@hybridlabor-api/aos 4.13.1 → 4.14.0

package/installer.js

@@ -526,12 +526,24 @@ function loadInstallManifest(customPath = null) {
     return {};
 }
 
+// Temp file in the same directory + rename: a crash mid-write cannot leave a truncated manifest.
+function writeFileAtomic(filePath, data) {
+    const tmp = `${filePath}.${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(tmp, data);
+        fs.renameSync(tmp, filePath);
+    } catch (e) {
+        try { fs.unlinkSync(tmp); } catch (_) {}
+        throw e;
+    }
+}
+
 function saveInstallManifest(manifest, customPath = null) {
     if (DRY_RUN) return;
     const manifestPath = customPath || getInstallManifestPath();
     try {
         fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
-        fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+        writeFileAtomic(manifestPath, JSON.stringify(manifest, null, 2));
     } catch (e) {
         log.warn(`Could not write install manifest: ${e.message}`);
     }
@@ -978,7 +990,11 @@ function detectInstallState() {
                 } catch (e) { logDebug(e, 'operation'); }
             }
         }
-        if (!localVersion) localVersion = '3.8.0';
+        if (!localVersion) {
+            // ponytail: placeholder only feeds the version display/compare; pruning is driven by the file manifest, not this value.
+            log.step('Previous AOS version is unknown (no manifest); assuming 3.8.0 for the update comparison only.');
+            localVersion = '3.8.0';
+        }
     }
 
     const basePath = scriptDir.includes('_npx') ? path.join(homeDir, '.agents') : path.dirname(srcDir);
@@ -1039,7 +1055,7 @@ function saveManifest(data = {}) {
             platform: process.platform,
             ...data
         });
-        fs.writeFileSync(manifestPath, JSON.stringify(updated, null, 2));
+        writeFileAtomic(manifestPath, JSON.stringify(updated, null, 2));
     } catch (e) { logDebug(e, 'manifest read/parse'); }
 }
 
@@ -1218,6 +1234,20 @@ function syncSkillEntry(fullPath, dirName, targetSkillDir, excludeSkills) {
     }
 }
 
+function redactSecrets(text) {
+    return String(text)
+        .replace(/([\w.-]*(?:key|token|secret|passw(?:or)?d|auth|credential)[\w.-]*\s*[=:]\s*)("[^"]*"|'[^']*'|\S+)/gi, '$1[redacted]')
+        .replace(/\bBearer\s+\S+/gi, 'Bearer [redacted]')
+        .replace(/\b(?:sk|ghp|gho|ghs|xox[a-z])[-_][A-Za-z0-9_-]{16,}/g, '[redacted]');
+}
+
+// execFileSync error -> one message that keeps the child's own stderr/stdout (last 2 KB, redacted).
+function describeExecError(e) {
+    const out = [e && e.stderr, e && e.stdout].map((b) => (b ? b.toString() : '').trim()).filter(Boolean).join('\n');
+    const head = redactSecrets(String((e && e.message) || e).split('\n')[0]).slice(0, 300);
+    return out ? `${head}\n${redactSecrets(out.slice(-2048))}` : head;
+}
+
 function installStep(what, fn, hint) {
     try {
         return { ok: true, value: fn() };
@@ -1937,7 +1967,7 @@ async function installMemB(interactive) {
     // banner. Stop at the module that could not be fetched.
     if (!downloadOrUpdateModule('@hybridlabor-api/memb', membDir, 'memB Vector Engine')) {
         log.warn('Skipping memB setup: the module could not be downloaded.');
-        return;
+        return false;
     }
     await installDeja();
     if (DRY_RUN) {
@@ -1945,6 +1975,7 @@ async function installMemB(interactive) {
         return;
     }
 
+    let membOk = true;
     const reqFile = path.join(membDir, 'requirements.txt');
     const serverPy = path.join(membDir, 'src', 'backend', 'server.py');
     if (fs.existsSync(reqFile)) {
@@ -2017,10 +2048,12 @@ async function installMemB(interactive) {
                 );
                 if (repaired && !verifyPythonImports(venvPython, membDir, importCheck)) {
                     log.warn('memB dependency repair did not pass the import check; inspect the venv before starting the daemon.');
+                    membOk = false;
                 }
             }
         } catch (e) {
             log.warn(`Failed memB standalone venv setup: ${e.message}`);
+            membOk = false;
         }
     }
 
@@ -2082,13 +2115,14 @@ async function installMemB(interactive) {
             } catch (e) { logDebug(e, 'windows memb daemon setup'); }
         }
     }
+    return membOk;
 }
 
 async function installSynapse() {
     const synapseDir = path.join(moduleBasePath(), 'bdb-synapse');
     if (!downloadOrUpdateModule('@hybridlabor-api/bdb-synapse', synapseDir, 'BDB Synapse')) {
         log.warn('Skipping Synapse setup: the module could not be downloaded.');
-        return;
+        return false;
     }
     if (DRY_RUN) {
         log.step('[dry-run] would link synapse binary into ~/.local/bin/synapse + setup background daemon');
@@ -2217,6 +2251,7 @@ async function installSynapse() {
         }
     } else {
         log.warn(`No pre-built binary for this platform. Compile with: cd "${synapseDir}" && go build -o ${binaryName} ./cmd/synapse/`);
+        return false;
     }
 }
 
@@ -2410,7 +2445,7 @@ async function installCreatorExtension() {
     const creatorDir = path.join(moduleBasePath(), 'bdb-dev-creator-extension');
     if (!downloadOrUpdateModule('@hybridlabor-api/bdb-dev-creator-extension', creatorDir, 'BDB Creator Extension')) {
         log.warn('Skipping Creator Extension setup: the module could not be downloaded.');
-        return;
+        return false;
     }
     if (DRY_RUN) {
         log.step('[dry-run] would run BDB Creator Extension setup');
@@ -2423,6 +2458,7 @@ async function installCreatorExtension() {
             : spawnSync('node', [installerScript, '--auto'], { stdio: 'inherit', cwd: creatorDir });
         if (setupResult.status !== 0) {
             log.warn(`Creator Extension setup note: exit code ${setupResult.status}`);
+            return false;
         }
     }
 }
@@ -2431,7 +2467,7 @@ async function installHardwarePcb() {
     const hwDir = path.join(moduleBasePath(), 'bdb-hardware-pcb');
     if (!downloadOrUpdateModule('@hybridlabor-api/bdb-hardware-pcb', hwDir, 'BDB Hardware & PCB (KiCad + OpenSCAD)')) {
         log.warn('Skipping Hardware & PCB setup: the module could not be downloaded.');
-        return;
+        return false;
     }
     if (DRY_RUN) {
         log.step('[dry-run] would run BDB Hardware & PCB setup');
@@ -2442,6 +2478,7 @@ async function installHardwarePcb() {
         const setupResult = spawnSync('node', [installerScript, '--auto'], { stdio: 'inherit', cwd: hwDir });
         if (setupResult.status !== 0) {
             log.warn(`Hardware & PCB setup note: exit code ${setupResult.status}`);
+            return false;
         }
     }
 }
@@ -2450,7 +2487,7 @@ async function installOSRemoteGateway() {
     const remoteDir = path.join(moduleBasePath(), 'bdb-os-remote');
     if (!downloadOrUpdateModule('@hybridlabor-api/bdb-os-remote', remoteDir, 'BDB OS Remote Gateway')) {
         log.warn('Skipping OS Remote Gateway setup: the module could not be downloaded.');
-        return;
+        return false;
     }
 }
 
@@ -2458,7 +2495,7 @@ async function installDevToolInstaller() {
     const toolInstallerDir = path.join(moduleBasePath(), 'bdb-dev-tool-installer');
     if (!downloadOrUpdateModule('@hybridlabor-api/bdb-dev-tool-installer', toolInstallerDir, 'BDB Dev Tool Installer')) {
         log.warn('Skipping Dev Tool Installer setup: the module could not be downloaded.');
-        return;
+        return false;
     }
 }
 
@@ -2470,7 +2507,7 @@ function aoSupportedHere() {
 async function installOSAgentWorkspace() {
     if (!aoSupportedHere()) {
         log.warn(`AO is not supported on ${process.platform}/${process.arch}.`);
-        return;
+        return false;
     }
 
     const isWin = process.platform === 'win32';
@@ -2491,7 +2528,7 @@ async function installOSAgentWorkspace() {
     } else {
         if (!downloadOrUpdateModule('@hybridlabor-api/bdb-agent-orchestrator', osAgentDir, 'BDB Agent Orchestrator')) {
             log.warn('Skipping AO setup: the module could not be downloaded.');
-            return;
+            return false;
         }
     }
     if (DRY_RUN) {
@@ -2566,16 +2603,13 @@ async function installOSAgentWorkspace() {
 
     if (!daemonBin) {
         log.warn(`AO binary missing in ${osAgentDir} — package layout changed or Go build needed.`);
-        return;
+        return false;
     }
 
     if (daemonBin !== binTarget) {
         installStep('place the ao binary', () => {
             fs.mkdirSync(localBinDir, { recursive: true });
-            fs.copyFileSync(daemonBin, binTarget);
-            if (!isWin) {
-                fs.chmodSync(binTarget, 0o755);
-            }
+            installBinaryAtomically(daemonBin, binTarget);
             log.step(`Installed ao to ${binTarget}`);
         }, 'AO cannot be started without its binary.');
     }
@@ -2602,9 +2636,14 @@ async function installOSAgentWorkspace() {
         }
     }
 
-    installStep('register the AO service', () => {
-        execFileSync(binTarget, ['service', 'install'], { stdio: 'ignore' });
+    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;
@@ -2660,6 +2699,9 @@ async function promptMemBIngestion(mcpCodeTarget) {
 }
 
 function verifyEcosystemInstallation() {
+    for (const f of moduleFailures) {
+        console.log(`  • ${colors.bold}${f.name}${colors.reset} ➔ ${colors.yellow}❌ NOT installed: ${f.reason.split('\n')[0]}${colors.reset}`);
+    }
     const modules = [
         { name: '1. bdb-synapse', pkg: '@hybridlabor-api/bdb-synapse', paths: [path.join(moduleBasePath(), 'bdb-synapse')] },
         { name: '2. memB', pkg: '@hybridlabor-api/memb', paths: [path.join(moduleBasePath(), 'memB'), path.join(geminiDir, 'config', 'mcps', 'memb-mcp')] },
@@ -2839,6 +2881,18 @@ function getTierExcludeSkills(tier) {
 // primary write above owns its file wholesale, but a secondary store belongs
 // to another product and is very likely to already hold the user's own
 // servers -- so this merges per server key and never replaces the file.
+// An unattended run has no credentials of its own (empty strings); those must never
+// replace a value the user already has in a server's env block.
+function keepExistingEnvValues(incomingServers, previousServers) {
+    for (const [key, incoming] of Object.entries(incomingServers || {})) {
+        const prevEnv = previousServers && previousServers[key] && previousServers[key].env;
+        if (!incoming || typeof incoming !== 'object' || !incoming.env || !prevEnv || typeof prevEnv !== 'object') continue;
+        for (const [k, v] of Object.entries(incoming.env)) {
+            if (v === '' && typeof prevEnv[k] === 'string' && prevEnv[k] !== '') incoming.env[k] = prevEnv[k];
+        }
+    }
+}
+
 function mirrorMcpServersTo(extraPaths, mcpConfigStr) {
     if (!Array.isArray(extraPaths) || extraPaths.length === 0) return;
 
@@ -2862,7 +2916,9 @@ function mirrorMcpServersTo(extraPaths, mcpConfigStr) {
             }
             const data = existing || {};
             data.mcpServers = data.mcpServers && typeof data.mcpServers === 'object' ? data.mcpServers : {};
-            for (const [key, val] of Object.entries(servers)) data.mcpServers[key] = val;
+            const mirrored = JSON.parse(JSON.stringify(servers));
+            keepExistingEnvValues(mirrored, data.mcpServers);
+            for (const [key, val] of Object.entries(mirrored)) data.mcpServers[key] = val;
             fs.mkdirSync(path.dirname(target), { recursive: true });
             // Carries injected API keys, same as the primary config. The `mode`
             // option only applies when writeFileSync CREATES the file -- an
@@ -3182,6 +3238,7 @@ async function installMcpsForTarget(paths, ctx) {
                     if (!incoming || typeof incoming !== 'object') return;
                     if (!incoming.env && previous.env) incoming.env = previous.env;
                 });
+                keepExistingEnvValues(newServers, oldServers);
                 oldConfig.mcpServers = Object.assign({}, oldServers, newServers);
                 fs.writeFileSync(paths.mcpConfigPath, JSON.stringify(oldConfig, null, 2), { mode: 0o600 });
                 try { fs.chmodSync(paths.mcpConfigPath, 0o600); } catch (e) { logDebug(e, 'chmod mcpConfigPath'); }
@@ -3260,7 +3317,16 @@ async function installMcpsForTarget(paths, ctx) {
 // spaces) rather than matching the first alphanumeric run anywhere in the
 // block, so it can't accidentally pick up a word from prose if the heading
 // format changes.
-function parseAgentsMd(content) {
+function loadCommonSkills(dir = srcDir) {
+    try {
+        const reg = JSON.parse(fs.readFileSync(path.join(dir, '.agents', 'nodes.json'), 'utf8'));
+        return Array.isArray(reg.common) ? reg.common.filter((s) => typeof s === 'string') : [];
+    } catch {
+        return [];
+    }
+}
+
+function parseAgentsMd(content, commonSkills = loadCommonSkills()) {
     const blocks = content.split(/\n## /).slice(1);
     const agents = [];
     for (const raw of blocks) {
@@ -3290,7 +3356,7 @@ function parseAgentsMd(content) {
             name,
             role: roleMatch[1].trim(),
             model: modelMatch ? modelMatch[1].trim() : null,
-            skills: extractListAfter('Primary Skills'),
+            skills: [...new Set([...extractListAfter('Primary Skills'), ...commonSkills])],
             mcpServers: extractListAfter('MCP Servers'),
             output: outputMatch ? outputMatch[1].trim() : null,
             systemPrompt: raw.trim(),
@@ -3708,6 +3774,21 @@ function installOpencodePlugin({ targetHome = homeDir, configPath = null, data =
         }
     }
 
+    // The plugin imports its decision logic from ./aos-hooks/ next to itself.
+    const hooksSrc = path.join(srcDir, '.claude', 'hooks');
+    if (fs.existsSync(hooksSrc)) {
+        try {
+            copyDirRecursiveSync(hooksSrc, path.join(opencodeDir, 'plugins', 'aos-hooks'));
+        } catch (e) {
+            log.error(`Could not install OpenCode plugin hooks (OpenCode gates inactive): ${e.message}`);
+        }
+    }
+
+    const trailLibSrc = path.join(srcDir, '.opencode', 'plugins', 'lib');
+    if (fs.existsSync(trailLibSrc)) {
+        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.
     const commandsSrc = path.join(srcDir, '.opencode', 'commands');
@@ -3906,23 +3987,25 @@ 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', 'graph-gate.mjs', 'memb-inject.mjs', 'trail-relay.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs'];
+    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'];
     // 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
     // design. Pointing it at $CLAUDE_PROJECT_DIR would make it fail on every
     // prompt in any project the harness was never installed into. trail-relay
     // talks to machine-global live-map daemons, so it is anchored the same way.
-    const machineGlobalHooks = ['memb-inject.mjs', 'trail-relay.mjs'];
+    const machineGlobalHooks = ['memb-inject.mjs', 'trail-relay.mjs', 'trail-autostart.mjs'];
     const isBdbEntry = (entry) => {
         const cmds = (entry && Array.isArray(entry.hooks) ? entry.hooks : [])
             .map((h) => (h && typeof h.command === 'string' ? h.command : ''))
             .join(' ');
         return bdbHookScripts.some((name) => cmds.includes(name));
     };
-    const localize = (cmd) => (projectLocal && !machineGlobalHooks.some((n) => cmd.includes(n))
-        ? cmd.split('${HOME}').join('$CLAUDE_PROJECT_DIR')
-        : cmd);
+    // Global installs must point at the copies installGlobalHooks put under
+    // $HOME/.claude/hooks; $CLAUDE_PROJECT_DIR would not exist in other projects.
+    const localize = (cmd) => (projectLocal
+        ? (machineGlobalHooks.some((n) => cmd.includes(n)) ? cmd : cmd.split('${HOME}').join('$CLAUDE_PROJECT_DIR'))
+        : cmd.split('$CLAUDE_PROJECT_DIR/.claude/hooks/').join('$HOME/.claude/hooks/'));
     const cloneBdbEntries = (entries) =>
         JSON.parse(JSON.stringify(entries)).map((e) => ({
             ...e,
@@ -3969,7 +4052,16 @@ function mergeBdbSettingsHooks(settingsPath, { projectLocal = false } = {}) {
 
     try {
         fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
-        fs.writeFileSync(settingsPath, JSON.stringify(buildMerged(existing), null, 2) + '\n');
+        const tmpPath = `${settingsPath}.${process.pid}.tmp`;
+        if (existing) {
+            fs.copyFileSync(settingsPath, `${settingsPath}.${process.hrtime.bigint()}.bak`);
+            const dir = path.dirname(settingsPath);
+            const base = path.basename(settingsPath);
+            const baks = fs.readdirSync(dir).filter((f) => f.startsWith(`${base}.`) && /\.\d{13,}\.bak$/.test(f)).sort();
+            for (const old of baks.slice(0, -3)) fs.rmSync(path.join(dir, old), { force: true });
+        }
+        fs.writeFileSync(tmpPath, JSON.stringify(buildMerged(existing), null, 2) + '\n', { mode: existing ? fs.statSync(settingsPath).mode & 0o777 : 0o644 });
+        fs.renameSync(tmpPath, settingsPath);
     } catch (e) {
         log.warn(`Could not write ${settingsPath}: ${e.message}`);
     }
@@ -3979,60 +4071,64 @@ function mergeBdbSettingsHooks(settingsPath, { projectLocal = false } = {}) {
 // ~/.gemini/config/hooks.json), preserving user-defined foreign hooks.
 function mergeAntigravityHooks(hooksPath, { projectLocal = false } = {}) {
     const bdbHookScripts = ['go-gate.mjs', 'graph-gate.mjs', 'memb-inject.mjs', 'startcycle-dispatch.mjs', 'trail-relay.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs'];
-    const isBdbEntry = (entry) => {
-        const cmds = (entry && Array.isArray(entry.hooks) ? entry.hooks : [entry])
-            .map((h) => (h && typeof h.command === 'string' ? h.command : (typeof h === 'string' ? h : '')))
-            .join(' ');
-        return bdbHookScripts.some((name) => cmds.includes(name));
-    };
+    const isBdbHandler = (h) => typeof h?.command === 'string' && bdbHookScripts.some((name) => h.command.includes(name));
 
     const baseDir = path.dirname(hooksPath);
     const hooksDir = projectLocal ? path.join(currentDir, '.agents', 'hooks') : path.join(baseDir, 'hooks');
     const workflowsDir = projectLocal ? path.join(currentDir, '.agents', 'workflows') : path.join(baseDir, 'workflows');
     const globalHooksDir = projectLocal ? path.join(homeDir, '.gemini', 'config', 'hooks') : hooksDir;
 
+    const cmd = (dir, script, args = '') => `node "${path.join(dir, script)}"${args}`;
     const bdbHooks = {
         PreToolUse: [
             {
                 matcher: "run_command|Bash",
                 hooks: [
-                    { type: "command", command: `node "${path.join(hooksDir, 'go-gate.mjs')}"`, timeout: 10000 },
-                    { type: "command", command: `node "${path.join(hooksDir, 'conventional-commits.mjs')}"`, timeout: 10000 }
+                    { type: "command", command: cmd(hooksDir, 'go-gate.mjs'), timeout: 10 },
+                    { type: "command", command: cmd(hooksDir, 'conventional-commits.mjs'), timeout: 10 }
                 ]
             },
             {
                 matcher: "write_file|edit_file|replace|Write|Edit|MultiEdit",
-                hooks: [{ type: "command", command: `node "${path.join(hooksDir, 'env-file-protection.mjs')}"`, timeout: 10000 }]
+                hooks: [{ type: "command", command: cmd(hooksDir, 'env-file-protection.mjs'), timeout: 10 }]
             },
             {
-                hooks: [{ type: "command", command: `node "${path.join(globalHooksDir, 'trail-relay.mjs')}" --agent agy --event PreToolUse`, timeout: 2000 }]
+                matcher: "*",
+                hooks: [{ type: "command", command: cmd(globalHooksDir, 'trail-relay.mjs', ' --agent agy --event PreToolUse'), timeout: 2 }]
             }
         ],
         Stop: [
-            {
-                hooks: [{ type: "command", command: `node "${path.join(hooksDir, 'graph-gate.mjs')}"`, timeout: 10000 }]
-            },
-            {
-                hooks: [{ type: "command", command: `node "${path.join(globalHooksDir, 'trail-relay.mjs')}" --agent agy --event Stop`, timeout: 2000 }]
-            }
+            { type: "command", command: cmd(hooksDir, 'graph-gate.mjs'), timeout: 10 },
+            { type: "command", command: cmd(globalHooksDir, 'trail-relay.mjs', ' --agent agy --event Stop'), timeout: 2 }
         ],
         PreInvocation: [
-            {
-                hooks: [
-                    { type: "command", command: `node "${path.join(globalHooksDir, 'memb-inject.mjs')}"`, timeout: 8000 },
-                    { type: "command", command: `node "${path.join(workflowsDir, 'startcycle-dispatch.mjs')}"`, timeout: 30000 }
-                ]
-            }
+            { type: "command", command: cmd(globalHooksDir, 'memb-inject.mjs'), timeout: 8 },
+            { type: "command", command: cmd(workflowsDir, 'startcycle-dispatch.mjs'), timeout: 30 }
         ]
     };
 
+    // Drops BDB handlers (old wrapped or current shape), keeps foreign ones, and
+    // rewraps flat events so previously written `{ hooks: [...] }` entries migrate.
+    const keepForeign = (event, entries) => {
+        const out = [];
+        for (const e of Array.isArray(entries) ? entries : []) {
+            const nested = e && Array.isArray(e.hooks);
+            if (bdbHooks[event][0].hooks) {
+                if (!nested) { if (!isBdbHandler(e)) out.push(e); continue; }
+                const kept = e.hooks.filter((h) => !isBdbHandler(h));
+                if (kept.length) out.push({ ...e, hooks: kept });
+            } else {
+                out.push(...(nested ? e.hooks : [e]).filter((h) => !isBdbHandler(h)));
+            }
+        }
+        return out;
+    };
+
     const buildMerged = (existing) => {
         const merged = existing && typeof existing === 'object' ? existing : {};
         merged.hooks = merged.hooks && typeof merged.hooks === 'object' ? merged.hooks : {};
         for (const [event, entries] of Object.entries(bdbHooks)) {
-            const foreignEntries = (Array.isArray(merged.hooks[event]) ? merged.hooks[event] : [])
-                .filter((e) => !isBdbEntry(e));
-            merged.hooks[event] = [...foreignEntries, ...entries];
+            merged.hooks[event] = [...keepForeign(event, merged.hooks[event]), ...entries];
         }
         return merged;
     };
@@ -4064,7 +4160,9 @@ function mergeAntigravityHooks(hooksPath, { projectLocal = false } = {}) {
 
     try {
         fs.mkdirSync(path.dirname(hooksPath), { recursive: true });
-        fs.writeFileSync(hooksPath, JSON.stringify(buildMerged(existing), null, 2) + '\n');
+        const tmpPath = `${hooksPath}.${process.pid}.tmp`;
+        fs.writeFileSync(tmpPath, JSON.stringify(buildMerged(existing), null, 2) + '\n');
+        fs.renameSync(tmpPath, hooksPath);
     } catch (e) {
         log.warn(`Could not write ${hooksPath}: ${e.message}`);
     }
@@ -4178,13 +4276,35 @@ function mergeCodexTomlHooks(configTomlPath, { projectLocal = false } = {}) {
         }
     }
 
-    // Replace existing AOS:HOOKS block or append
-    const hookBlockRegex = /# AOS:HOOKS:START[\s\S]*?# AOS:HOOKS:END/;
-    if (hookBlockRegex.test(content)) {
-        content = content.replace(hookBlockRegex, tomlSnippet);
-    } else {
-        content = `${content.trimEnd()}\n\n${tomlSnippet}\n`;
-    }
+    // Drop every AOS hook entry (marker block or not, duplicates included), then append one fresh block.
+    const bdbCodexScripts = ['go-gate.mjs', 'graph-gate.mjs', 'memb-inject.mjs', 'trail-relay.mjs', 'startcycle-dispatch.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs'];
+    const isAosMarker = (l) => /^\s*# AOS:HOOKS:(START|END)\s*$/.test(l);
+    const eol = content.includes('\r\n') ? '\r\n' : '\n';
+    const lines = content.split(/\r?\n/).filter((l) => !isAosMarker(l));
+    const sections = [];
+    for (const l of lines) {
+        if (/^\s*\[/.test(l) || !sections.length) sections.push([l]);
+        else sections[sections.length - 1].push(l);
+    }
+    const isHookHeader = (sec) => /^\s*\[\[hooks\.\w+\]\]\s*$/.test(sec[0]);
+    const isHookInner = (sec) => /^\s*\[\[hooks\.\w+\.hooks\]\]\s*$/.test(sec[0]);
+    const kept = [];
+    for (let i = 0; i < sections.length; i++) {
+        if (!isHookHeader(sections[i])) { kept.push(sections[i]); continue; }
+        let j = i + 1;
+        while (j < sections.length && isHookInner(sections[j])) j++;
+        const group = sections.slice(i, j);
+        const ours = group.some((sec) => sec.some((l) => /^\s*command\s*=/.test(l) && bdbCodexScripts.some((n) => l.includes(n))));
+        if (ours) {
+            // keep trailing blanks/comments (they may belong to another tool's marker)
+            const tail = group.flat();
+            let end = tail.length;
+            while (end > 0 && /^\s*(#.*)?$/.test(tail[end - 1])) end--;
+            if (end < tail.length) kept.push(tail.slice(end));
+        } else kept.push(...group);
+        i = j - 1;
+    }
+    content = `${kept.flat().join(eol).trimEnd()}${eol}${eol}${tomlSnippet.split('\n').join(eol)}${eol}`;
 
     try {
         fs.mkdirSync(path.dirname(configTomlPath), { recursive: true });
@@ -4350,13 +4470,33 @@ async function promptOptionalModules(installedModules) {
         required: false
     }));
 
+    return (await runModuleInstalls(allModules, chosen, installedModules)).installed;
+}
+
+// Module installers return false (or throw) on failure; undefined/true mean success.
+// Only successes are recorded, so the manifest never claims a module that is not there.
+const moduleFailures = [];
+async function runModuleInstalls(allModules, chosen, installedModules) {
+    const installed = [];
+    const failed = [];
     for (const mod of allModules) {
-        if (chosen.includes(mod.id)) {
-            await mod.fn();
-            installedModules.push(mod.id);
+        if (!chosen.includes(mod.id)) continue;
+        let reason = null;
+        try {
+            if (await mod.fn() === false) reason = 'installation reported a failure (see warnings above)';
+        } catch (e) {
+            reason = e && e.message ? e.message : String(e);
+        }
+        if (reason === null) {
+            installed.push(mod.id);
+            if (!installedModules.includes(mod.id)) installedModules.push(mod.id);
+        } else {
+            failed.push({ id: mod.id, name: mod.name, reason });
+            moduleFailures.push({ id: mod.id, name: mod.name, reason });
+            log.warn(`${mod.name} was not installed: ${reason}`);
         }
     }
-    return chosen;
+    return { installed, failed };
 }
 
 // Module ids whose daemons ship a web interface or background service worth
@@ -4397,6 +4537,107 @@ function shouldAutostartLaunchpad(overrides = {}) {
     return isDevEnvironment(overrides);
 }
 
+// Plan Canvas autostart is strictly opt-in (--autostart-plan-canvas): unlike
+// the launchpad opener it is NOT implied by a dev checkout. The server never
+// idle-exits there (AOS_PLAN_CANVAS_IDLE_MS=0 is honoured by server.js).
+const PLAN_CANVAS_LABEL = 'com.bdb.plan-canvas';
+
+function shouldAutostartPlanCanvas(overrides = {}) {
+    const argv = overrides.argv || process.argv;
+    return argv.includes('--autostart-plan-canvas');
+}
+
+function buildPlanCanvasPlist({ nodeBin, scriptPath, home, logDir }) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${PLAN_CANVAS_LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${nodeBin}</string>
+        <string>${scriptPath}</string>
+        <string>server</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>AOS_PLAN_CANVAS_IDLE_MS</key>
+        <string>0</string>
+    </dict>
+    <key>WorkingDirectory</key>
+    <string>${home}</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>ThrottleInterval</key>
+    <integer>30</integer>
+    <key>StandardOutPath</key>
+    <string>${path.join(logDir, 'plan-canvas.stdout.log')}</string>
+    <key>StandardErrorPath</key>
+    <string>${path.join(logDir, 'plan-canvas.stderr.log')}</string>
+</dict>
+</plist>`;
+}
+
+// Same bat + hidden-vbs-in-Startup mechanism as the OpenWiki visualizer.
+function buildPlanCanvasWinFiles({ nodeBin, scriptPath, home, logDir, batPath }) {
+    const out = path.join(logDir, 'plan-canvas.stdout.log');
+    const err = path.join(logDir, 'plan-canvas.stderr.log');
+    return {
+        bat: `@echo off\r\ncd /d "${home}"\r\nset AOS_PLAN_CANVAS_IDLE_MS=0\r\n"${nodeBin}" "${scriptPath}" server >> "${out}" 2>> "${err}"\r\n`,
+        vbs: `Set WshShell = CreateObject("WScript.Shell")\r\nWshShell.CurrentDirectory = "${home}"\r\nWshShell.Run """${batPath}""", 0, False\r\n`,
+    };
+}
+
+function installPlanCanvasAutostart(overrides = {}) {
+    if (!shouldAutostartPlanCanvas(overrides)) return false;
+    if ((overrides.dryRun ?? DRY_RUN)) {
+        log.step('[dry-run] would register the Plan Canvas background server (Port 4519, no idle exit)');
+        return false;
+    }
+    const home = overrides.homeDir || homeDir;
+    const platform = overrides.platform || process.platform;
+    const scriptPath = [
+        path.join(home, '.agents', 'skills', 'plan-canvas', 'scripts', 'plan-canvas.js'),
+        path.join(srcDir, 'skills', 'global_config', 'plan-canvas', 'scripts', 'plan-canvas.js'),
+    ].find(p => fs.existsSync(p));
+    if (!scriptPath) {
+        log.warn('Plan Canvas autostart skipped: plan-canvas.js not found. Start it with: aos-plan-canvas server');
+        return false;
+    }
+    const nodeBin = overrides.nodeBin || process.execPath;
+    const logDir = path.join(home, '.agents', 'logs');
+    try {
+        fs.mkdirSync(logDir, { recursive: true });
+        if (platform === 'darwin') {
+            const plistPath = path.join(home, 'Library', 'LaunchAgents', `${PLAN_CANVAS_LABEL}.plist`);
+            fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+            fs.writeFileSync(plistPath, buildPlanCanvasPlist({ nodeBin, scriptPath, home, logDir }));
+            if (!overrides.skipLaunchctl) {
+                execSync(`launchctl unload "${plistPath}" 2>/dev/null || true`, { stdio: 'ignore' });
+                execSync(`launchctl load -w "${plistPath}" 2>/dev/null || true`, { stdio: 'ignore' });
+            }
+            log.success('Plan Canvas LaunchAgent registered (Port 4519)');
+        } else if (platform === 'win32') {
+            const startupDir = path.join(overrides.appData || process.env.APPDATA || path.join(home, 'AppData', 'Roaming'), 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup');
+            fs.mkdirSync(startupDir, { recursive: true });
+            const batPath = path.join(home, '.agents', 'run-plan-canvas.bat');
+            const vbsPath = path.join(startupDir, `${PLAN_CANVAS_LABEL}.vbs`);
+            const files = buildPlanCanvasWinFiles({ nodeBin, scriptPath, home, logDir, batPath });
+            fs.writeFileSync(batPath, files.bat, 'utf-8');
+            fs.writeFileSync(vbsPath, files.vbs, 'utf-8');
+            if (!overrides.skipLaunchctl) spawn('wscript.exe', [vbsPath], { detached: true, stdio: 'ignore' }).unref();
+            log.success('Plan Canvas Startup entry registered (Port 4519)');
+        } else {
+            log.step('Plan Canvas autostart is only wired for macOS and Windows. Start it with: aos-plan-canvas server');
+            return false;
+        }
+        return true;
+    } catch (e) { logDebug(e, 'plan canvas autostart'); return false; }
+}
+
 function generateAndOpenLaunchpad(installedModules = []) {
     if (DRY_RUN) {
         log.step('[dry-run] would generate & open BDB Launchpad HTML');
@@ -4532,6 +4773,16 @@ function generateAndOpenLaunchpad(installedModules = []) {
     .card.offline .card-hint {
       display: block;
     }
+    .card-hint code {
+      font-family: var(--mono);
+      font-style: normal;
+      color: #ffffff;
+      background: #0a0a0a;
+      border: 1px solid var(--accent);
+      border-radius: 4px;
+      padding: 1px 6px;
+      cursor: copy;
+    }
     .footer {
       margin-top: 28px;
       text-align: center;
@@ -4722,6 +4973,25 @@ function generateAndOpenLaunchpad(installedModules = []) {
           <span class="status-dot" id="dot-store" title="Checking..."></span>
         </div>
       </a>
+      <a class="card" href="http://127.0.0.1:4519/" target="_blank">
+        <div class="card-content">
+          <div class="card-icon"><svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+            <defs><linearGradient id="grad-plancanvas" x1="50%" y1="0%" x2="50%" y2="100%"><stop offset="0%" stop-color="#FFFFFF"/><stop offset="100%" stop-color="#9b30c4"/></linearGradient></defs>
+            <rect x="18" y="22" width="64" height="56" rx="4" fill="url(#grad-plancanvas)" opacity="0.85"/>
+            <rect x="26" y="30" width="22" height="14" rx="1.5" fill="#0a0a0a" opacity="0.6"/><rect x="52" y="30" width="22" height="14" rx="1.5" fill="#0a0a0a" opacity="0.6"/>
+            <line x1="26" y1="54" x2="74" y2="54" stroke="#0a0a0a" stroke-width="2.5" opacity="0.5"/><line x1="26" y1="64" x2="56" y2="64" stroke="#0a0a0a" stroke-width="2.5" opacity="0.5"/>
+          </svg></div>
+          <div class="card-info">
+            <h2>Plan Canvas</h2>
+            <p>Review plans in the browser: annotate, chat, approve</p>
+            <div class="card-hint">offline — run: <code data-copy="aos-plan-canvas server" title="Click to copy">aos-plan-canvas server</code></div>
+          </div>
+        </div>
+        <div class="card-meta">
+          <span class="port-pill">:4519</span>
+          <span class="status-dot" id="dot-plancanvas" title="Checking..."></span>
+        </div>
+      </a>
     </div>
     <div class="footer">
       <span>Autostart Daemons • 127.0.0.1</span>
@@ -4749,7 +5019,26 @@ function generateAndOpenLaunchpad(installedModules = []) {
       checkHealth('http://127.0.0.1:9080', 'dot-remote');
       checkHealth('http://127.0.0.1:4321', 'dot-openwiki');
       checkHealth('http://127.0.0.1:4322', 'dot-store');
-    }
+      checkHealth('http://127.0.0.1:4519', 'dot-plancanvas');
+    }
+    document.addEventListener('click', (ev) => {
+      const el = ev.target.closest && ev.target.closest('[data-copy]');
+      if (!el) return;
+      ev.preventDefault();
+      ev.stopPropagation();
+      const text = el.getAttribute('data-copy');
+      const fallback = () => {
+        const ta = document.createElement('textarea');
+        ta.value = text;
+        document.body.appendChild(ta);
+        ta.select();
+        try { document.execCommand('copy'); } catch (e) {}
+        ta.remove();
+      };
+      if (navigator.clipboard && navigator.clipboard.writeText) navigator.clipboard.writeText(text).catch(fallback);
+      else fallback();
+      el.title = 'Copied';
+    }, true);
     checkAllHealth();
     setInterval(checkAllHealth, 5000);
   </script>
@@ -4962,6 +5251,7 @@ async function universalHarnessSync(primaryMcpConfigPath, installedModules = [])
     }
     log.success('Universal Sync Complete!');
     generateAndOpenLaunchpad(installedModules);
+    installPlanCanvasAutostart();
 }
 
 async function runQuickUpdate(installState) {
@@ -5128,7 +5418,41 @@ function installAosCli() {
     }
 }
 
+// A running daemon may execute dest; overwriting its inode keeps stale code-signature
+// state on macOS and every new exec dies with SIGKILL. Rename gives dest a fresh inode.
+function installBinaryAtomically(src, dest) {
+    const tmp = path.join(path.dirname(dest), `.${path.basename(dest)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+        fs.copyFileSync(src, tmp);
+        if (process.platform !== 'win32') fs.chmodSync(tmp, 0o755);
+        fs.renameSync(tmp, dest);
+    } catch (e) {
+        try { fs.unlinkSync(tmp); } catch (_) {}
+        throw e;
+    }
+}
+
 async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes('--version') || args.includes('-V')) {
+        console.log(pkg.version);
+        return;
+    }
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log(`Usage: aos [command] [options]
+
+Commands:
+  store            Browse and install skills
+  doctor|checkup   Check the installation
+
+Options:
+  -y, --yes        Non-interactive install (implied without a TTY)
+  --dry-run        Show what would change
+  --verbose, -v    Verbose output
+  -V, --version    Print the version and exit
+  -h, --help       Print this help and exit`);
+        return;
+    }
     if (process.argv[2] === 'store') {
         const storeScript = path.join(srcDir, 'bin', 'aos-store.mjs');
         const result = spawnSync(process.execPath, [storeScript, ...process.argv.slice(3)], { stdio: 'inherit' });
@@ -5582,10 +5906,14 @@ if (require.main === module) {
 
 // Exported for tests -- requiring installer.js must not launch the TUI.
 module.exports = {
+    installBinaryAtomically,
     installOSAgentWorkspace,
     downloadOrUpdateModule,
     detectPlatforms,
     markPlatformsExplicit,
+    runModuleInstalls,
+    describeExecError,
+    keepExistingEnvValues,
     mergeBdbSettingsHooks,
     mergeAntigravityHooks,
     mergeCodexTomlHooks,
@@ -5610,6 +5938,7 @@ module.exports = {
     INSTALL_MANIFEST_PATH,
     // Agent compilers & pipeline helpers
     parseAgentsMd,
+    loadCommonSkills,
     compileClaudeAgents,
     compileOpenCodeAgents,
     compileCodexAgents,
@@ -5620,6 +5949,10 @@ module.exports = {
     generateAndOpenLaunchpad,
     shouldOpenLaunchpad,
     shouldAutostartLaunchpad,
+    shouldAutostartPlanCanvas,
+    buildPlanCanvasPlist,
+    buildPlanCanvasWinFiles,
+    installPlanCanvasAutostart,
     isDevEnvironment,
     LAUNCHPAD_WEB_MODULES,
     LAUNCHPAD_OPEN_FLAGS,