@hybridlabor-api/aos 4.17.0 → 4.18.0

package/bin/guarded-patterns.json

@@ -0,0 +1,106 @@
+{
+  "version": 1,
+  "source": "go-gate.mjs GUARDED_PATTERNS (JavaScript RegExp syntax, lookaheads included; not RE2)",
+  "scopes": [
+    "push-feature",
+    "push-main",
+    "merge",
+    "publish",
+    "destructive",
+    "github-write"
+  ],
+  "patterns": [
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:git\\s+push|git(?:\\s+(?:-[cC]\\s*(?:\"[^\"]*\"|'[^']*'|\\S+)|--[\\w-]+(?:=(?:\"[^\"]*\"|'[^']*'|\\S+))?))+\\s+push)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?npm\\s+publish\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?npm\\s+version\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:gh\\s+pr\\s+merge|gh(?:\\s+(?:-R|--repo)(?:\\s+|=)\\S+)+\\s+pr\\s+merge)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:gh\\s+release\\s+create|gh(?:\\s+(?:-R|--repo)(?:\\s+|=)\\S+)+\\s+release\\s+create)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:git\\s+reset\\s+--hard|(?:git\\s+|git(?:\\s+(?:-[cC]\\s*(?:\"[^\"]*\"|'[^']*'|\\S+)|--[\\w-]+(?:=(?:\"[^\"]*\"|'[^']*'|\\S+))?))+\\s+)reset\\b[^;&|\\n]*\\s--hard)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:git\\s+clean|git(?:\\s+(?:-[cC]\\s*(?:\"[^\"]*\"|'[^']*'|\\S+)|--[\\w-]+(?:=(?:\"[^\"]*\"|'[^']*'|\\S+))?))+\\s+clean)\\b[^;&|\\n]*\\s(?:-[a-zA-Z]*f[a-zA-Z]*|--force)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?rm\\s+(?:[^;&|\\n]*\\s)?['\"]?(?:-[a-zA-Z]*[rR][a-zA-Z]*|--recursive)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:git\\s+branch|git(?:\\s+(?:-[cC]\\s*(?:\"[^\"]*\"|'[^']*'|\\S+)|--[\\w-]+(?:=(?:\"[^\"]*\"|'[^']*'|\\S+))?))+\\s+branch)\\b[^;&|\\n]*\\s(?:-[a-zA-Z]*D[a-zA-Z]*|-[a-zA-Z]*(?:df|fd)[a-zA-Z]*)(?=\\s|$)",
+      "flags": ""
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:git\\s+branch|git(?:\\s+(?:-[cC]\\s*(?:\"[^\"]*\"|'[^']*'|\\S+)|--[\\w-]+(?:=(?:\"[^\"]*\"|'[^']*'|\\S+))?))+\\s+branch)\\b(?=[^;&|\\n]*\\s(?:-d|--delete)\\b)(?=[^;&|\\n]*\\s(?:-f|--force)\\b)",
+      "flags": ""
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:git\\s+worktree|git(?:\\s+(?:-[cC]\\s*(?:\"[^\"]*\"|'[^']*'|\\S+)|--[\\w-]+(?:=(?:\"[^\"]*\"|'[^']*'|\\S+))?))+\\s+worktree)\\s+remove\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:gh\\s+|gh(?:\\s+(?:-R|--repo)(?:\\s+|=)\\S+)+\\s+)pr\\s+(?:create|comment|edit|review|close)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:gh\\s+|gh(?:\\s+(?:-R|--repo)(?:\\s+|=)\\S+)+\\s+)issue\\s+(?:create|comment)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:gh\\s+|gh(?:\\s+(?:-R|--repo)(?:\\s+|=)\\S+)+\\s+)release\\s+(?:edit|delete)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:gh\\s+|gh(?:\\s+(?:-R|--repo)(?:\\s+|=)\\S+)+\\s+)repo\\s+(?:create|edit|delete)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:gh\\s+|gh(?:\\s+(?:-R|--repo)(?:\\s+|=)\\S+)+\\s+)api\\b[^;&|\\n]*\\s(?:-X\\s*|--method[\\s=]+)(?:POST|PATCH|PUT|DELETE)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:gh\\s+|gh(?:\\s+(?:-R|--repo)(?:\\s+|=)\\S+)+\\s+)api\\b[^;&|\\n]*\\s(?:-[fF]|--field|--raw-field|--input)",
+      "flags": ""
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?git\\s+(?:-[cC]\\s*\\S+\\s+)*-c\\s*['\"]?alias\\.",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?opencode\\s+run\\b[^;&|\\n]*\\s(?:-[a-zA-Z]*[sc]\\S*|--session|--continue)(?=[\\s=]|$)",
+      "flags": ""
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?claude\\b[^;&|\\n]*\\s(?:-[a-zA-Z]*[cr]\\S*|--resume|--continue)(?=[\\s=]|$)",
+      "flags": ""
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?opencode\\s+attach\\b",
+      "flags": "i"
+    },
+    {
+      "source": "\\/session\\/[^\\s/'\"]+\\/(?:message|prompt_async|command|shell)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "\\/\\/[^\\s'\"]*\\/tui\\/|\\/tui\\/(?:append|submit|clear|execute|open|show|publish|control)",
+      "flags": "i"
+    }
+  ]
+}

package/commands/plan.md

@@ -2,4 +2,4 @@
 description: "Plan end to end: draft, render in plan-canvas or Plan Builder, annotate, await approval, then hand off."
 ---
 
-Run the full planning pipeline: 1) draft the plan with `concise-planning`; 2) always offer the choice between plan-canvas and Plan Builder (`visual-plan`) 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: $ARGUMENTS
+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: $ARGUMENTS

package/docs/codenotch.md

@@ -0,0 +1,44 @@
+# BDB AO Codenotch (macOS and Windows, default on)
+
+The AOS installer installs the BDB AO Codenotch desktop app by default on **macOS and Windows**. On Linux the step is never offered and no code of it runs.
+
+## Controlling it
+
+| Mode | Behavior |
+|---|---|
+| Interactive | Prompt "Install BDB AO Codenotch?", default **yes** |
+| Non-interactive (`-y`, no TTY) | Installs unless opted out |
+| Opt out | `AOS_CODENOTCH=0` or `--no-codenotch` (wins over everything) |
+| Force on | `AOS_CODENOTCH=1` or `--codenotch` (skips the question) |
+
+A failure at any step (no release yet, 404, offline, rate limit, checksum mismatch, mount error) prints a warning and the AOS install continues; the exit code is never affected. The installer ends with one line saying whether Codenotch was installed, skipped or failed, and how to remove it.
+
+## Windows
+
+- Asset: `Codenotch-Setup-<version>.exe` plus `Codenotch-Setup-<version>.exe.sha256` from the same release. If the exact name is absent, the single `*Setup*.exe` that has a matching `.sha256` is used; anything ambiguous is refused.
+- The SHA-256 is verified before the installer runs; a mismatch only warns.
+- Runs the NSIS installer silently as `Setup.exe /S`, per-user, no admin, no elevation, with a 5 minute timeout, then checks the version in the per-user uninstall registry key (`HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall`, key `Codenotch`, fallback scan for a subkey whose DisplayName is Codenotch).
+- Installed version same or newer: skipped. An older install AOS did not record is kept unless you confirm interactively.
+- The path of the uninstaller and the version are recorded in `~/.agents/.bdb-codenotch.json` (`%USERPROFILE%` on Windows).
+- `aos-uninstall` runs `<recorded uninstall.exe> /S` only if that file still exists and the registry version and uninstaller path still match the record; otherwise the install is left alone.
+- Default install dir is `%LOCALAPPDATA%\Codenotch` (codenotch.exe, codenotch-hook.exe, uninstall.exe). The installer is unsigned, so Windows SmartScreen may warn.
+- **Unverified:** the registry key (`Codenotch`), `DisplayVersion`, `UninstallString`, and the silent `/S` install and uninstall come from Tauri's stock NSIS template, not from a real build. They must be checked on Windows with the first CI-built installer.
+
+## What it does (macOS)
+
+1. Reads the release list of the public repo `hybridlabor-api/bdb-ao-codenotch` (`https://api.github.com/repos/hybridlabor-api/bdb-ao-codenotch/releases`, unauthenticated) and picks the newest release that is neither draft nor prerelease and carries this platform's asset plus a `.sha256`; other releases are ignored. A missing repo (404), no matching release, or a GitHub rate limit prints a friendly note and the install continues; nothing fails.
+2. Downloads the `.dmg` and verifies its `.sha256` asset from the same release **before** mounting. A mismatch or a missing checksum refuses the install.
+3. Mounts with `hdiutil attach -nobrowse -readonly -mountpoint <temp dir>` and always detaches again, even on failure.
+4. Copies the single `.app` from the DMG to `/Applications`, or to `~/Applications` when `/Applications` is not writable. Never uses sudo.
+5. Runs `xattr -dr com.apple.quarantine` on the copy. The app is **ad-hoc signed** until Apple developer certificates are in place, so Gatekeeper would otherwise block it.
+6. Records path, version and bundle id in `~/.agents/.bdb-codenotch.json`.
+
+## Idempotence and safety
+
+- Installed version same or newer (`CFBundleShortVersionString`): skipped.
+- Older and installed by AOS (recorded path, bundle id and version still match): asked in interactive mode, replaced automatically with `AOS_CODENOTCH=1`. The old copy is restored if the new copy fails.
+- Older and not installed by AOS: kept with a note in non-interactive mode; in interactive mode replaced only after you confirm.
+
+## Uninstall
+
+`aos-uninstall` removes only the recorded `.app`, and only while its bundle id and version still match the record. A replaced or otherwise unknown app is kept. `--dry-run` lists the decision.

package/docs/codex-gate-smoke.md

@@ -0,0 +1,43 @@
+# Codex hook smoke test (plan only, not run)
+
+Question: does a `PreToolUse` hook fire (a) under `codex exec` and (b) under `aos-acp codex`? If it fires, `go-gate.mjs` is the inner gate for Codex like it is for agy and OpenCode. If it does not under ACP, `aos-acp` stays the only gate for Codex and keeps refusing guarded commands without a GO token.
+
+**Status: nothing here has been run.** Codex calls a paid API, so the test needs a working login and your knowledge. Everything below that says UNVERIFIED stays that way until `scripts/codex-gate-smoke.mjs --run` was executed and the result is written in the table at the end.
+
+## What is known (codex-cli 0.154.0, from the plan's section 9b)
+
+- `codex features list` shows `hooks stable true`; events include PreToolUse, PermissionRequest, PostToolUse, SessionStart, UserPromptSubmit, Stop.
+- Config: `[[hooks.PreToolUse]]` with `matcher` (regex on the tool name) and `[[hooks.PreToolUse.hooks]]` with `type = "command"`, `command`, `timeout` in `~/.codex/config.toml`.
+- Deny: exit 2 with the reason on stderr, or JSON `decision: "block"` with a reason. `go-gate.mjs` already does this for Codex.
+- Codex keeps a trust state per hook (`--dangerously-bypass-hook-trust` exists). New or changed hooks probably need your approval: **UNVERIFIED**.
+- Hook input: `transcript_path`, `prompt`, `tool_input.command` confirmed; `session_id` and `tool_name` not confirmed.
+
+## Installer
+
+The default install already writes the go-gate `[[hooks.PreToolUse]]` stanza (matcher `^(Bash|run_command)$`) into the Codex `config.toml` block between `# AOS:HOOKS:START` and `# AOS:HOOKS:END`. `aos --codex-gate` prints exactly that stanza plus the trust note and exits without writing anything, so you can inspect or copy it. Codex asks you to trust new or changed hooks; approve the go-gate hook there or it stays inactive.
+
+## Procedure
+
+`node scripts/codex-gate-smoke.mjs` prints the plan and executes nothing. `AOS_CODEX_SMOKE=1 node scripts/codex-gate-smoke.mjs --run` runs it in a throwaway `CODEX_HOME` with a probe hook that appends each hook call to a marker file (and denies a command containing `SMOKE_DENY`). Log in inside that `CODEX_HOME` yourself; the script never reads `~/.codex`. `--bypass-trust` adds `--dangerously-bypass-hook-trust` to the Codex calls.
+
+| Step | Command shape | Pass |
+|---|---|---|
+| exec-fires | `codex exec ... "Run the shell command: echo smoke-ok"` | marker has a line for that command |
+| exec-denies | same with `echo SMOKE_DENY` | marker line exists and the command did not run |
+| acp-fires | `aos-acp codex --name smoke --cwd <dir> --allow-default allow --prompt "Run the shell command: echo smoke-acp"` | marker has a line for that command |
+
+The `CODEX_HOME` variable and the `-C` flag of `codex exec` are assumed from general knowledge of the CLI and are UNVERIFIED; adjust the plan if Codex rejects them.
+
+## Decision after the run
+
+- exec fires, ACP fires: wire go-gate as the inner gate for Codex under ACP; `aos-acp codex` can then default to `--no-consume` like claude and opencode (the hook consumes the token).
+- exec fires, ACP does not: keep `aos-acp codex` as the gate (`consume` stays on); document that Codex workers are covered only by `aos-acp`.
+- exec does not fire: check the trust state first; otherwise Codex has no inner gate at all.
+
+## Results
+
+| Step | Date | Codex version | Result |
+|---|---|---|---|
+| exec-fires | | | UNVERIFIED |
+| exec-denies | | | UNVERIFIED |
+| acp-fires | | | UNVERIFIED |

package/docs/delegation-routing.md

@@ -0,0 +1,32 @@
+# Delegation routing: which channel for which job
+
+AOS works without AO. Pick the channel by the job, not by habit.
+
+| Job | Channel | Why |
+|---|---|---|
+| One-shot task for another harness (research, review, a bounded edit) | `mcsc` (`delegate_opencode`, `delegate_codex`, `delegate_agy`) | one call, one answer, live events on agenttrail |
+| A worker that may need a GO (push, merge, publish, destructive) | `aos-acp` | ACP client: guarded commands need a GO token for the worker name, `--go-wait` parks the request, events go to agenttrail and `~/.aos/acp/<name>.jsonl` |
+| A message to an OpenCode session that is already running | `aos-bus` | `aos-bus send <name> <text>`; OpenCode only, never counts as a human GO |
+| A durable fleet of long-lived workers across repos | AO (optional) | the daemon, dashboard and worktrees; AOS must keep working without it |
+
+Both `mcsc` and `aos-acp` write the same event protocol to agenttrail (`SessionStart`, `PreToolUse`, `PostToolUse`, `SessionEnd`), so the GO board reads one source.
+
+## Limits that apply to every row
+
+- **mcsc is one level deep.** Every adapter sets `MCSC_DEPTH` to the caller's depth plus one; a server that starts at depth 1 or more refuses all delegation. A delegated agent cannot delegate again.
+- **`delegate_agy` is read-only until tested.** Use it for research, review and analysis. Its `write` flag (`--mode accept-edits`) is untested and not part of the contract.
+- **`opencode run --auto` auto-approves tool calls.** It skips the permission prompt, so nothing but the gate hooks stands between the worker and a guarded command. Prefer `aos-acp opencode` (permissions answered by the GO rules) or `mcsc`; use `--auto` only in a throwaway worktree with the go-gate plugin loaded, and never to run a guarded action.
+- **agy over ACP:** no sanctioned adapter (`antigravity-acp` breaches Google's Antigravity terms). Use `mcsc` or adopt an agy session.
+- **A GO is not inherited.** A worker, subagent or delegated run never gets its caller's GO; a blocked command is not retried without a fresh one.
+- **Coverage:** `aos-acp` sees only what the agent asks permission for. A worker running with permissions bypassed asks for nothing, so the hook inside the harness stays the main layer. Hook firing under ACP is verified for Claude only; for Codex it is UNVERIFIED (`docs/codex-gate-smoke.md`).
+
+## The `opencode-subagent` skill
+
+That skill is installed under `~/.agents/skills/` and is not part of this repository, so it cannot be changed from here. Its text should say:
+
+- delegate with `mcsc` (`delegate_opencode`) for one-shot tasks and `aos-acp opencode --name <worker> --cwd <worktree> --prompt "<task>"` for workers that may need a GO;
+- warn that `opencode run --auto` auto-approves tool calls and bypasses the permission prompt, and name the exception above.
+
+## For AO
+
+AO is an optional consumer. A bounded call to `~/.aos/bin/go-check.mjs` decides whether a guarded command may run (`docs/go-check.md`). AOS documents AO only as the last row of the table.

package/docs/go-check.md

@@ -0,0 +1,60 @@
+# go-check: one GO check for callers that are not a hook
+
+`go-check.mjs` answers "may this worker run this guarded command?" with the same classifier and token logic as `go-gate.mjs`, so AO (or any other supervisor) does not rebuild transcript and token handling. The installer places it at a fixed path you can find without running `aos` (an `aos` call starts the installer):
+
+```
+~/.aos/bin/go-check.mjs          the CLI
+~/.aos/bin/go-gate.mjs           copy it imports (same directory)
+~/.aos/bin/guarded-patterns.json the guarded patterns, for reference
+```
+
+Source: `bin/go-check.mjs`, `bin/guarded-patterns.json` (regenerate with `node bin/go-check.mjs --write-patterns bin/guarded-patterns.json`; a test fails on drift).
+
+## Call
+
+```
+node ~/.aos/bin/go-check.mjs --session <Name> --command "<shell string>" [--consume]
+```
+
+- `--session` is the stable worker slug (`AOS_SESSION_NAME`). The token for `GO <Name>` is looked up under that name.
+- `--command` is a **shell string**, not an argv array. The patterns are anchored on `^`, `;`, `|`, `&&`, `$(`, backticks and wrappers (`sudo`, `env`, `bash -c`, ...). The caller must build the string from its provider's tool input (for ACP, `RawInput`). If the form of an `execute` call is unknown, treat it as guarded-unknown: hand it to the human approval surface, never allow it automatically.
+- Without `--consume` the token is only verified. With `--consume` it is used up (one token, one guarded command). Pass `--consume` only on the final allow.
+
+## Output and exit codes
+
+stdout is one JSON line: `{"guarded": bool|null, "ok": bool, "scope": [...]|null, "reason": "..."}`.
+
+| Exit | Meaning | Caller |
+|---|---|---|
+| 0 | allowed: not guarded, or a valid GO token (consumed with `--consume`) | allow |
+| 1 | guarded and no valid GO (also: the command touches the GO/grant store) | hand over to the human surface |
+| 2 | error (bad arguments, missing `go-gate.mjs`, unreadable state) | treat as denied, never allow |
+
+`scope` is the list of grant scopes the command needs (`push-feature`, `push-main`, `merge`, `publish`, `destructive`, `github-write`), or `null` when a guarded part has no scope. Scopes are informational here: they do not select a grant.
+
+## What it deliberately does not do
+
+- **Tokens only (v1).** A valid `~/.aos/go/<Name>.token` (under 10 min old, names this session, master transcript still ends with that `GO <Name>`, not yet used) covers any guarded command, including `gh pr merge 117`. `GO #117` style PR-scoped GOs live in the transcript path of `go-gate.mjs` and are not read here.
+- **Mode `soft` grants are never read.** They belong to the human session (`~/.aos/gate`), and a worker must not be able to use them.
+- **Mode `off` never applies.** go-check does not look at the gate store at all.
+- **It never mints a token.** With `AOS_ACP_CLIENT=1` (set in every AO worker environment) the result is the same: no token is written anywhere. Tokens are created only by the `UserPromptSubmit` hook `go-token.mjs` from a human-typed `GO <Name>`.
+- **No network, no stdin, no subprocess.** One call takes roughly 60 to 150 ms. Callers should still apply their own timeout (3 s suggested); a timeout counts as exit 2.
+
+## Coverage limits (inherited, say them out loud)
+
+- The ACP client only sees what the agent asks for. `bypassPermissions` never sends `session/request_permission`, and a TUI (PTY) session has no AO interception point. The hook inside the harness stays the main layer; go-check is the second layer for harnesses without hooks.
+- Whether Claude's hook fires under `bypassPermissions`, and whether Codex hooks fire under ACP, is UNVERIFIED (see `docs/codex-gate-smoke.md`).
+- A token that is still valid is not bound to one command: it covers the next guarded command the worker asks about. `--consume` makes it one command.
+
+## Patterns file
+
+`guarded-patterns.json` holds `{version, source, scopes, patterns: [{source, flags}]}` in JavaScript RegExp syntax. It uses lookaheads, which Go's RE2 does not support, so do not port it. Call go-check instead; the file exists so AO can show or diff the list.
+
+## Failure cases for AO
+
+| Situation | Behaviour |
+|---|---|
+| `~/.aos/bin/go-check.mjs` missing (AOS not installed) | feature off, AO behaves as before |
+| installed, exit 2, no `node`, or timeout | do not allow; hand over |
+| exit 1 | hand over to the approval surface |
+| exit 0 | allow; `--consume` only at the final allow |

package/docs/master-session-acp.md

@@ -42,6 +42,8 @@ Double gate: opencode and claude workers also run their own AOS gate inside the
 
 `~/.aos/acp/<name>.jsonl` (override `--log`): `start`, `send`, `initialized`, `session`, `text`, `tool_call`, `tool_call_update`, `permission_pending`, `permission`, `done`, `error`, `agent_stderr`. The master builds its roster and GO board for ACP workers from these files; `ListAgents` does not see them.
 
+The same run is also posted to agenttrail with mcsc's protocol (`mcps/mcsc/packages/core/src/trail.js`): `SessionStart` and `SessionEnd` (session id `aos-acp-<pid>-<ms>`, agent `<adapter>:<name>`), and `PreToolUse` / `PostToolUse` per ACP `tool_call` / `tool_call_update` (`tool_name` from the ACP `kind`, `tool_input.file_path` from `locations`, `tool_input.command` from `rawInput`). Best effort, 300 ms per port, `AGENTTRAIL_PORT` overrides the 5330 to 5344 scan.
+
 ## Open points
 
 - Codex live run not verified (auth). With `OPENAI_API_KEY` or a ChatGPT login it should pass the same smoke.

package/docs/opencode-setup.md

@@ -29,6 +29,24 @@ AOS_OPENCODE_OPTIONAL=ponytail,loop,rtk aos        # or: aos --opencode-optional
 
 Entries are appended only when no entry for that package exists, after a timestamped `opencode.jsonc.<ts>.bak` backup. AOS never runs foreign installers (the `opencode-loop` npx installer rewrites the config) and skips `orca-opencode-status.js` (the Orca app maintains it) and `dag.jsonc` / GraphAgent (AGPL engine, different program).
 
+## Optional permission (off by default)
+
+```bash
+AOS_OPENCODE_PERMISSION=external_directory aos     # or: aos --opencode-permission=external_directory
+```
+
+Without it OpenCode asks on every access outside the working directory, including `~/.agents` skills. The opt-in sets only `permission.external_directory`, scoped to AOS paths:
+
+```json
+"permission": { "external_directory": { "~/.agents/**": "allow", "~/.config/opencode/**": "allow" } }
+```
+
+- An existing `permission.external_directory` (any form) is left untouched and a note is printed. A string `permission` (for example `"allow"`) is refused, not replaced. Unparseable config is refused.
+- A timestamped `.bak` backup is made before the change; a second run changes nothing and makes no backup. Writing the config drops `//` comments, as with every other AOS config write.
+- Schema evidence: the OpenCode 1.18.30 binary accepts a string or a pattern record for `external_directory`, and the permissions docs show `~` and `$HOME` expansion in patterns. Whether the `**` globs match the AOS paths on your machine was not run against a live OpenCode.
+- Uninstall: AOS does not record this key, so it stays in place as your config. Remove it by hand.
+- Nothing else is touched: no other `permission` key and no `mcp` entry.
+
 ## Known limits
 
 - **`/loop-shell` and the go-gate (unverified).** `opencode-loop` can run shell commands as child processes. `tool.execute.before`, where the AOS go-gate sits, may never see them. Do not schedule `git push`, publish or other gated commands through them. The installer prints this warning whenever `opencode-loop` is in `plugin[]`.