@hybridlabor-api/aos 4.6.6 → 4.7.1

package/installer.js

@@ -1828,6 +1828,50 @@ function moduleBasePath() {
     return scriptDir.includes('_npx') ? path.join(os.homedir(), '.agents') : path.dirname(srcDir);
 }
 
+// deja resolves its exclude file as $XDG_CONFIG_HOME/deja/exclude, falling
+// back to $HOME/.config on ALL platforms including Windows -- do not switch
+// this to os.UserConfigDir()/APPDATA, deja would never read that file there.
+function ensureDejaExclude(excludePath) {
+    fs.mkdirSync(path.dirname(excludePath), { recursive: true });
+    let existing = '';
+    if (fs.existsSync(excludePath)) {
+        existing = fs.readFileSync(excludePath, 'utf8');
+    }
+    // deja skips comment lines when matching, so a '# secret' line does not
+    // count as the pattern being present. Only a line trimming to exactly
+    // 'secret' counts -- never rewrite, reorder or deduplicate user lines.
+    if (existing.split(/\r?\n/).some(line => line.trim() === 'secret')) return false;
+    let content = existing;
+    if (content.length > 0 && !content.endsWith('\n')) content += '\n';
+    fs.writeFileSync(excludePath, `${content}secret\n`);
+    return true;
+}
+
+async function installDeja() {
+    if (DRY_RUN) {
+        log.step('[dry-run] would install deja-vu 0.21.1 globally and add its exclude pattern');
+        return;
+    }
+    try {
+        log.step('Installing deja-vu session memory...');
+        execSync('npm install -g @vshulcz/deja-vu@0.21.1', { stdio: 'ignore' });
+    } catch (e) {
+        log.warn('deja-vu install failed. Install later with: npm install -g @vshulcz/deja-vu@0.21.1');
+    }
+    if (!hasExecutable('deja')) {
+        log.warn('deja is not on PATH. Install it with: npm install -g @vshulcz/deja-vu@0.21.1');
+    }
+    const base = process.env.XDG_CONFIG_HOME || path.join(homeDir, '.config');
+    const excludePath = path.join(base, 'deja', 'exclude');
+    try {
+        if (ensureDejaExclude(excludePath)) {
+            log.step(`Added 'secret' to the deja exclude list at ${excludePath}`);
+        }
+    } catch (e) {
+        log.warn(`Could not update the deja exclude list at ${excludePath}: ${e.message}. Add the line 'secret' to it by hand.`);
+    }
+}
+
 async function installMemB(interactive) {
     let installWebUI = true;
     if (interactive && !isAutoYes) {
@@ -1845,6 +1889,7 @@ async function installMemB(interactive) {
         log.warn('Skipping memB setup: the module could not be downloaded.');
         return;
     }
+    await installDeja();
     if (DRY_RUN) {
         log.step('[dry-run] would bootstrap memB venv + pip requirements');
         return;
@@ -2846,6 +2891,13 @@ async function installMcpsForTarget(paths, ctx) {
     const skippedMcpConfigKeys = resolveUnsupportedMcpConfigKeys();
     try {
         const parsedMcpConfig = JSON.parse(mcpConfigStr);
+        // npm's Windows shim is deja.cmd, which Node refuses to spawn without
+        // a shell (EINVAL since the CVE-2024-27980 fix) -- wrap the command in
+        // cmd /c here so every generated config, the Codex TOML block and the
+        // ~/.claude.json mirror get the launchable form.
+        if (process.platform === 'win32' && parsedMcpConfig.mcpServers.deja) {
+            parsedMcpConfig.mcpServers.deja = { command: 'cmd', args: ['/c', 'deja', 'mcp'] };
+        }
         const finalMcpServers = {};
         const availableFolders = fs.readdirSync(mcpSrcDir);
 
@@ -2903,7 +2955,7 @@ async function installMcpsForTarget(paths, ctx) {
             ? path.join(mcpCodeTarget, 'memb-mcp', '.venv', 'Scripts', 'python.exe')
             : path.join(mcpCodeTarget, 'memb-mcp', '.venv', 'bin', 'python');
         const pythonBinValue = pythonBinPath.split('\\').join('/');
-        const geminiKeyValue = creds.gemini || process.env.GEMINI_API_KEY || '';
+        const geminiKeyValue = (creds.keyEnvName === 'GEMINI_API_KEY' ? creds.gemini : '') || process.env.GEMINI_API_KEY || '';
         mcpConfigStr = mcpConfigStr.replace(/__PYTHON_BIN__/g, () => JSON.stringify(pythonBinValue).slice(1, -1));
         mcpConfigStr = mcpConfigStr.replace(/__GEMINI_API_KEY__/g, () => JSON.stringify(geminiKeyValue).slice(1, -1));
     }
@@ -2939,39 +2991,12 @@ async function installMcpsForTarget(paths, ctx) {
     if (!mcpTemplate.ok) {
         log.warn(`No MCP config was written: the template could not be read. ${configName} left untouched.`);
     } else if (isTomlConfig) {
-        const snippetPath = `${paths.mcpConfigPath}.bdb-mcp-servers.toml`;
-        const tomlKey = (k) => (/^[A-Za-z0-9_-]+$/.test(k) ? k : JSON.stringify(k));
-        const tomlValue = (v) => {
-            if (Array.isArray(v)) return `[${v.map(tomlValue).join(', ')}]`;
-            if (v && typeof v === 'object') {
-                const pairs = Object.entries(v).map(([k, x]) => `${tomlKey(k)} = ${tomlValue(x)}`);
-                return `{ ${pairs.join(', ')} }`;
-            }
-            if (typeof v === 'number' || typeof v === 'boolean') return String(v);
-            return JSON.stringify(String(v));
-        };
         try {
-            const servers = JSON.parse(mcpConfigStr).mcpServers || {};
-            const tables = Object.entries(servers).map(([name, cfg]) => {
-                const rows = [`[mcp_servers.${tomlKey(name)}]`];
-                Object.entries(cfg || {}).forEach(([k, v]) => rows.push(`${tomlKey(k)} = ${tomlValue(v)}`));
-                return rows.join('\n');
-            });
-            const snippet = [
-                '# BDB MCP servers for Codex, generated by installer.beta.js.',
-                `# Append these tables to ${configName}; if you ran the installer`,
-                '# before, replace the [mcp_servers.*] tables of the same name',
-                '# instead of adding them a second time.',
-                '',
-                tables.join('\n\n'),
-                ''
-            ].join('\n');
-            // Snippets can embed injected API keys — keep them user-readable only.
-            fs.writeFileSync(snippetPath, snippet, { mode: 0o600 });
-            try { fs.chmodSync(snippetPath, 0o600); } catch (e) { logDebug(e, 'chmod snippetPath'); }
-            log.warn(`${configName} is TOML; written as snippet instead: ${snippetPath}`);
+            const skipped = mergeCodexTomlMcpServers(paths.mcpConfigPath, JSON.parse(mcpConfigStr).mcpServers || {});
+            log.step(`Merged BDB MCP servers into ${configName}`);
+            if (skipped.length) log.step(`Kept your own entries for: ${skipped.join(', ')}`);
         } catch (e) {
-            log.warn(`Could not write the Codex TOML snippet: ${e.message}`);
+            log.warn(`Could not merge MCP servers into ${configName}: ${e.message}`);
         }
     } else if (mode === 'merge' && fs.existsSync(paths.mcpConfigPath) && !existingConfigIsEmpty()) {
         const oldConfig = readJsonFile(paths.mcpConfigPath);
@@ -3583,7 +3608,7 @@ function installGlobalBinaries() {
     }
 
     const isWin = process.platform === 'win32';
-    const cliBins = ['aos-config', 'aos-dashboard', 'aos-uninstall'];
+    const cliBins = ['aos-config', 'aos-dashboard', 'aos-uninstall', 'aos-store', 'aos-doctor'];
 
     for (const name of cliBins) {
         const targetMjs = path.join(globalAgentsBin, `${name}.mjs`);
@@ -3626,13 +3651,14 @@ 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'];
+    const bdbHookScripts = ['go-gate.mjs', 'graph-gate.mjs', 'memb-inject.mjs', 'trail-relay.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.
-    const machineGlobalHooks = ['memb-inject.mjs'];
+    // 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 isBdbEntry = (entry) => {
         const cmds = (entry && Array.isArray(entry.hooks) ? entry.hooks : [])
             .map((h) => (h && typeof h.command === 'string' ? h.command : ''))
@@ -3697,7 +3723,7 @@ function mergeBdbSettingsHooks(settingsPath, { projectLocal = false } = {}) {
 // Merge the BDB hooks into Google Antigravity's hooks.json (.agents/hooks.json or
 // ~/.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'];
+    const bdbHookScripts = ['go-gate.mjs', 'graph-gate.mjs', 'memb-inject.mjs', 'startcycle-dispatch.mjs', 'trail-relay.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 : '')))
@@ -3715,11 +3741,17 @@ function mergeAntigravityHooks(hooksPath, { projectLocal = false } = {}) {
             {
                 matcher: "run_command|Bash",
                 hooks: [{ type: "command", command: `node "${path.join(hooksDir, 'go-gate.mjs')}"`, timeout: 10000 }]
+            },
+            {
+                hooks: [{ type: "command", command: `node "${path.join(globalHooksDir, 'trail-relay.mjs')}" --agent agy --event PreToolUse`, timeout: 2000 }]
             }
         ],
         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 }]
             }
         ],
         PreInvocation: [
@@ -3776,6 +3808,46 @@ function mergeAntigravityHooks(hooksPath, { projectLocal = false } = {}) {
     }
 }
 
+// Writes the AOS MCP servers into Codex's config.toml between AOS:MCP markers,
+// replacing the block on re-runs. A server the user already declared outside the
+// block is skipped: a second [mcp_servers.<name>] table would make the file invalid TOML.
+function mergeCodexTomlMcpServers(configTomlPath, servers) {
+    const tomlKey = (k) => (/^[A-Za-z0-9_-]+$/.test(k) ? k : JSON.stringify(k));
+    const tomlValue = (v) => {
+        if (Array.isArray(v)) return `[${v.map(tomlValue).join(', ')}]`;
+        if (v && typeof v === 'object') {
+            const pairs = Object.entries(v).map(([k, x]) => `${tomlKey(k)} = ${tomlValue(x)}`);
+            return `{ ${pairs.join(', ')} }`;
+        }
+        if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+        return JSON.stringify(String(v));
+    };
+    let content = fs.existsSync(configTomlPath) ? fs.readFileSync(configTomlPath, 'utf8') : '';
+    const blockRegex = /# AOS:MCP:START[\s\S]*?# AOS:MCP:END\n?/;
+    const outside = content.replace(blockRegex, '');
+    const tables = [];
+    const skipped = [];
+    Object.entries(servers || {}).forEach(([name, cfg]) => {
+        const header = `[mcp_servers.${tomlKey(name)}]`;
+        const headerRegex = new RegExp(`^${header.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`, 'm');
+        if (headerRegex.test(outside)) { skipped.push(name); return; }
+        const rows = [header];
+        Object.entries(cfg || {}).forEach(([k, v]) => rows.push(`${tomlKey(k)} = ${tomlValue(v)}`));
+        tables.push(rows.join('\n'));
+    });
+    const block = ['# AOS:MCP:START', tables.join('\n\n'), '# AOS:MCP:END'].join('\n');
+    if (blockRegex.test(content)) {
+        content = content.replace(blockRegex, `${block}\n`);
+    } else if (content.length) {
+        content = `${content.trimEnd()}\n\n${block}\n`;
+    } else {
+        content = `${block}\n`;
+    }
+    fs.writeFileSync(configTomlPath, content, { mode: 0o600 });
+    try { fs.chmodSync(configTomlPath, 0o600); } catch (e) { logDebug(e, 'chmod configTomlPath'); }
+    return skipped;
+}
+
 // Merge the BDB hooks into ChatGPT Codex CLI's config.toml (~/.codex/config.toml or
 // .codex/config.toml), ensuring [features] hooks = true and preserving existing
 // non-BDB settings, comments, and MCP servers.
@@ -3806,11 +3878,29 @@ function mergeCodexTomlHooks(configTomlPath, { projectLocal = false } = {}) {
         `command = ${JSON.stringify(`node "${path.join(globalHooksDir, 'memb-inject.mjs')}"`)}`,
         'timeout = 30',
         '',
+        '[[hooks.SessionStart]]',
+        '[[hooks.SessionStart.hooks]]',
+        'type = "command"',
+        `command = ${JSON.stringify(`node "${path.join(globalHooksDir, 'memb-inject.mjs')}"`)}`,
+        'timeout = 30',
+        '',
         '[[hooks.UserPromptSubmit]]',
         '[[hooks.UserPromptSubmit.hooks]]',
         'type = "command"',
         `command = ${JSON.stringify(`node "${path.join(workflowsDir, 'startcycle-dispatch.mjs')}"`)}`,
         'timeout = 30',
+        '',
+        '[[hooks.PreToolUse]]',
+        '[[hooks.PreToolUse.hooks]]',
+        'type = "command"',
+        `command = ${JSON.stringify(`node "${path.join(globalHooksDir, 'trail-relay.mjs')}" --agent codex --event PreToolUse`)}`,
+        'timeout = 2',
+        '',
+        '[[hooks.Stop]]',
+        '[[hooks.Stop.hooks]]',
+        'type = "command"',
+        `command = ${JSON.stringify(`node "${path.join(globalHooksDir, 'trail-relay.mjs')}" --agent codex --event Stop`)}`,
+        'timeout = 2',
         '# AOS:HOOKS:END'
     ].join('\n');
 
@@ -3927,6 +4017,9 @@ async function promptMcpSelection(tier) {
             .map(d => d.name);
     } catch (e) { return []; }
 
+    // memb-mcp ships via npm, not as a folder under mcps/, so readdir never lists it.
+    if (!availableMcps.includes(CORE_MCP)) availableMcps.push(CORE_MCP);
+
     if (tier === '2') {
         const basicMcps = ['computer-use-mcp', 'memb-mcp', 'windows-computer-use-mcp'];
         availableMcps = availableMcps.filter(m => basicMcps.includes(m));
@@ -4471,7 +4564,7 @@ async function universalHarnessSync(primaryMcpConfigPath, installedModules = [])
                 // OpenCode provider APIs (e.g. OpenAI-compatible, Console) enforce tool name length limits
                 // (e.g. max 64 chars) and context limits. Loading 20+ MCPs causes provider errors (e.g. 73-char tool names).
                 // OpenCode uses a slim profile: only core servers (memb_mcp, zavora_computer_use) are enabled by default.
-                const OPENCODE_DEFAULT_SLIM = new Set(['memb_mcp', 'zavora_computer_use']);
+                const OPENCODE_DEFAULT_SLIM = new Set(['memb_mcp', 'zavora_computer_use', 'deja']);
                 const existingMcp = existing && existing.mcp ? existing.mcp : {};
                 const hasExistingKeys = Object.keys(existingMcp).length > 0;
 
@@ -4595,6 +4688,14 @@ async function universalHarnessSync(primaryMcpConfigPath, installedModules = [])
             syncMcpConfig(path.join(homeDir, '.aider', 'mcp.json'));
         } else if (d.key === 'opencode') {
             syncOpencodeConfig(path.join(d.path, 'opencode.jsonc'));
+        } else if (d.key === 'codex') {
+            // Universal Sync never had a branch for Codex, so its config.toml
+            // was never updated here even though the log claimed it was.
+            try {
+                mergeCodexTomlMcpServers(path.join(d.path, 'config.toml'), masterMcpData.mcpServers || {});
+            } catch (e) {
+                log.warn(`Failed to sync MCP to ${path.join(d.path, 'config.toml')}: ${e.message}`);
+            }
         }
     }
     log.success('Universal Sync Complete!');
@@ -4708,7 +4809,38 @@ async function runQuickUpdate(installState) {
 }
 
 
+function buildAoAnnouncementBanner() {
+    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'
+    ].join('\n');
+}
+
 async function main() {
+    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' });
+        process.exitCode = result.status == null ? 1 : result.status;
+        return;
+    }
+    if (process.argv[2] === 'doctor' || process.argv[2] === 'checkup' || process.argv.includes('--doctor')) {
+        const doctorScript = path.join(srcDir, 'bin', 'aos-doctor.mjs');
+        const doctorArgs = process.argv.slice(process.argv[2] === 'doctor' || process.argv[2] === 'checkup' ? 3 : 2).filter(a => a !== '--doctor');
+        const result = spawnSync(process.execPath, [doctorScript, ...doctorArgs], { stdio: 'inherit' });
+        process.exitCode = result.status == null ? 1 : result.status;
+        return;
+    }
     const skipIntro = isAutoYes || process.argv.includes('--no-intro') || process.argv.includes('--no-animation');
     await renderKineticIntro({ rotations: 1, fps: 12.5, skip: skipIntro, pkgVersion: pkg.version });
     console.log(buildWordmarkBanner());
@@ -4726,6 +4858,7 @@ async function main() {
 
     intro(buildHeroHeader(pkg.version));
     console.log(buildTelemetryCard({ installState, detections, daemonStatus }));
+    console.log(buildAoAnnouncementBanner());
 
     if (DRY_RUN) {
         // Precise on purpose: version comparison still queries the registry, and
@@ -4768,12 +4901,14 @@ async function main() {
         const options = installState.updateAvailable
             ? [
                 { value: 'quick', label: `⚡ Quick Update (v${installState.localVersion} ➔ v${installState.currentVersion})`, hint: 'refresh skills, templates & daemons' },
+                { value: 'doctor', label: '🩺 Run System Checkup / Doctor', hint: 'verify environment, placement, daemons & AO' },
                 { value: 'project', label: '📁 Drop Local Project Harness', hint: 'copy dispatcher contract to cwd' },
                 { value: 'reconfigure', label: '🛠️ Reconfigure System', hint: 'change targets, tier or options' },
                 { value: 'uninstall', label: '🗑️ Uninstall AOS', hint: 'remove what this installer placed; your data stays' },
                 { value: 'cancel', label: '❌ Exit' }
               ]
             : [
+                { value: 'doctor', label: '🩺 Run System Checkup / Doctor', hint: 'verify environment, placement, daemons & AO' },
                 { value: 'project', label: '📁 Drop Local Project Harness', hint: 'copy dispatcher contract to cwd' },
                 { value: 'quick', label: '🔄 Verify & Refresh All Skills', hint: 're-sync and health check' },
                 { value: 'reconfigure', label: '🛠️ Reconfigure System', hint: 'switch tier or targets' },
@@ -4791,6 +4926,12 @@ async function main() {
             outro('Cancelled.');
             return;
         }
+        if (action === 'doctor') {
+            const doctorScript = path.join(srcDir, 'bin', 'aos-doctor.mjs');
+            spawnSync(process.execPath, [doctorScript], { stdio: 'inherit' });
+            outro('System Checkup complete.');
+            return;
+        }
         if (action === 'project') {
             installProjectHarness();
             outro('Project harness installation complete.');
@@ -5129,9 +5270,12 @@ module.exports = {
     mergeAntigravityHooks,
     mergeCodexTomlHooks,
     mergeCodexHooks: mergeCodexTomlHooks,
+    mergeCodexTomlMcpServers,
     installGlobalHooks,
     installProjectHarness,
+    promptMcpSelection,
     mirrorMcpServersTo,
+    ensureDejaExclude,
     // Manifest store (exported for verification tests)
     computeFileHash,
     getInstallManifestPath,

package/lib/aos-archify-contract.mjs

@@ -0,0 +1,277 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const ARCHITECTURE_SPEC_PATH = 'production_artifacts/00_architecture.json';
+export const ARCHITECTURE_HTML_PATH = 'production_artifacts/00_architecture.html';
+export const ARCHITECTURE_STATE_KEY = 'architecture';
+export const ARCHITECTURE_CHECK_COUNT = 9;
+export const RECEIPT_MAX_BYTES = 65536;
+export const LOG_MAX_CHARS = 400;
+export const ARCHIFY_REL_BIN = 'skills/global_config/archify/bin/archify.mjs';
+export const ARCHIFY_TIMEOUT_MS = 120000;
+export const ARCHIFY_MAX_BYTES = 65536;
+export const PLAN_CANVAS_BIN = 'aos-plan-canvas';
+export const PLAN_CANVAS_TIMEOUT_MS = 15000;
+export const PLAN_CANVAS_MAX_BYTES = 16384;
+export const AGENT_TRAIL_BIN = 'aos-trail';
+export const EXECUTION_PLAN_PATH = 'production_artifacts/00_execution_plan.md';
+
+const ALLOWED_PATHS = new Set([ARCHITECTURE_SPEC_PATH, ARCHITECTURE_HTML_PATH]);
+const SHA256_RE = /^[a-fA-F0-9]{64}$/;
+const LONG_HEX_RE = /[a-fA-F0-9]{64}/g;
+const HOME_RE = /\/(Users|home)\/[^\s/]+/g;
+
+export function isAllowedArchitecturePath(value) {
+  if (typeof value !== 'string') return false;
+  return ALLOWED_PATHS.has(value);
+}
+
+function boundedString(raw, maxBytes) {
+  if (typeof raw !== 'string') return { ok: false, value: '' };
+  if (Buffer.byteLength(raw, 'utf8') > maxBytes) return { ok: false, value: '' };
+  return { ok: true, value: raw };
+}
+
+function firstDiagnosticMessage(diagnostics) {
+  if (!Array.isArray(diagnostics)) return '';
+  for (const entry of diagnostics) {
+    if (entry && typeof entry.message === 'string' && entry.message) return entry.message;
+    if (entry && typeof entry.code === 'string' && entry.code) return entry.code;
+  }
+  return '';
+}
+
+export function parseDeliverReceipt(raw, options = {}) {
+  const maxBytes = Number.isInteger(options.maxBytes) ? options.maxBytes : RECEIPT_MAX_BYTES;
+  const bounded = boundedString(raw, maxBytes);
+  if (!bounded.ok) {
+    return { ok: false, error: 'receipt exceeds bounded size, refusing to parse' };
+  }
+  let obj = null;
+  try {
+    obj = JSON.parse(bounded.value);
+  } catch {
+    return { ok: false, error: 'receipt is not valid JSON' };
+  }
+  if (!obj || typeof obj !== 'object') {
+    return { ok: false, error: 'receipt is not a JSON object' };
+  }
+  if (obj.ok !== true) {
+    const detail = (typeof obj.error === 'string' && obj.error) || firstDiagnosticMessage(obj.diagnostics) || 'archify deliver failed';
+    return { ok: false, error: String(detail).slice(0, 300), stage: typeof obj.stage === 'string' ? obj.stage : 'unknown' };
+  }
+  const validation = obj.validation && typeof obj.validation === 'object' ? obj.validation : null;
+  const checksPassed = validation ? validation.checksPassed : undefined;
+  const checkCount = validation ? validation.checkCount : undefined;
+  const errors = validation ? validation.errors : undefined;
+  const artifactSha = obj.artifact && typeof obj.artifact.sha256 === 'string' ? obj.artifact.sha256 : '';
+  const specSha = obj.specification && typeof obj.specification.sha256 === 'string' ? obj.specification.sha256 : '';
+  if (checksPassed !== checkCount || checkCount !== ARCHITECTURE_CHECK_COUNT || errors !== 0) {
+    return { ok: false, error: `deliver receipt incomplete: ${checksPassed}/${checkCount} checks, errors ${errors}` };
+  }
+  if (!SHA256_RE.test(artifactSha) || !SHA256_RE.test(specSha)) {
+    return { ok: false, error: 'deliver receipt missing sha256 evidence' };
+  }
+  return {
+    ok: true,
+    checksPassed,
+    checkCount,
+    errors: 0,
+    warnings: typeof validation.warnings === 'number' ? validation.warnings : 0,
+    artifactSha256: artifactSha,
+    specificationSha256: specSha,
+  };
+}
+
+export function mergeArchitectureState(state, receipt) {
+  const base = state && typeof state === 'object' ? state : {};
+  const artifacts = base.artifacts && typeof base.artifacts === 'object' ? { ...base.artifacts } : {};
+  if (receipt && receipt.ok === true) {
+    artifacts[ARCHITECTURE_STATE_KEY] = ARCHITECTURE_HTML_PATH;
+    return { state: { ...base, artifacts }, escalate: null };
+  }
+  const detail = receipt && typeof receipt.error === 'string' && receipt.error ? receipt.error : 'archify deliver/validate failed';
+  return {
+    state: { ...base, artifacts },
+    escalate: `archify deliver/validate failed: ${String(detail).slice(0, 200)}, previous artifact preserved`,
+  };
+}
+
+export function buildUrlLine() {
+  return `url: ${ARCHITECTURE_HTML_PATH}`;
+}
+
+export function planCanvasCommands() {
+  return {
+    open: `aos-plan-canvas open ${ARCHITECTURE_HTML_PATH}`,
+    awaitCmd: `aos-plan-canvas await ${ARCHITECTURE_HTML_PATH}`,
+  };
+}
+
+export function agentTrailCommand() {
+  return 'aos-trail . --plan production_artifacts/00_execution_plan.md --no-open';
+}
+
+export function buildPlanCanvasOpenArgs(htmlPath) {
+  if (!isAllowedArchitecturePath(htmlPath)) return null;
+  if (htmlPath !== ARCHITECTURE_HTML_PATH) return null;
+  return ['open', ARCHITECTURE_HTML_PATH, '--no-open'];
+}
+
+export function buildAgentTrailArgs() {
+  return ['.', '--plan', EXECUTION_PLAN_PATH, '--no-open'];
+}
+
+export async function runArchitectureCanvas(options = {}) {
+  const cwd = options.cwd;
+  const htmlPath = options.htmlPath;
+  const exists = options.exists;
+  const run = options.run;
+  const maxBytes = Number.isInteger(options.maxBytes) ? options.maxBytes : PLAN_CANVAS_MAX_BYTES;
+  const timeoutMs = Number.isInteger(options.timeoutMs) ? options.timeoutMs : PLAN_CANVAS_TIMEOUT_MS;
+  const args = buildPlanCanvasOpenArgs(htmlPath);
+  if (!args || typeof cwd !== 'string' || cwd.length === 0) {
+    return { displayed: false, reason: 'plan-canvas rejected untrusted arguments, architecture preserved', architecturePreserved: true };
+  }
+  if (typeof exists === 'function') {
+    let present = false;
+    try {
+      present = exists(htmlPath);
+    } catch {
+      present = false;
+    }
+    if (!present) {
+      return { displayed: false, reason: 'architecture artifact missing, canvas skipped', architecturePreserved: true };
+    }
+  }
+  if (typeof run !== 'function') {
+    return { displayed: false, reason: 'plan-canvas unavailable, architecture preserved', architecturePreserved: true };
+  }
+  let res = null;
+  try {
+    res = await run(args, { cwd, timeoutMs, shell: false });
+  } catch (error) {
+    return { displayed: false, error: redactForLog(error && error.message ? error.message : 'plan-canvas open failed'), architecturePreserved: true };
+  }
+  const out = boundedOutputText(res ? res.stdout : '', maxBytes);
+  if (!out.ok) {
+    return { displayed: false, error: 'plan-canvas output exceeds bounded size', architecturePreserved: true };
+  }
+  if (!res || res.status !== 0) {
+    return { displayed: false, error: redactForLog((res && res.stderr) || 'plan-canvas open failed'), architecturePreserved: true };
+  }
+  return { displayed: true, architecturePreserved: true };
+}
+
+export function redactForLog(value) {
+  const text = String(value ?? '');
+  const homes = text.replace(HOME_RE, '~');
+  const shas = homes.replace(LONG_HEX_RE, (m) => `${m.slice(0, 12)}..`);
+  return shas.slice(0, LOG_MAX_CHARS);
+}
+
+function isWithin(root, candidate) {
+  const relativePath = path.relative(root, candidate);
+  return relativePath === '' || (relativePath !== '..' && !relativePath.startsWith(`..${path.sep}`) && !path.isAbsolute(relativePath));
+}
+
+export function resolveArchifyBin(cwd) {
+  if (typeof cwd !== 'string' || cwd.length === 0) return null;
+  try {
+    const root = fs.realpathSync(path.resolve(cwd));
+    if (!fs.statSync(root).isDirectory()) return null;
+    const binaryPath = fs.realpathSync(path.resolve(root, ARCHIFY_REL_BIN));
+    if (!isWithin(root, binaryPath) || !fs.statSync(binaryPath).isFile()) return null;
+    return binaryPath;
+  } catch {
+    return null;
+  }
+}
+
+export function buildValidateArgs(specPath) {
+  if (!isAllowedArchitecturePath(specPath)) return null;
+  if (specPath !== ARCHITECTURE_SPEC_PATH) return null;
+  return ['validate', 'architecture', specPath, '--quality', 'showcase', '--json'];
+}
+
+export function buildDeliverArgs(specPath, htmlPath) {
+  if (!isAllowedArchitecturePath(specPath) || !isAllowedArchitecturePath(htmlPath)) return null;
+  if (specPath !== ARCHITECTURE_SPEC_PATH || htmlPath !== ARCHITECTURE_HTML_PATH) return null;
+  return ['deliver', 'architecture', specPath, htmlPath, '--quality', 'showcase', '--json'];
+}
+
+function boundedOutputText(value, maxBytes) {
+  if (typeof value !== 'string') return { ok: false, text: '' };
+  let size = 0;
+  try {
+    size = Buffer.byteLength(value, 'utf8');
+  } catch {
+    size = value.length;
+  }
+  if (size > maxBytes) return { ok: false, text: '' };
+  return { ok: true, text: value };
+}
+
+function boundaryFailure(stage, detail) {
+  return {
+    ok: false,
+    stage,
+    error: redactForLog(String(detail || 'archify boundary step failed')).slice(0, LOG_MAX_CHARS),
+    preservePrevious: true,
+  };
+}
+
+export async function runArchifyBoundary(options = {}) {
+  const cwd = options.cwd;
+  const specPath = options.specPath;
+  const htmlPath = options.htmlPath;
+  const run = options.run;
+  const maxBytes = Number.isInteger(options.maxBytes) ? options.maxBytes : ARCHIFY_MAX_BYTES;
+  const timeoutMs = Number.isInteger(options.timeoutMs) ? options.timeoutMs : ARCHIFY_TIMEOUT_MS;
+  const validateArgs = buildValidateArgs(specPath);
+  const deliverArgs = buildDeliverArgs(specPath, htmlPath);
+  if (!validateArgs || !deliverArgs || typeof cwd !== 'string' || cwd.length === 0) {
+    return boundaryFailure('arguments', 'archify boundary rejected untrusted arguments');
+  }
+  if (typeof run !== 'function') {
+    return boundaryFailure('executor', 'archify boundary has no executor in this runtime');
+  }
+  let validateRes = null;
+  try {
+    validateRes = await run(validateArgs, { cwd, timeoutMs, shell: false, maxBuffer: maxBytes });
+  } catch (error) {
+    return boundaryFailure('validate', error && error.message ? error.message : 'archify validate executor failed');
+  }
+  const validateOut = boundedOutputText(validateRes ? validateRes.stdout : '', maxBytes);
+  if (!validateRes || validateRes.status !== 0 || !validateOut.ok) {
+    const detail = !validateOut.ok
+      ? 'archify validate output exceeds bounded size'
+      : (validateRes && validateRes.stderr) || 'archify validate failed';
+    return boundaryFailure('validate', detail);
+  }
+  let deliverRes = null;
+  try {
+    deliverRes = await run(deliverArgs, { cwd, timeoutMs, shell: false, maxBuffer: maxBytes });
+  } catch (error) {
+    return boundaryFailure('deliver', error && error.message ? error.message : 'archify deliver executor failed');
+  }
+  const deliverOut = boundedOutputText(deliverRes ? deliverRes.stdout : '', maxBytes);
+  if (!deliverRes || deliverRes.status !== 0 || !deliverOut.ok) {
+    const detail = !deliverOut.ok
+      ? 'archify deliver output exceeds bounded size'
+      : (deliverRes && deliverRes.stderr) || 'archify deliver failed';
+    return boundaryFailure('deliver', detail);
+  }
+  const receipt = parseDeliverReceipt(deliverOut.text, { maxBytes });
+  if (!receipt || receipt.ok !== true) {
+    return boundaryFailure('deliver', (receipt && receipt.error) || 'archify deliver receipt invalid');
+  }
+  return {
+    ok: true,
+    stage: 'deliver',
+    validate: { status: 0 },
+    deliver: { status: 0 },
+    receipt,
+    preservePrevious: false,
+  };
+}