@hybridlabor-api/aos 4.15.0 → 4.17.0

package/installer.js

@@ -23,6 +23,7 @@ const net = require('net');
 const readline = require('readline');
 const util = require('util');
 const crypto = require('crypto');
+const pluginMigration = require('./lib/plugin-migration');
 
 function verifyDaemonListening(port, name, timeoutMs = 4000) {
     return new Promise((resolve) => {
@@ -497,8 +498,8 @@ const CORE_MCP = 'memb-mcp';
 // compared against: (a) the SOURCE hash (unmodified) and (b) the MANIFEST
 // hash (last-installed value).  This gives us three cases:
 //   ours + unmodified  → source_hash == disk_hash          → overwrite + update manifest
-//   ours + user-edited → manifest_hash == source_hash,
-//                        but disk_hash != source_hash       → .bak + warn + write
+//   ours + user-edited → disk_hash != manifest_hash         → keep user file,
+//                                                             write <file>.new
 //   foreign            → no manifest record AND disk_hash
 //                        not in any known source hash       → skip + warn
 
@@ -560,8 +561,11 @@ function adoptFileIntoManifest(manifest, targetPath, sourceHash) {
     };
 }
 
+// User-edited files this run left untouched (shipped copy written as <file>.new).
+const keptUserEdits = [];
+
 // Manifest-aware file writer implementing the three-way conflict policy.
-// Returns 'wrote' | 'bak' | 'skipped'.
+// Returns 'wrote' | 'bak' | 'kept' | 'skipped'.
 // knownSourceHashes: Set of sha256 hashes of all source files in the current
 // payload (used to identify files we recognise even before manifest entry).
 function resolveFileConflict(sourcePath, targetPath, manifest, knownSourceHashes) {
@@ -627,15 +631,13 @@ function resolveFileConflict(sourcePath, targetPath, manifest, knownSourceHashes
     }
 
     // Case: ours + user-edited (manifest recorded our hash, but disk now differs).
+    // The user's file wins: the shipped version lands next to it as .new, and
+    // the manifest keeps the old hash so the next run still sees the edit.
     if (manifestEntry && diskHash !== manifestEntry.sha256) {
-        const bakPath = `${targetPath}.${timestamp}.bak`;
-        try { fs.copyFileSync(targetPath, bakPath); } catch (e) {
-            log.warn(`[manifest] Could not create backup ${bakPath}: ${e.message}`);
-        }
-        fs.copyFileSync(sourcePath, targetPath);
-        manifest[targetPath] = { path: targetPath, sha256: sourceHash, version: pkg.version, installedAt: new Date().toISOString() };
-        log.warn(`[manifest] User-edited file backed up to ${bakPath}, new version written.`);
-        return 'bak';
+        const newPath = `${targetPath}.new`;
+        fs.copyFileSync(sourcePath, newPath);
+        keptUserEdits.push(targetPath);
+        return 'kept';
     }
 
     // Default: manifest entry present, disk matches manifest (no change needed) – overwrite.
@@ -765,6 +767,17 @@ function pruneRemovedSkills(manifest) {
 
 function flushSessionManifest() {
     if (_sessionManifest) saveInstallManifest(_sessionManifest);
+    reportKeptUserEdits();
+}
+
+function reportKeptUserEdits() {
+    if (keptUserEdits.length === 0) return;
+    log.warn([
+        `${keptUserEdits.length} file(s) you edited were KEPT; the shipped version is next to each as <file>.new:`,
+        ...keptUserEdits.map((p) => `  ${p}`),
+        'Merge or delete the .new files when convenient.',
+    ].join('\n'));
+    keptUserEdits.length = 0;
 }
 
 // skills/global_legacy/ has not existed in the shipped payload for a long
@@ -1265,9 +1278,94 @@ function reportFatal(stage, e) {
     process.exitCode = 1;
 }
 
+// AOS_PLUGIN_MIGRATION=off skips plugin registration and loose-copy removal; =check only reports.
+function pluginMigrationMode(argv = process.argv, env = process.env) {
+    const flag = argv.find((a) => a.startsWith('--plugin-migration='));
+    const raw = String(flag ? flag.slice('--plugin-migration='.length) : (env.AOS_PLUGIN_MIGRATION || '')).trim().toLowerCase();
+    if (raw === 'off' || raw === '0' || raw === 'false') return 'off';
+    return raw === 'check' || DRY_RUN ? 'check' : 'on';
+}
+
+// .agents/plugins holds the Codex marketplace file; it belongs to the repo checkout, not to ~/.agents or a project.
+const AGENTS_COPY_EXCLUDE = ['plugins'];
+
+let _pluginMigration = null;
+function runPluginMigration({ targetHome = homeDir, detected = null, mode = pluginMigrationMode(), registrars } = {}) {
+    if (_pluginMigration && targetHome === homeDir) return _pluginMigration;
+    const keys = detected || detectPlatforms().map((d) => d.key);
+    const ownsManifest = !_sessionManifest;
+    const manifest = _sessionManifest || loadInstallManifest();
+    let result;
+    try {
+        result = pluginMigration.migrate({ home: targetHome, manifest, detected: keys, mode, ...(registrars ? { registrars } : {}) });
+    } catch (e) {
+        log.warn(`Plugin migration skipped: ${e.message}`);
+        result = { covered: new Set(), lines: [] };
+    }
+    for (const line of result.lines) log.step(line);
+    if (ownsManifest && mode === 'on') saveInstallManifest(manifest);
+    if (targetHome === homeDir) _pluginMigration = result;
+    return result;
+}
+
+// The plugin migration runs first: when it retires Claude's loose copies, ~/.claude/skills is not
+// written again, so a rerun neither recreates nor re-backs-up what the plugin now delivers.
+function installTargetSkills(targets, { mode, backupDir, excludeSkills, skillsBase }) {
+    const detected = detectPlatforms().map((d) => d.key);
+    if (targets.some((t) => t.value === '2') && !detected.includes('claudecode')) detected.push('claudecode');
+    const pluginCovered = runPluginMigration({ detected }).covered;
+
+    for (const t of targets) {
+        const viaPlugin = t.value === '2' && pluginCovered.has('claudecode');
+        if (mode === 'replace') {
+            if (!viaPlugin) {
+                moveIfExists(t.targetSkillDir, path.join(backupDir, `config_skills_backup_${t.value}`), `global config skills (${t.value})`);
+                moveIfExists(t.targetLegacyDir, path.join(backupDir, `legacy_skills_backup_${t.value}`), `legacy skills (${t.value})`);
+            }
+            moveIfExists(t.targetWorkspaceDir, path.join(backupDir, `workspace_skills_backup_${t.value}`), `workspace skills (${t.value})`);
+        }
+
+        installStep(`create the skill target directories (${t.value})`, () => {
+            if (!viaPlugin) {
+                fs.mkdirSync(t.targetSkillDir, { recursive: true });
+                retireObsoleteLegacyDir(t.targetLegacyDir);
+            }
+            fs.mkdirSync(t.targetWorkspaceDir, { recursive: true });
+        }, 'The skill copies below will most likely be skipped as well.');
+
+        if (fs.existsSync(skillsBase)) {
+            installStep(`install the skills (${t.value})`, () => {
+                const rawDirs = fs.readdirSync(skillsBase);
+                const dirs = rawDirs.sort((a, b) => {
+                    const aIsLeaf = fs.existsSync(path.join(skillsBase, a, 'SKILL.md'));
+                    const bIsLeaf = fs.existsSync(path.join(skillsBase, b, 'SKILL.md'));
+                    if (aIsLeaf && !bIsLeaf) return 1;
+                    if (!aIsLeaf && bIsLeaf) return -1;
+                    return 0;
+                });
+                for (const dir of dirs) {
+                    const fullPath = path.join(skillsBase, dir);
+                    if (!fs.statSync(fullPath).isDirectory()) continue;
+
+                    if (viaPlugin && dir !== 'workspace_agents') continue;
+                if (dir === 'global_legacy') {
+                        copyDirRecursiveSync(fullPath, t.targetLegacyDir, excludeSkills);
+                    } else if (dir === 'workspace_agents') {
+                        copyDirRecursiveSync(fullPath, t.targetWorkspaceDir, excludeSkills);
+                    } else {
+                        syncSkillEntry(fullPath, dir, t.targetSkillDir, excludeSkills);
+                    }
+                }
+                log.step(`Installed all global config & core skills to ${t.targetSkillDir}`);
+            }, 'The skills are missing or incomplete; the rest of the installation continues.');
+        }
+    }
+}
+
 function syncSkillsToGlobalHarnesses(excludeSkills = []) {
     const skillsBase = path.join(srcDir, 'skills');
     if (!fs.existsSync(skillsBase)) return;
+    const pluginCovered = runPluginMigration().covered;
 
     // Mirror only into harnesses that are actually present. This list used to
     // be unconditional, which both wrote skills nobody would read and planted
@@ -1288,7 +1386,7 @@ function syncSkillsToGlobalHarnesses(excludeSkills = []) {
         { dir: path.join(homeDir, '.cursor', 'skills'), key: 'cursor' },
         { dir: path.join(homeDir, '.roo', 'skills'), key: 'vscode' },
         { dir: process.platform === 'win32' ? path.join(process.env.APPDATA || homeDir, 'opencode', 'skills') : path.join(homeDir, '.config', 'opencode', 'skills'), key: 'opencode' },
-    ].filter((d) => d.key === null || detectedKeys.has(d.key));
+    ].filter((d) => d.key === null || (detectedKeys.has(d.key) && !pluginCovered.has(d.key)));
 
     for (const { dir: dest } of extraSkillDestinations) {
         try {
@@ -1537,6 +1635,17 @@ async function promptCredentials(referenceMcpDir) {
 
 const DAEMON_LOGON_FALLBACK_EXIT_CODE = 10;
 
+// The daemon job points at these scripts for good, so they live in the installer-owned shared store
+// (~/.agents/skills), which the plugin migration never retires, not in ~/.claude/skills.
+function stableOpenWikiScripts() {
+    const dest = path.join(homeDir, '.agents', 'skills', 'openwiki-skill');
+    if (!fs.existsSync(path.join(dest, 'scripts', 'install_daemon.sh'))) {
+        const src = path.join(srcDir, 'skills', 'global_config', 'openwiki-skill');
+        if (fs.existsSync(src)) copyDirRecursiveSync(src, dest);
+    }
+    return path.join(dest, 'scripts');
+}
+
 async function installOpenWikiDaemon(apiKey, targetSkillDir, openwikiEnv = {}) {
     const prov = openwikiEnv.provider || "google";
     if (!apiKey && !["ollama", "lmstudio"].includes(prov)) {
@@ -1550,7 +1659,7 @@ async function installOpenWikiDaemon(apiKey, targetSkillDir, openwikiEnv = {}) {
     const s = spinner();
     s.start('Installing OpenWiki Daemon...');
 
-    const scriptBase = path.join(targetSkillDir, 'openwiki-skill', 'scripts');
+    const scriptBase = stableOpenWikiScripts();
 
     const daemonEnv = Object.assign({}, process.env, {
         OPENWIKI_PROVIDER:  prov,
@@ -2504,118 +2613,283 @@ function aoSupportedHere() {
     return ['darwin', 'linux', 'win32'].includes(process.platform);
 }
 
-async function installOSAgentWorkspace() {
-    if (!aoSupportedHere()) {
-        log.warn(`AO is not supported on ${process.platform}/${process.arch}.`);
-        return false;
-    }
+const AO_PKG = '@hybridlabor-api/bdb-agent-orchestrator';
+// `ao service install` restarts the daemon; it can take well over 8s to bind.
+const AO_DAEMON_WAIT_MS = 30000;
 
-    const isWin = process.platform === 'win32';
-    const isMac = process.platform === 'darwin';
-    const isLinux = process.platform === 'linux';
+function aoBinTarget() {
+    return process.platform === 'win32'
+        ? path.join(process.env.LOCALAPPDATA || homeDir, 'Programs', 'ao', 'ao.exe')
+        : path.join(homeDir, '.local', 'bin', 'ao');
+}
 
-    // Discover AO directory: check local development checkouts first, then moduleBasePath
-    const candidateDirs = [
-        path.join(homeDir, 'dev', 'agents', 'bdb-agent-orchestrator'),
-        path.join(homeDir, 'dev', 'bdb-dev', 'bdb-agent-orchestrator'),
-        path.join(moduleBasePath(), 'bdb-agent-orchestrator')
-    ];
-    const osAgentDir = candidateDirs.find(d => fs.existsSync(d)) || candidateDirs[candidateDirs.length - 1];
-    const isLocalGitRepo = fs.existsSync(path.join(osAgentDir, '.git'));
+// Go links the `go version -m` text between these two 16-byte markers, so the
+// revision of a binary can be read from its bytes: no Go toolchain needed, and
+// the binary (possibly the live daemon) is never executed.
+const GO_BUILDINFO_START = Buffer.from('3077af0c9274080241e1c107e6d618e6', 'hex');
+const GO_BUILDINFO_END = Buffer.from('f932433186182072008242104116d8f2', 'hex');
+
+function readGoBuildInfo(binPath) {
+    let buf;
+    try { buf = fs.readFileSync(binPath); } catch { return null; }
+    const start = buf.indexOf(GO_BUILDINFO_START);
+    const end = start < 0 ? -1 : buf.indexOf(GO_BUILDINFO_END, start);
+    return end < 0 ? null : parseGoBuildInfo(buf.subarray(start + GO_BUILDINFO_START.length, end).toString('utf8'));
+}
 
-    if (isLocalGitRepo) {
-        log.step(`Using local development workspace for AO: ${osAgentDir}`);
-    } else {
-        if (!downloadOrUpdateModule('@hybridlabor-api/bdb-agent-orchestrator', osAgentDir, 'BDB Agent Orchestrator')) {
-            log.warn('Skipping AO setup: the module could not be downloaded.');
-            return false;
-        }
+// Accepts the embedded text or `go version -m` output (same lines, tab-indented).
+function parseGoBuildInfo(text) {
+    const get = (key) => (String(text).match(new RegExp(`^\\s*build\\s+${key}=(\\S*)`, 'm')) || [])[1];
+    const revision = get('vcs\\.revision');
+    if (!revision) return null;
+    return { revision, time: get('vcs\\.time') || null, modified: get('vcs\\.modified') === 'true' };
+}
+
+// Never trade the installed ao for a build that is not provably newer and clean.
+// allowDirty: the AOS_AO_DEV_BUILD opt-in. daemonRunning/candidateIsRelease
+// only matter when the installed binary's revision is unreadable: a clean
+// published release may then replace it, but not while some daemon of unknown
+// build is running.
+function decideAoInstall({ installedExists, installed, candidate, allowDirty = false, candidateIsRelease = false, daemonRunning = true }) {
+    if (!installedExists) return { install: true, reason: 'no ao installed yet' };
+    if (!candidate) return { install: false, reason: 'the candidate build has no readable revision' };
+    if (candidate.modified && !allowDirty) return { install: false, reason: `the candidate ${candidate.revision.slice(0, 9)} is a dirty build (vcs.modified=true)` };
+    if (!installed) {
+        if (candidateIsRelease && !candidate.modified && daemonRunning === false) {
+            return { install: true, reason: `the installed binary's revision is unreadable and no daemon is running; installing the clean release ${candidate.revision.slice(0, 9)}` };
+        }
+        return { install: false, reason: 'the installed binary\'s revision is unreadable, so a downgrade cannot be ruled out' };
+    }
+    if (candidate.revision === installed.revision) return { install: false, reason: `already at ${installed.revision.slice(0, 9)}` };
+    const c = Date.parse(candidate.time || '');
+    const i = Date.parse(installed.time || '');
+    if (!(c > i)) return { install: false, reason: `the candidate ${candidate.revision.slice(0, 9)} (${candidate.time || 'no date'}) is not newer than the installed ${installed.revision.slice(0, 9)} (${installed.time || 'no date'})` };
+    return { install: true, reason: `${installed.revision.slice(0, 9)} -> ${candidate.revision.slice(0, 9)}` };
+}
+
+// A dev checkout is a release source only when clean and HEAD sits on a tag.
+function checkAoWorkspace(dir, git = (args) => execFileSync('git', ['--no-optional-locks', '-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()) {
+    try {
+        if (git(['status', '--porcelain'])) return { ok: false, reason: 'it has uncommitted or untracked changes' };
+        let tag;
+        try { tag = git(['describe', '--tags', '--exact-match', 'HEAD']); } catch { return { ok: false, reason: 'HEAD is not on a release tag' }; }
+        return { ok: true, tag, head: git(['rev-parse', 'HEAD']) };
+    } catch (e) {
+        return { ok: false, reason: `git could not read it (${String(e.message).split('\n')[0]})` };
     }
-    if (DRY_RUN) {
-        log.step('[dry-run] would link ao binary and run `ao service install`');
-        return;
+}
+
+// Builds into a temp dir: a build left in the checkout's gitignored backend/bin
+// outlives every later pull and gets picked up as if it were current.
+function buildAoFromSource(dir) {
+    if (!hasExecutable('go') || !fs.existsSync(path.join(dir, 'backend', 'cmd', 'ao'))) return null;
+    const out = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'aos-ao-build-')), process.platform === 'win32' ? 'ao.exe' : 'ao');
+    const s = spinner();
+    s.start('Compiling AO daemon binary from Go source...');
+    try {
+        execFileSync('go', ['build', '-ldflags=-s -w', '-o', out, './cmd/ao'], { cwd: path.join(dir, 'backend'), stdio: 'ignore' });
+        s.stop('Compiled AO daemon binary successfully.');
+        return out;
+    } catch (e) {
+        s.stop(`Failed to compile AO from source: ${e.message}`);
+        return null;
     }
+}
 
-    const localBinDir = isWin
-        ? path.join(process.env.LOCALAPPDATA || homeDir, 'Programs', 'ao')
-        : path.join(homeDir, '.local', 'bin');
-    const binTarget = path.join(localBinDir, isWin ? 'ao.exe' : 'ao');
+// Installed version = the release version the installer recorded for exactly
+// the revision on disk. Never the dev workspace's package.json.
+function trustedAoVersion(build, record) {
+    return build && !build.modified && record && record.version && record.revision === build.revision ? record.version : null;
+}
 
-    // Platform-specific binary lookup
-    const candidateBinaries = [];
-    if (isWin) {
-        candidateBinaries.push(
-            path.join(osAgentDir, 'backend', 'bin', 'ao-windows-amd64.exe'),
-            path.join(osAgentDir, 'backend', 'bin', 'ao.exe'),
-            path.join(osAgentDir, 'backend', 'ao.exe')
-        );
-    } else if (isMac) {
-        if (process.arch === 'arm64') {
-            candidateBinaries.push(path.join(osAgentDir, 'backend', 'bin', 'ao-darwin-arm64'));
-        } else {
-            candidateBinaries.push(path.join(osAgentDir, 'backend', 'bin', 'ao-darwin-amd64'));
-        }
-        candidateBinaries.push(
-            path.join(osAgentDir, 'backend', 'ao-daemon'),
-            path.join(osAgentDir, 'backend', 'bin', 'ao'),
-            path.join(osAgentDir, 'backend', 'ao')
-        );
-    } else if (isLinux) {
-        if (process.arch === 'arm64') {
-            candidateBinaries.push(path.join(osAgentDir, 'backend', 'bin', 'ao-linux-arm64'));
-        } else {
-            candidateBinaries.push(path.join(osAgentDir, 'backend', 'bin', 'ao-linux-amd64'));
-        }
-        candidateBinaries.push(
-            path.join(osAgentDir, 'backend', 'ao-daemon'),
-            path.join(osAgentDir, 'backend', 'bin', 'ao'),
-            path.join(osAgentDir, 'backend', 'ao')
-        );
+function describeAoVersion({ exists, build, record, latest }) {
+    if (!exists) return { text: 'Not installed', updateAvailable: false };
+    if (!build) return { text: 'Installed (build revision unreadable, version unknown)', updateAvailable: false };
+    const rev = build.revision.slice(0, 9);
+    if (build.modified) return { text: `Dev build ${rev} with uncommitted changes (not a release, version not comparable)`, updateAvailable: false };
+    const version = trustedAoVersion(build, record);
+    if (!version) return { text: `Build ${rev} (release version unknown)`, updateAvailable: false };
+    if (latest && isNewerVersion(version, latest)) return { text: `Update available (v${version} ➔ v${latest})`, updateAvailable: true };
+    return { text: `v${version} (Up to date)`, updateAvailable: false };
+}
+
+// The daemon's running.json (AO backend/internal/runfile: pid, port, startedAt).
+// pid+startedAt tells a restarted daemon from the old one still on :3101.
+function readAoDaemonIdentity(file = process.env.AO_RUN_FILE || path.join(homeDir, '.ao', 'running.json')) {
+    const data = readJsonFile(file);
+    if (!data || data.pid == null) return null;
+    return data.startedAt ? `${data.pid}@${data.startedAt}` : String(data.pid);
+}
+
+async function waitUntil(check, timeoutMs, pollMs = 300) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (check()) return true;
+        if (Date.now() >= deadline) return false;
+        await new Promise((r) => setTimeout(r, pollMs));
     }
-    let daemonBin = candidateBinaries.find(p => fs.existsSync(p));
+}
 
-    // Fallback: compile from Go source if Go is installed and binary is not pre-built
-    if (!daemonBin && hasExecutable('go') && fs.existsSync(path.join(osAgentDir, 'backend', 'cmd', 'ao'))) {
-        const s = spinner();
-        s.start('Compiling AO daemon binary from Go source...');
+// Back up, swap atomically, register the service, wait for a NEW daemon on
+// :3101. A failed swap or service install puts the previous binary back.
+async function installAoBinary({ src, dest, stamp = timestamp, serviceInstall, waitForDaemon, readIdentity = readAoDaemonIdentity, restartWaitMs = AO_DAEMON_WAIT_MS }) {
+    let backup = null;
+    if (src) {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        if (fs.existsSync(dest)) {
+            backup = `${dest}.bak-${stamp}`;
+            fs.copyFileSync(dest, backup);
+        }
         try {
-            const buildTarget = path.join(osAgentDir, 'backend', 'bin', isWin ? 'ao.exe' : 'ao');
-            fs.mkdirSync(path.dirname(buildTarget), { recursive: true });
-            execFileSync('go', ['build', '-ldflags=-s -w', '-o', buildTarget, './cmd/ao'], {
-                cwd: path.join(osAgentDir, 'backend'),
-                stdio: 'ignore'
-            });
-            daemonBin = buildTarget;
-            s.stop('Compiled AO daemon binary successfully.');
+            installBinaryAtomically(src, dest);
         } catch (e) {
-            s.stop(`Failed to compile AO from source: ${e.message}`);
+            if (backup) installBinaryAtomically(backup, dest);
+            log.warn(`Could not place the ao binary (${e.message})${backup ? '; the previous binary is back in place' : ''}.`);
+            return { ok: false, backup, restored: !!backup };
         }
+        log.step(`Installed ao to ${dest}${backup ? ` (previous binary kept at ${backup})` : ''}`);
+    }
+    const before = readIdentity();
+    try {
+        await serviceInstall(dest);
+    } catch (e) {
+        if (backup) {
+            installBinaryAtomically(backup, dest);
+            try { await serviceInstall(dest); } catch (e2) { logDebug(e2, 'ao service install after restore'); }
+        }
+        log.warn(`AO service install failed: ${e.message}${backup ? `. Restored the previous ao from ${backup}` : ''}. Start it by hand with: ao service install`);
+        return { ok: false, backup, restored: !!backup };
+    }
+    // No identity before (file missing/unreadable): the port check is all we have.
+    const restarted = before ? await waitUntil(() => { const now = readIdentity(); return !!now && now !== before; }, restartWaitMs) : true;
+    const listening = await waitForDaemon();
+    const backupNote = backup ? ` The previous binary is at ${backup} (restore: mv "${backup}" "${dest}" && ao service install).` : '';
+    if (listening && restarted) {
+        log.success('AO Orchestrator running on http://localhost:3101');
+    } else if (listening) {
+        log.warn(`AO on :3101 is still the old process (${before}); it was not restarted, probably because it does not run under the AO service. Restart it: ao service install, then check ao service status (or stop it and start it the way it was started).${backupNote}`);
+    } else {
+        const hint = process.platform === 'win32'
+            ? 'Run `ao service install` again or log out and back in, then check `ao service status`.'
+            : 'Check `ao service status` and `ao service logs`.';
+        log.warn(`AO did not answer on :3101 within ${Math.round(AO_DAEMON_WAIT_MS / 1000)}s. ${hint}${backupNote}`);
     }
+    return { ok: true, backup, listening, restarted };
+}
 
-    // Fallback: if already installed and functional, keep it
-    if (!daemonBin && fs.existsSync(binTarget)) {
-        try {
-            execFileSync(binTarget, ['--version'], { stdio: 'ignore' });
-            log.step(`Keeping existing working AO binary at ${binTarget}`);
-            daemonBin = binTarget;
-        } catch (_) {}
+function aoPlatformBinaries(dir) {
+    const b = (...p) => path.join(dir, 'backend', ...p);
+    if (process.platform === 'win32') return [b('bin', 'ao-windows-amd64.exe'), b('bin', 'ao.exe'), b('ao.exe')];
+    const plat = process.platform === 'darwin' ? 'darwin' : 'linux';
+    const arch = process.arch === 'arm64' ? 'arm64' : 'amd64';
+    return [b('bin', `ao-${plat}-${arch}`), b('ao-daemon'), b('bin', 'ao'), b('ao')];
+}
+
+// Picks the binary this run may install. A local checkout counts only when it
+// is a release source (clean, HEAD on a tag) or AOS_AO_DEV_BUILD=1 opts in;
+// otherwise the published release package is used, never the dev checkout.
+function selectAoCandidate({
+    checkoutDir, isLocalGitRepo, releaseDir,
+    devOptIn = process.env.AOS_AO_DEV_BUILD === '1',
+    dryRun = DRY_RUN,
+    checkWorkspace = checkAoWorkspace,
+    download = (dir) => downloadOrUpdateModule(AO_PKG, dir, 'BDB Agent Orchestrator'),
+    build = buildAoFromSource,
+    candidatesIn = aoPlatformBinaries,
+}) {
+    if (isLocalGitRepo) {
+        const ws = checkWorkspace(checkoutDir);
+        if (ws.ok) {
+            if (dryRun) return { bin: null, source: 'dry-run' };
+            // A prebuilt binary counts only when it was built clean from this exact HEAD.
+            const prebuilt = candidatesIn(checkoutDir).find((p) => {
+                const info = readGoBuildInfo(p);
+                return info && !info.modified && info.revision === ws.head;
+            });
+            return { bin: prebuilt || build(checkoutDir), source: 'checkout' };
+        }
+        if (devOptIn) {
+            log.warn(`AOS_AO_DEV_BUILD=1: building ao from ${checkoutDir} HEAD although ${ws.reason}; a downgrade is still refused.`);
+            if (dryRun) return { bin: null, source: 'dry-run' };
+            return { bin: build(checkoutDir), source: 'dev', allowDirty: true };
+        }
+        log.warn(`The AO checkout ${checkoutDir} is not a release source (${ws.reason}; Go also counts untracked files as uncommitted), so the published release is used. To build from the checkout instead, rerun with AOS_AO_DEV_BUILD=1.`);
+    }
+    if (fs.existsSync(path.join(releaseDir, '.git'))) {
+        log.warn(`${releaseDir} is a git checkout; not downloading the release over it. Keeping the installed ao.`);
+        return { bin: null, source: 'release-dir-is-checkout' };
+    }
+    if (dryRun) {
+        log.step(`[dry-run] would download ${AO_PKG} to ${releaseDir}`);
+        return { bin: null, source: 'dry-run' };
+    }
+    if (!download(releaseDir)) {
+        log.warn(`Could not download ${AO_PKG}; keeping the installed ao.`);
+        return { bin: null, source: 'download-failed' };
     }
+    return { bin: candidatesIn(releaseDir).find((p) => fs.existsSync(p)) || null, source: 'release' };
+}
 
-    if (!daemonBin) {
-        log.warn(`AO binary missing in ${osAgentDir} — package layout changed or Go build needed.`);
+async function installOSAgentWorkspace() {
+    if (!aoSupportedHere()) {
+        log.warn(`AO is not supported on ${process.platform}/${process.arch}.`);
         return false;
     }
 
-    if (daemonBin !== binTarget) {
-        installStep('place the ao binary', () => {
-            fs.mkdirSync(localBinDir, { recursive: true });
-            installBinaryAtomically(daemonBin, binTarget);
-            log.step(`Installed ao to ${binTarget}`);
-        }, 'AO cannot be started without its binary.');
+    const releaseDir = path.join(moduleBasePath(), 'bdb-agent-orchestrator');
+    const checkoutDir = [
+        path.join(homeDir, 'dev', 'agents', 'bdb-agent-orchestrator'),
+        path.join(homeDir, 'dev', 'bdb-dev', 'bdb-agent-orchestrator'),
+    ].find((d) => fs.existsSync(path.join(d, '.git')));
+    if (checkoutDir) log.step(`Found a local AO checkout: ${checkoutDir}`);
+
+    const pick = selectAoCandidate({ checkoutDir, isLocalGitRepo: !!checkoutDir, releaseDir });
+    if (DRY_RUN) {
+        log.step('[dry-run] would install the ao binary and run `ao service install`');
+        return;
+    }
+
+    const binTarget = aoBinTarget();
+    const installedExists = fs.existsSync(binTarget);
+    let src = null;
+    let candidate = null;
+    if (pick.bin) {
+        candidate = readGoBuildInfo(pick.bin);
+        const installed = installedExists ? readGoBuildInfo(binTarget) : null;
+        const daemonRunning = installedExists && !installed
+            ? (readAoDaemonIdentity() !== null || await verifyDaemonListening(3101, 'AO Orchestrator', 1500))
+            : true;
+        const verdict = decideAoInstall({ installedExists, installed, candidate, allowDirty: !!pick.allowDirty, candidateIsRelease: pick.source === 'release', daemonRunning });
+        if (verdict.install) src = pick.bin;
+        else log.step(`Keeping ${binTarget}: ${verdict.reason}.`);
+    }
+
+    if (!src && !installedExists) {
+        log.warn(`No ao binary could be installed (${pick.source}).`);
+        return false;
     }
+    // Unchanged binary and a live daemon: nothing to restart.
+    if (!src && await verifyDaemonListening(3101, 'AO Orchestrator', 1500)) {
+        log.success('AO Orchestrator running on http://localhost:3101');
+        return;
+    }
+
+    const result = await installAoBinary({
+        src,
+        dest: binTarget,
+        serviceInstall: (bin) => aoServiceInstall(bin),
+        waitForDaemon: () => verifyDaemonListening(3101, 'AO Orchestrator', AO_DAEMON_WAIT_MS),
+    });
+    if (result.ok && src) {
+        const pkgJson = readJsonFile(path.join(pick.source === 'release' ? releaseDir : checkoutDir, 'package.json')) || {};
+        saveManifest({ ao: { version: pick.source === 'dev' ? null : (pkgJson.version || null), revision: candidate ? candidate.revision : null, modified: !!(candidate && candidate.modified), installedAt: new Date().toISOString() } });
+    }
+    return result.ok ? undefined : false;
+}
 
+function aoServiceInstall(binTarget) {
     // macOS only: code-sign ad-hoc to prevent AMFI SIGKILL
-    if (isMac) {
+    if (process.platform === 'darwin') {
         try {
             execFileSync('codesign', ['-v', binTarget], { stdio: 'ignore' });
         } catch {
@@ -2625,35 +2899,17 @@ async function installOSAgentWorkspace() {
                 log.step('Signed it ad-hoc.');
             } catch (e) { log.warn(`Could not sign it: ${e.message}`); }
         }
-    }
-
-    // AO installs its own service, and does it for macOS, Windows and Linux.
-    if (isMac) {
         const legacyPlist = path.join(homeDir, 'Library', 'LaunchAgents', 'com.bdb.agent-workspace.plist');
         if (fs.existsSync(legacyPlist)) {
             try { execFileSync('launchctl', ['unload', legacyPlist], { stdio: 'ignore' }); } catch (e) { logDebug(e, 'unload legacy ao agent'); }
             try { fs.unlinkSync(legacyPlist); log.step('Removed the old com.bdb.agent-workspace service.'); } catch (e) { logDebug(e, 'remove legacy plist'); }
         }
     }
-
-    const serviceStep = installStep('register the AO service', () => {
-        try {
-            execFileSync(binTarget, ['service', 'install'], { stdio: ['ignore', 'pipe', 'pipe'] });
-        } catch (e) {
-            throw new Error(describeExecError(e));
-        }
-    }, 'Start it by hand with: ao service install');
-    if (!serviceStep.ok) return false;
-
-    // Windows startup entries fire asynchronously — give the service more time
-    const aoTimeout = process.platform === 'win32' ? 20000 : 8000;
-    if (await verifyDaemonListening(3101, 'AO Orchestrator', aoTimeout)) {
-        log.success('AO Orchestrator running on http://localhost:3101');
-    } else {
-        const hint = process.platform === 'win32'
-            ? 'Run `ao service install` again or log out and back in, then check `ao service status`.'
-            : 'Check `ao service status` and `ao service logs`.';
-        log.warn(`AO did not answer on :3101 — ${hint}`);
+    // AO installs its own service, and does it for macOS, Windows and Linux.
+    try {
+        execFileSync(binTarget, ['service', 'install'], { stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (e) {
+        throw new Error(describeExecError(e));
     }
 }
 async function promptMemBIngestion(mcpCodeTarget) {
@@ -2715,6 +2971,18 @@ function verifyEcosystemInstallation() {
     ];
 
     for (const mod of modules) {
+        if (mod.pkg === AO_PKG) {
+            const bin = aoBinTarget();
+            const exists = fs.existsSync(bin);
+            const build = exists ? readGoBuildInfo(bin) : null;
+            const record = (readJsonFile(path.join(homeDir, '.agents', '.bdb-manifest.json')) || {}).ao || null;
+            const version = trustedAoVersion(build, record);
+            const latest = version ? (newestDistTag(AO_PKG, version) || {}).version : null;
+            const s = describeAoVersion({ exists, build, record, latest });
+            const mark = !exists ? `${colors.dim}⚪` : s.updateAvailable ? `${colors.yellow}⚠️ ` : build && !build.modified ? `${colors.green}✅` : `${colors.yellow}⚠️ `;
+            console.log(`  • ${colors.bold}${mod.name.padEnd(35)}${colors.reset} ➔ ${mark} ${s.text}${colors.reset}`);
+            continue;
+        }
         let modulePkgPath = null;
         for (const p of mod.paths) {
             const candidate = path.join(p, 'package.json');
@@ -2727,29 +2995,9 @@ function verifyEcosystemInstallation() {
         if (modulePkgPath) {
             try {
                 const localVer = JSON.parse(fs.readFileSync(modulePkgPath, 'utf8')).version || '1.0.0';
-                let newerVersion = null;
-                let newerTag = null;
-                try {
-                    const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-                    const distTagsJson = process.platform === 'win32'
-                        ? execSync(`"${npmCmd}" view ${mod.pkg} dist-tags --json`, { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8', timeout: 4000 }).trim()
-                        : execFileSync(npmCmd, ['view', mod.pkg, 'dist-tags', '--json'], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8', timeout: 4000 }).trim();
-                    const distTags = JSON.parse(distTagsJson);
-                    for (const [tag, ver] of Object.entries(distTags)) {
-                        if (isNewerVersion(localVer, ver)) {
-                            if (!newerVersion || isNewerVersion(newerVersion, ver)) {
-                                newerVersion = ver;
-                                newerTag = tag;
-                            }
-                        }
-                    }
-                } catch (e) { logDebug(e, 'operation'); }
-
-                // `npm view <pkg> dist-tags --json` fetches all tags.
-                // We compare every tag's version against localVer with the fixed
-                // isNewerVersion(), and report an update if ANY tag is ahead.
-                if (newerVersion) {
-                    console.log(`  • ${colors.bold}${mod.name.padEnd(35)}${colors.reset} ➔ ${colors.yellow}⚠️  Update available (v${localVer} ➔ v${newerVersion} (${newerTag}))${colors.reset}`);
+                const newer = newestDistTag(mod.pkg, localVer);
+                if (newer) {
+                    console.log(`  • ${colors.bold}${mod.name.padEnd(35)}${colors.reset} ➔ ${colors.yellow}⚠️  Update available (v${localVer} ➔ v${newer.version} (${newer.tag}))${colors.reset}`);
                 } else {
                     console.log(`  • ${colors.bold}${mod.name.padEnd(35)}${colors.reset} ➔ ${colors.green}✅ v${localVer} (Up to date)${colors.reset}`);
                 }
@@ -3473,6 +3721,14 @@ function compileClaudeAgents(agents, targetDir, pipelineConfig = null) {
     }
 }
 
+// .claude/agents/<slug>.md is shipped and copied to ~/.claude/agents by the
+// manifest-tracked "copy harness directories" step. Compiling the same slug
+// there first made the two writers fight: the compiled bytes never matched the
+// manifest, so every update flagged all 13 personas as user-edited.
+function agentsNotShippedAsFiles(agents, shippedDir = path.join(srcDir, '.claude', 'agents')) {
+    return agents.filter((a) => !fs.existsSync(path.join(shippedDir, `${a.name.toLowerCase().replace(/_/g, '-')}.md`)));
+}
+
 // Generates .opencode/agents/<name>.md. Emits description, mode: subagent, and model.
 function compileOpenCodeAgents(agents, targetDir, pipelineConfig = null) {
     fs.mkdirSync(targetDir, { recursive: true });
@@ -3575,8 +3831,12 @@ function injectHarnessRules() {
         if (sources.ok) {
             const { globalRules, startcycleContent, agentsMdContent } = sources.value;
 
+            // Run from $HOME, these project files ARE the global files that the
+            // manifest-tracked harness copy below writes; a second writer would
+            // make every update see them as user-edited.
+            const cwdIsHome = path.resolve(currentDir) === path.resolve(homeDir);
             const cursorRulesDir = path.join(currentDir, '.cursor', 'rules');
-            installStep(`write the Cursor rules to ${cursorRulesDir}`, () => {
+            if (!cwdIsHome) installStep(`write the Cursor rules to ${cursorRulesDir}`, () => {
                 fs.mkdirSync(cursorRulesDir, { recursive: true });
                 fs.writeFileSync(path.join(cursorRulesDir, '000_global_rules.mdc'), `---\nname: global-rules\ndescription: Global BDB Agent Rules\n---\n\n${globalRules}`);
                 if (startcycleContent) {
@@ -3618,7 +3878,7 @@ function injectHarnessRules() {
             installStep('compile Claude Code subagents', () => {
                 if (agentsMdContent) {
                     const pipelineConfig = loadPipelineConfig();
-                    const agents = parseAgentsMd(agentsMdContent);
+                    const agents = agentsNotShippedAsFiles(parseAgentsMd(agentsMdContent));
                     const claudeAgentsDir = path.join(homeDir, '.claude', 'agents');
                     compileClaudeAgents(agents, claudeAgentsDir, pipelineConfig);
                     log.step(`Compiled AGENTS.md to Claude Code subagents in ${claudeAgentsDir}`);
@@ -3723,7 +3983,7 @@ function injectHarnessRules() {
                     const targetPath = path.join(homeDir, dir);
                     // settings.json is merged separately below: a wholesale
                     // copy would clobber user-owned keys like enabledPlugins.
-                    const exclude = dir === '.claude' ? ['settings.json'] : [];
+                    const exclude = dir === '.claude' ? ['settings.json'] : dir === '.agents' ? AGENTS_COPY_EXCLUDE : [];
                     copyDirRecursiveSync(sourcePath, targetPath, exclude);
                     log.step(`Copied ${dir} to ${targetPath}`);
                 }
@@ -3735,13 +3995,109 @@ function injectHarnessRules() {
             const globalAgentsDir = path.join(os.homedir(), '.agents');
             const agentsDirSrc = path.join(srcDir, '.agents');
             if (fs.existsSync(agentsDirSrc)) {
-                copyDirRecursiveSync(agentsDirSrc, globalAgentsDir);
+                copyDirRecursiveSync(agentsDirSrc, globalAgentsDir, AGENTS_COPY_EXCLUDE);
                 log.step(`Synced global .agents/ to ${globalAgentsDir}`);
             }
         }, 'agents.md and workflows/startcycle.md may be missing globally.');
     }
 }
 
+// Optional third-party OpenCode components. Off unless named in
+// AOS_OPENCODE_OPTIONAL=ponytail,loop,rtk or --opencode-optional=ponytail,loop,rtk.
+// Pinned entries only; the foreign installers (opencode-loop's npx installer, rtk init)
+// are never run because they rewrite the user's opencode config.
+const OPENCODE_OPTIONAL_PINS = {
+    ponytail: '@dietrichgebert/ponytail@4.10.0',
+    loop: '@bybrawe/opencode-loop@0.6.2',
+};
+const OPENCODE_RTK_HINT = 'rtk is not installed by AOS. Run yourself: brew install rtk && rtk init -g --opencode';
+const OPENCODE_LOOP_SHELL_WARNING = 'opencode-loop: /loop-shell style commands run shell commands as child processes. ' +
+    'tool.execute.before, and so the AOS go-gate, may never see them (unverified). ' +
+    'Do not schedule git push, publish or other gated commands through them.';
+
+function parseOpencodeOptional(argv = process.argv, env = process.env) {
+    const flag = argv.find((a) => a.startsWith('--opencode-optional='));
+    const raw = [env.AOS_OPENCODE_OPTIONAL, flag && flag.slice('--opencode-optional='.length)].filter(Boolean).join(',');
+    return new Set(raw.split(',').map((x) => x.trim().toLowerCase()).filter(Boolean));
+}
+
+const pluginPackageName = (entry) => {
+    const str = typeof entry === 'string' ? entry : (Array.isArray(entry) ? String(entry[0]) : '');
+    return str.replace(/(?<=.)@[^@/]*$/, '');
+};
+
+// OpenCode auto-loads plugins/*.js and also loads plugin[] paths, then dedupes by file
+// URL (verified in the 1.18.30 binary strings, not by running it). Same path = one load;
+// a second differing spelling would load the gate and loop keeper twice.
+function warnOnDuplicateAosPlugin(plugins, canonical) {
+    const norm = (v) => String(Array.isArray(v) ? v[0] : v).replace(/\\/g, '/');
+    const others = plugins.filter((p) => /bdb-aos\.js$/.test(norm(p)) && norm(p) !== canonical);
+    if (others.length > 0) {
+        log.warn(`opencode.jsonc lists bdb-aos.js under another path (${others.map(norm).join(', ')}). ` +
+            `plugins/bdb-aos.js is auto-loaded too; remove the extra entry to avoid a double gate.`);
+    }
+}
+
+function appendOptionalOpencodePlugins(data, configPath, optional) {
+    const wanted = optional instanceof Set ? optional : new Set(optional || []);
+    for (const name of wanted) {
+        if (!(name in OPENCODE_OPTIONAL_PINS) && name !== 'rtk') log.warn(`Unknown OpenCode optional component "${name}" ignored.`);
+    }
+    if (wanted.has('rtk')) log.message(OPENCODE_RTK_HINT);
+    let backedUp = false;
+    for (const name of Object.keys(OPENCODE_OPTIONAL_PINS)) {
+        if (!wanted.has(name) || DRY_RUN) continue;
+        const pin = OPENCODE_OPTIONAL_PINS[name];
+        if (data.plugin.some((p) => pluginPackageName(p) === pluginPackageName(pin))) continue;
+        if (!backedUp && configPath && fs.existsSync(configPath)) {
+            const bak = `${configPath}.${timestamp}.bak`;
+            try { fs.copyFileSync(configPath, bak); backedUp = true; } catch (e) {
+                log.warn(`Could not back up ${configPath}, skipping optional ${name}: ${e.message}`);
+                continue;
+            }
+        }
+        data.plugin.push(pin);
+        log.step(`Added opt-in OpenCode plugin ${pin}`);
+    }
+    if (data.plugin.some((p) => pluginPackageName(p) === pluginPackageName(OPENCODE_OPTIONAL_PINS.loop))) {
+        log.warn(OPENCODE_LOOP_SHELL_WARNING);
+    }
+}
+
+// Idempotent and edit-safe: a file is overwritten only when it is absent, already
+// identical, or still byte-equal to what this installer last recorded. Anything else
+// (user edit, or an untracked file with the same name) is kept and the shipped copy
+// lands as <file>.new. Files the installer did not create are never removed.
+function installOpencodeCommands(srcDirPath, destDirPath) {
+    if (DRY_RUN) {
+        log.message(`[dry-run] install OpenCode commands: ${srcDirPath} -> ${destDirPath}`);
+        return;
+    }
+    const ownsManifest = !_sessionManifest;
+    const manifest = _sessionManifest || loadInstallManifest();
+    fs.mkdirSync(destDirPath, { recursive: true });
+    let wrote = 0;
+    for (const file of fs.readdirSync(srcDirPath)) {
+        const src = path.join(srcDirPath, file);
+        if (!fs.statSync(src).isFile()) continue;
+        const dest = path.join(destDirPath, file);
+        const srcHash = computeFileHash(src);
+        const diskHash = fs.existsSync(dest) ? computeFileHash(dest) : null;
+        if (diskHash === null || diskHash === srcHash || diskHash === manifest[dest]?.sha256) {
+            if (diskHash !== srcHash) { fs.copyFileSync(src, dest); wrote++; }
+            manifest[dest] = { path: dest, sha256: srcHash, version: pkg.version, installedAt: new Date().toISOString() };
+        } else {
+            fs.copyFileSync(src, `${dest}.new`);
+            keptUserEdits.push(dest);
+        }
+    }
+    if (ownsManifest) {
+        saveInstallManifest(manifest);
+        reportKeptUserEdits();
+    }
+    log.step(`OpenCode commands in ${destDirPath}: ${wrote} written`);
+}
+
 // Copy the OpenCode plugin + command payload and register both in
 // opencode.jsonc. This is the single copy site: the Quick Update path
 // (injectHarnessRules -> installGlobalHooks) and the fresh-install path
@@ -3752,7 +4108,7 @@ function injectHarnessRules() {
 // Sync merges MCP servers in the same pass and writes once). When `data` is
 // omitted the function loads and saves the config itself, which is what lets the
 // Quick Update path register the plugin as well as copy it.
-function installOpencodePlugin({ targetHome = homeDir, configPath = null, data = null } = {}) {
+function installOpencodePlugin({ targetHome = homeDir, configPath = null, data = null, optional = parseOpencodeOptional() } = {}) {
     const opencodeDir = configPath
         ? path.dirname(configPath)
         : (process.platform === 'win32'
@@ -3789,13 +4145,11 @@ function installOpencodePlugin({ targetHome = homeDir, configPath = null, data =
         try { copyDirRecursiveSync(trailLibSrc, path.join(opencodeDir, 'plugins', 'lib')); } catch (e) { log.warn(`Could not install OpenCode plugin lib: ${e.message}`); }
     }
 
-    // Slash-command payloads. Without these the /startcycle-graph command has no
-    // native resolution and only survives as a raw-text match in the plugin.
+    // Slash-command payloads (/startcycle-graph and the generated /bdb-aos-<cmd> files).
     const commandsSrc = path.join(srcDir, '.opencode', 'commands');
     if (fs.existsSync(commandsSrc)) {
         try {
-            copyDirRecursiveSync(commandsSrc, path.join(opencodeDir, 'commands'));
-            log.step(`Installed OpenCode commands to ${path.join(opencodeDir, 'commands')}`);
+            installOpencodeCommands(commandsSrc, path.join(opencodeDir, 'commands'));
         } catch (e) {
             log.warn(`Could not install OpenCode commands: ${e.message}`);
         }
@@ -3822,6 +4176,8 @@ function installOpencodePlugin({ targetHome = homeDir, configPath = null, data =
         return str.includes('bdb-aos');
     });
     if (!alreadyRegistered) data.plugin.push(pluginPathNormalized);
+    warnOnDuplicateAosPlugin(data.plugin, pluginPathNormalized);
+    appendOptionalOpencodePlugins(data, configPath, optional);
 
     // Skill paths. `.agents/skills` stays project-relative on purpose: it is the
     // per-project contract, and OpenCode resolves it against each project, so it
@@ -3987,7 +4343,7 @@ function installGlobalBinaries() {
 // merged result goes to a .bdb-new.json sidecar -- the same recovery pattern
 // the MCP config merge in installMcpsForTarget uses.
 function mergeBdbSettingsHooks(settingsPath, { projectLocal = false } = {}) {
-    const bdbHookScripts = ['go-gate.mjs', 'go-token.mjs', 'graph-gate.mjs', 'memb-inject.mjs', 'trail-relay.mjs', 'trail-autostart.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs'];
+    const bdbHookScripts = ['go-gate.mjs', 'go-token.mjs', 'go-grant.mjs', 'graph-gate.mjs', 'memb-inject.mjs', 'trail-relay.mjs', 'trail-autostart.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs'];
     // memb-inject reads the machine-global memB store under $HOME and is
     // installed once per machine, so it stays $HOME-anchored even inside a
     // project harness -- unlike the two gate hooks, which are per-checkout by
@@ -4095,9 +4451,12 @@ function selfCheckAgyHooks(hooksPath, spawn = spawnSync) {
     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 r = spawn(shell, [flag, command], { cwd: path.dirname(hooksPath), input: '{}', encoding: 'utf8', timeout: 20000, windowsHide: true, env: { ...process.env, AGENTTRAIL_PORT: '1' } });
         const stderr = String((r && r.stderr) || '');
         let reason = null;
+        // A slow machine (memb-inject reads the store) can exceed the limit without the hook being broken:
+        // the failures this check exists for (bad path, missing module, non-zero exit) are immediate.
+        if (r && r.error && r.error.code === 'ETIMEDOUT') { log.warn(`agy hook self-check timed out, not treated as a failure: ${command}`); continue; }
         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)}`;
@@ -4391,7 +4750,7 @@ function installProjectHarness() {
     installStep('copy .agents/ contract into project', () => {
         const agentsSrc = path.join(srcDir, '.agents');
         if (!fs.existsSync(agentsSrc)) throw new Error(`missing payload: ${agentsSrc}`);
-        copyDirRecursiveSync(agentsSrc, projectAgentsDir);
+        copyDirRecursiveSync(agentsSrc, projectAgentsDir, AGENTS_COPY_EXCLUDE);
         log.step(`Copied .agents/ contract to ${projectAgentsDir}`);
     }, 'graph.md / state.schema.json may be missing in the project.');
 
@@ -5420,20 +5779,22 @@ async function runQuickUpdate(installState) {
 
 
 function buildAoAnnouncementBanner() {
+    const W = 78;
+    const row = (text, style = '') => `\x1b[36m│\x1b[0m${style}${text.padEnd(W)}\x1b[0m\x1b[36m│\x1b[0m`;
     return [
-        '\x1b[36m╭──────────────────────────────────────────────────────────────────────────────╮\x1b[0m',
-        '\x1b[36m│\x1b[0m                                                                              \x1b[36m│\x1b[0m',
-        '\x1b[36m│\x1b[0m   \x1b[1m\x1b[35m🚀 BDB AGENT ORCHESTRATOR APP — FINALE BETA JETZT VERFÜGBAR!\x1b[0m              \x1b[36m│\x1b[0m',
-        '\x1b[36m│\x1b[0m                                                                              \x1b[36m│\x1b[0m',
-        '\x1b[36m│\x1b[0m   Die nächste Generation der Cross-Harness Multi-Agenten-Orchestrierung      \x1b[36m│\x1b[0m',
-        '\x1b[36m│\x1b[0m   ist jetzt als finale Beta für alle User freigeschaltet.                    \x1b[36m│\x1b[0m',
-        '\x1b[36m│\x1b[0m                                                                              \x1b[36m│\x1b[0m',
-        '\x1b[36m│\x1b[0m   • \x1b[1mDashboard & WebUI:\x1b[0m  http://localhost:3101                                \x1b[36m│\x1b[0m',
-        '\x1b[36m│\x1b[0m   • \x1b[1mService-Befehl:\x1b[0m     ao service install  (Hintergrunddienst aktivieren)   \x1b[36m│\x1b[0m',
-        '\x1b[36m│\x1b[0m   • \x1b[1mQuick Launch:\x1b[0m       ao open  oder  ao service status                     \x1b[36m│\x1b[0m',
-        '\x1b[36m│\x1b[0m   • \x1b[1mFeatures:\x1b[0m           Session-Telemetrie, Live-AgentTrail & Multi-Workspaces\x1b[36m│\x1b[0m',
-        '\x1b[36m│\x1b[0m                                                                              \x1b[36m│\x1b[0m',
-        '\x1b[36m╰──────────────────────────────────────────────────────────────────────────────╯\x1b[0m\n'
+        `\x1b[36m╭${'─'.repeat(W)}╮\x1b[0m`,
+        row(''),
+        row('   BDB AGENT ORCHESTRATOR APP — FINAL BETA NOW AVAILABLE', '\x1b[1m\x1b[35m'),
+        row(''),
+        row('   The next generation of cross-harness multi-agent orchestration'),
+        row('   is now open to every user as a final beta.'),
+        row(''),
+        row('   • Dashboard & WebUI:  http://localhost:3101'),
+        row('   • Service command:    ao service install  (enables the background service)'),
+        row('   • Quick launch:       ao open  or  ao service status'),
+        row('   • Features:           session telemetry, live AgentTrail, multi-workspaces'),
+        row(''),
+        `\x1b[36m╰${'─'.repeat(W)}╯\x1b[0m\n`
     ].join('\n');
 }
 
@@ -5487,11 +5848,11 @@ function installBinaryAtomically(src, dest) {
 
 async function main() {
     const args = process.argv.slice(2);
-    if (args.includes('--version') || args.includes('-V')) {
+    if (args.includes('--version') || args.includes('-V') || args[0] === 'version') {
         console.log(pkg.version);
         return;
     }
-    if (args.includes('--help') || args.includes('-h')) {
+    if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
         console.log(`Usage: aos [command] [options]
 
 Commands:
@@ -5501,6 +5862,15 @@ Commands:
 Options:
   -y, --yes        Non-interactive install (implied without a TTY)
   --dry-run        Show what would change
+  --opencode-optional=LIST
+                   Opt in to OpenCode extras (comma list: ponytail, loop, rtk), or set
+                   AOS_OPENCODE_OPTIONAL. Pinned plugin[] entries are appended after a
+                   config backup; rtk only prints a brew hint. Off by default. AOS never
+                   runs foreign installers and never touches OpenCode's mcp set.
+  --plugin-migration=off|check
+                   Skip (off) or only report (check) the bdb-aos plugin registration and
+                   removal of AOS's own loose skill copies; same as AOS_PLUGIN_MIGRATION.
+                   --dry-run implies check. Default: on.
   --verbose, -v    Verbose output
   -V, --version    Print the version and exit
   -h, --help       Print this help and exit`);
@@ -5868,45 +6238,7 @@ Options:
     const s = spinner();
     s.start(`Installing optimized skills${tier === '2' ? ' [Basic Tier]' : ''} to ${targets.length} target(s)...`);
 
-    for (const t of targets) {
-        if (mode === 'replace') {
-            moveIfExists(t.targetSkillDir, path.join(backupDir, `config_skills_backup_${t.value}`), `global config skills (${t.value})`);
-            moveIfExists(t.targetLegacyDir, path.join(backupDir, `legacy_skills_backup_${t.value}`), `legacy skills (${t.value})`);
-            moveIfExists(t.targetWorkspaceDir, path.join(backupDir, `workspace_skills_backup_${t.value}`), `workspace skills (${t.value})`);
-        }
-
-        installStep(`create the skill target directories (${t.value})`, () => {
-            fs.mkdirSync(t.targetSkillDir, { recursive: true });
-            retireObsoleteLegacyDir(t.targetLegacyDir);
-            fs.mkdirSync(t.targetWorkspaceDir, { recursive: true });
-        }, 'The skill copies below will most likely be skipped as well.');
-
-        if (fs.existsSync(skillsBase)) {
-            installStep(`install the skills (${t.value})`, () => {
-                const rawDirs = fs.readdirSync(skillsBase);
-                const dirs = rawDirs.sort((a, b) => {
-                    const aIsLeaf = fs.existsSync(path.join(skillsBase, a, 'SKILL.md'));
-                    const bIsLeaf = fs.existsSync(path.join(skillsBase, b, 'SKILL.md'));
-                    if (aIsLeaf && !bIsLeaf) return 1;
-                    if (!aIsLeaf && bIsLeaf) return -1;
-                    return 0;
-                });
-                for (const dir of dirs) {
-                    const fullPath = path.join(skillsBase, dir);
-                    if (!fs.statSync(fullPath).isDirectory()) continue;
-
-                    if (dir === 'global_legacy') {
-                        copyDirRecursiveSync(fullPath, t.targetLegacyDir, excludeSkills);
-                    } else if (dir === 'workspace_agents') {
-                        copyDirRecursiveSync(fullPath, t.targetWorkspaceDir, excludeSkills);
-                    } else {
-                        syncSkillEntry(fullPath, dir, t.targetSkillDir, excludeSkills);
-                    }
-                }
-                log.step(`Installed all global config & core skills to ${t.targetSkillDir}`);
-            }, 'The skills are missing or incomplete; the rest of the installation continues.');
-        }
-    }
+    installTargetSkills(targets, { mode, backupDir, excludeSkills, skillsBase });
 
     syncSkillsToGlobalHarnesses(excludeSkills);
     pruneRemovedSkills(_sessionManifest);
@@ -5961,6 +6293,16 @@ if (require.main === module) {
 module.exports = {
     installBinaryAtomically,
     installOSAgentWorkspace,
+    readGoBuildInfo,
+    parseGoBuildInfo,
+    decideAoInstall,
+    checkAoWorkspace,
+    installAoBinary,
+    readAoDaemonIdentity,
+    selectAoCandidate,
+    describeAoVersion,
+    buildAoAnnouncementBanner,
+    agentsNotShippedAsFiles,
     downloadOrUpdateModule,
     detectPlatforms,
     markPlatformsExplicit,
@@ -5976,6 +6318,10 @@ module.exports = {
     mergeCodexTomlMcpServers,
     installGlobalHooks,
     installOpencodePlugin,
+    installOpencodeCommands,
+    parseOpencodeOptional,
+    pluginMigrationMode,
+    runPluginMigration,
     installProjectHarness,
     promptMcpSelection,
     mirrorMcpServersTo,
@@ -5988,6 +6334,9 @@ module.exports = {
     resolveFileConflict,
     buildKnownSourceHashes,
     initSessionManifest,
+    installTargetSkills,
+    stableOpenWikiScripts,
+    AGENTS_COPY_EXCLUDE,
     flushSessionManifest,
     copyDirRecursiveSync,
     INSTALL_MANIFEST_PATH,