@hybridlabor-api/aos 4.16.0 → 4.18.0

package/docs/codex-agy-setup.md

@@ -0,0 +1,16 @@
+# Codex and Antigravity (agy) plugin setup
+
+Both manifests are generated from `plugin-commands.json` by `node scripts/build-plugin-manifest.mjs` and checked by `--check` (stale or missing files, version drift against `package.json`, referenced files, no `disable-model-invocation` in any Codex output).
+
+## Codex
+
+- **Load:** `codex plugin marketplace add <path-to-this-repo>` (it reads `.agents/plugins/marketplace.json`), then `codex plugin add bdb-aos@bdb-aos`.
+- **Invoke:** `$bdb-aos:<cmd>`, for example `$bdb-aos:setup`. Codex has no `/` command for plugin skills.
+- **How it is built:** each command becomes a wrapper skill in `plugins/bdb-aos-codex/skills/<cmd>/SKILL.md`. The plugin ships only these wrappers; the 200+ AOS skills reach Codex through the installer's `~/.codex/skills` copies, and a wrapper tells the model which one to run.
+- **Bodies:** `bodies.codex` is optional; without it the Claude body is used with `/bdb-aos:<cmd>` rewritten to `$bdb-aos:<cmd>`.
+
+## Antigravity (agy)
+
+- **Load:** `agy plugin install` against `plugins/bdb-aos` (its `plugin.json` sits at the plugin root), or `agy plugin validate plugins/bdb-aos` to check it.
+- **Invoke:** `/bdb-aos:<cmd>`, for example `/bdb-aos:setup`.
+- **Bodies:** commands reuse `commands/<cmd>.md`. A command with `bodies.agy` is written to `agy-commands/<cmd>.md` and wired instead.

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

@@ -0,0 +1,54 @@
+# OpenCode setup
+
+The AOS installer copies these into `~/.config/opencode` (`%APPDATA%\opencode` on Windows):
+
+- `plugins/bdb-aos.js` with `plugins/aos-hooks/` and `plugins/lib/` (go-gate, loop keeper, bus)
+- `commands/startcycle-graph.md` and one generated `commands/bdb-aos-<cmd>.md` per AOS command, called as `/bdb-aos-<cmd>` (flat hyphen names; a colon is not valid in Windows file names)
+
+The command files are generated from `plugin-commands.json` by `node scripts/build-plugin-manifest.mjs` and checked by `--check`. A command may carry `bodies.opencode`; without it the Claude body is used with `/bdb-aos:<cmd>` rewritten to `/bdb-aos-<cmd>`.
+
+## Updating and your edits
+
+- A command file you edited is kept; the shipped version lands next to it as `<file>.new`.
+- A file that already existed under a shipped name but was never installed by AOS is kept the same way.
+- The installer never deletes files it did not create.
+
+## Lean MCP set
+
+OpenCode deliberately runs a small MCP set (`memb_mcp`, `deja`, `zavora_computer_use`). AOS never copies other harnesses' MCP lists into OpenCode and never adds ComfyUI or show-control MCPs there. Media playbooks stop with "Missing MCP" on OpenCode by design.
+
+## Optional components (off by default)
+
+```bash
+AOS_OPENCODE_OPTIONAL=ponytail,loop,rtk aos        # or: aos --opencode-optional=ponytail,loop,rtk
+```
+
+- `ponytail`: appends `@dietrichgebert/ponytail@4.10.0` to `plugin[]`
+- `loop`: appends `@bybrawe/opencode-loop@0.6.2` to `plugin[]`
+- `rtk`: prints `brew install rtk && rtk init -g --opencode`; AOS installs nothing
+
+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[]`.
+- **Machine prompts are never human.** Every prompt the plugin sends itself (loop nudge, bus wake) is `synthetic` and carries `aos_loop` or `aos_bus` metadata, so it cannot count as a GO. A test scans the plugin source for this.
+- **Double loading of `bdb-aos.js`.** OpenCode auto-loads `plugins/*.{ts,js}` and also loads paths in `plugin[]`. From the 1.18.30 binary strings: both lists are merged through one de-duplication keyed on the `file://` URL, so the same absolute path loads once (read from the binary, not observed by running OpenCode). A differently spelled second path (checkout path, symlinked config dir) would load twice, giving two gates and two loop keepers. The installer registers exactly one path, `<config>/plugins/bdb-aos.js`, and warns when `plugin[]` holds another spelling.

package/docs/plugin-migration.md

@@ -0,0 +1,61 @@
+# Plugin registration and loose-copy migration
+
+The installer registers the `bdb-aos` plugin for Claude Code, then removes only its own loose skill copies there. Hooks, MCP servers, `trail-autostart` and the bus stay in the installer, so disabling the plugin never disables the go-gate.
+
+| Harness | Loose copies | Why |
+|---|---|---|
+| Claude Code | **removed** from `~/.claude/skills` only after registration **and** evidence that Claude Code installed the plugin | the plugin bundles the skills |
+| Codex | stay (`~/.codex/skills`) | the Codex plugin bundles only the command wrapper skills; nested skill scanning is unverified |
+| agy | stay (`~/.gemini/config/skills`) | skill bundling is unverified (`agy plugin validate` processed 9 skills) |
+| OpenCode | stay | plugins cannot bundle skills |
+| all | `~/.agents/skills` always stays as the shared store | |
+
+## Rules
+
+- **Registration first, evidence second.** Registration means `settings.json` holds the marketplace and `enabledPlugins` keys; that alone proves nothing about an installed plugin. Copies are removed only when Claude's plugin state shows the install: an entry for `bdb-aos@bdb-marketplace` in `~/.claude/plugins/installed_plugins.json`, or a cache directory `~/.claude/plugins/cache/bdb-marketplace/bdb-aos/<version>`. Either way the directory must resolve (realpath) under `~/.claude/plugins`, must not be cached from another (older external) marketplace, and must contain `skills/<name>/SKILL.md` for a skill the install manifest lists for `~/.claude/skills`. `installPath: "/"`, an empty `skills` dir or a path elsewhere do not count. The `installed_plugins.json` shape (`{version, plugins: {"<name>@<marketplace>": [{installPath, ...}]}}`) is verified against other plugins on a local machine; that `bdb-aos` writes the same shape and the cache layout fallback are **inferred**, not observed.
+- **Not verifiable yet.** The installer registers the plugin, keeps every copy and prints "restart Claude Code, then run the installer again to retire the loose copies". The retirement happens on a later run once the evidence exists. Until then the installer keeps writing `~/.claude/skills` as before.
+- **Ordering.** The migration runs before the install target loop. Once Claude is covered, `~/.claude/skills` is not written again, so a rerun changes nothing and creates no backup.
+- **Merge, never overwrite.** Other keys survive. `settings.json` is backed up (`settings.json.<ts>.bak`) before a change; an unchanged file is not rewritten. A symlinked `settings.json` is written through to its real file and stays a link.
+- **Opt-out.** `"bdb-aos@bdb-marketplace": false` in `enabledPlugins` (or `bdb-aos@<old external key>: false`): nothing is registered, nothing is removed.
+- **Own copies only, safely resolved.** A file is removed when the install manifest lists it and its bytes still match the recorded hash. Keys with `..` or relative paths are rejected; each file and the root are resolved with `path.resolve` and `fs.realpathSync`, the real file must be a regular file under the real root. If `~/.claude/skills` itself is a symlink, nothing is removed. Edited files and files not in the manifest stay.
+- **All or nothing.** If any listed copy is edited or unsafe, nothing is removed, Claude is not treated as covered, the installer names the skills involved and keeps updating the copies it owns. Move your edits out and run the installer again to retire them.
+- **OpenWiki daemon.** `openwiki-skill/scripts/` is never retired, and the daemon is installed and run from the installer-owned `~/.agents/skills/openwiki-skill/scripts` (copied there when missing), so scheduled jobs never point into `~/.claude/skills`.
+- **Malformed settings.** If `enabledPlugins` or `extraKnownMarketplaces` exists but is not a plain object, registration is refused and nothing is written.
+- **One at a time.** A lock file (`~/.agents/.bdb-plugin-migration.lock`, stale after ten minutes or a dead pid) keeps two migrations apart; a file that vanishes mid-run is skipped.
+- **Backup before removal.** Removed files are copied to `~/.agents/backups/plugin-migration-<timestamp>/` keeping their path relative to `$HOME`.
+- **External marketplace.** An entry pointing at `hybridlabor-api/bdb-marketplace` is replaced by this repo's marketplace (`hybridlabor-api/aos`) only when no other plugin id uses it. Only `bdb-aos@<oldkey>` is renamed to `bdb-aos@bdb-marketplace`; other plugins' ids are never renamed. A foreign marketplace that also lists other plugins stays in place. If the name `bdb-marketplace` itself is that external marketplace with other plugins, or points at another source, registration is refused with a message and nothing changes. Nothing on GitHub is changed.
+- **Old command files.** Command files from earlier versions that are no longer in the generated table are not touched by the migration; they are neither removed nor backed up. Only the generated `commands/` set is kept in sync by `scripts/build-plugin-manifest.mjs`.
+- **State.** `~/.agents/.bdb-plugin-migration.json` records each change: `addedMarketplace`, `addedEnabled`, `replaced`, `renames`, `keptForeign`. Deregistering reverses exactly those.
+
+## Packaging
+
+The npm package ships `plugins/bdb-aos-codex/` (a real directory) and the root manifests (`plugin.json`, `.codex-plugin/`, `.agents/plugins/marketplace.json`, `commands/`, `agy-commands/`). `plugins/bdb-aos/` is built from symlinks and is **not** in the npm package. The Claude Code plugin directory (`.claude-plugin/` and `plugins/bdb-aos/`) is git-only: Claude installs it from the GitHub marketplace `hybridlabor-api/aos`, not from npm. `.agents/plugins` (the Codex marketplace file) is excluded from the `.agents` copies into `~/.agents` and project directories.
+
+The root `.codex-plugin/.mcp.json` is no longer referenced: the previous manifest pointed at it through an `mcp_config` key, which real Codex plugins do not use (they use `mcpServers`). It stays unreferenced on purpose, because the installer already registers the MCP servers in Codex's config and the plugin would register them twice. The plugin therefore delivers no MCP servers.
+
+## Opt out and preview
+
+```bash
+AOS_PLUGIN_MIGRATION=off   npx -y @hybridlabor-api/aos@latest   # skip entirely
+AOS_PLUGIN_MIGRATION=check npx -y @hybridlabor-api/aos@latest   # report only
+npx -y @hybridlabor-api/aos@latest --plugin-migration=off|check
+```
+
+`--dry-run` implies `check`. Default is on.
+
+## Undo
+
+```bash
+aos-uninstall --restore-plugin-backup   # puts removed files back, never overwrites an existing file
+aos-uninstall                           # also removes the plugin registration it added and restores a replaced external marketplace
+```
+
+## Known limits
+
+- The lock guards migrations only. An installer copy running at the same moment in another process is not serialized; a file removed under it is skipped, and the next run reconciles.
+- Until Claude Code shows the plugin as installed, both copies exist; skills may then appear twice after the plugin loads and before the next installer run retires the copies.
+- `aos-doctor` accepts the plugin evidence as Claude having the skills.
+- A deregister that reverses a marketplace rename keeps the content of `enabledPlugins` but may reorder its keys (cosmetic).
+- Restoring a backup after an uninstall creates a new install manifest and puts the legacy `~/.claude/skills/startcycle` marker back, so AOS is detected as installed again.
+
+Backups survive uninstall (the state keeps its backup index and `~/.agents/backups/plugin-migration-*` is scanned), so `--restore-plugin-backup` also works afterwards. Restored files are recorded in the install manifest, and the restore deregisters the plugin so skills are not loaded twice; the restore also sets `bdb-aos@bdb-marketplace` to `false` in `settings.json` (the opt-out), so the next installer run does not register the plugin or retire the restored files. Set it back to `true` to migrate again.