@hybridlabor-api/aos 4.17.0 → 4.18.1

package/lib/codenotch.js

@@ -0,0 +1,389 @@
+'use strict';
+// macOS-only opt-in install of BDB AO Codenotch from the public releases repo.
+// Every side effect (network, hdiutil, xattr, plutil, copy, prompts, roots) is injectable.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+
+// The list endpoint, not /releases/latest: the newest release may lack this platform's assets.
+const RELEASES_URL = 'https://api.github.com/repos/hybridlabor-api/bdb-ao-codenotch/releases?per_page=30';
+const stateFilePath = (home = os.homedir()) => path.join(home, '.agents', '.bdb-codenotch.json');
+
+// 'off' wins over 'force'; otherwise macOS installs default on.
+function codenotchMode(argv = process.argv, env = process.env) {
+    if (argv.includes('--no-codenotch') || env.AOS_CODENOTCH === '0') return 'off';
+    if (argv.includes('--codenotch') || env.AOS_CODENOTCH === '1') return 'force';
+    return 'default';
+}
+
+function compareVersions(a, b) {
+    const parts = (v) => String(v).replace(/^v/i, '').split(/[^0-9]+/).filter(Boolean).map(Number);
+    const x = parts(a), y = parts(b);
+    for (let i = 0; i < Math.max(x.length, y.length); i++) {
+        const d = (x[i] || 0) - (y[i] || 0);
+        if (d) return d < 0 ? -1 : 1;
+    }
+    return 0;
+}
+
+const run = (cmd) => (args) => execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+const defaultDeps = () => ({
+    fetch: (...a) => fetch(...a),
+    hdiutil: run('hdiutil'),
+    xattr: run('xattr'),
+    plutil: run('plutil'),
+    copyApp: (src, dest) => execFileSync('ditto', [src, dest]),
+    reg: run('reg'),
+    runInstaller: (exe, args, timeoutMs) => runWinProgram(require('child_process').spawnSync, exe, args, timeoutMs),
+});
+
+function readPlist(plutil, appPath) {
+    const plist = path.join(appPath, 'Contents', 'Info.plist');
+    if (!fs.existsSync(plist)) return null;
+    const get = (key) => {
+        try { return String(plutil(['-extract', key, 'raw', '-o', '-', plist])).trim() || null; } catch { return null; }
+    };
+    const version = get('CFBundleShortVersionString');
+    return version ? { version, bundleId: get('CFBundleIdentifier') } : null;
+}
+
+const readState = (file) => {
+    try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+};
+
+const isWritableDir = (dir) => {
+    try { if (!fs.statSync(dir).isDirectory()) return false; fs.accessSync(dir, fs.constants.W_OK); return true; } catch { return false; }
+};
+
+async function fetchLatestRelease(fetchFn, platform) {
+    let res;
+    try {
+        res = await fetchFn(RELEASES_URL, { headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'aos-installer' } });
+    } catch (e) {
+        return { error: `could not reach GitHub (${e.message}); try again later` };
+    }
+    if (res.status === 404) return { error: 'no public Codenotch release found yet (hybridlabor-api/bdb-ao-codenotch); try again later' };
+    const remaining = res.headers && res.headers.get && res.headers.get('x-ratelimit-remaining');
+    if (res.status === 429 || (res.status === 403 && remaining === '0')) return { error: 'GitHub API rate limit reached for unauthenticated requests; try again in about an hour' };
+    if (!res.ok) return { error: `GitHub releases API answered HTTP ${res.status}` };
+    const data = await res.json();
+    const release = selectRelease(Array.isArray(data) ? data : [data], platform);
+    return release ? { release } : { error: `no public Codenotch release found yet with a ${platform === 'win32' ? 'Windows Setup .exe' : '.dmg'} and a .sha256 asset; try again later` };
+}
+
+function pickMacAssets(assets) {
+    const dmg = assets.find((a) => /\.dmg$/i.test(a.name));
+    const sha = dmg && (assets.find((a) => a.name === `${dmg.name}.sha256`) || assets.find((a) => /\.sha256$/i.test(a.name)));
+    return dmg && sha ? { dmg, sha } : null;
+}
+
+// First (newest) non-draft, non-prerelease release that carries this platform's asset and a checksum.
+function selectRelease(releases, platform) {
+    return releases.find((r) => {
+        if (!r || r.draft || r.prerelease) return false;
+        const tag = String(r.tag_name || '').replace(/^v/i, '');
+        return tag && !(platform === 'win32' ? pickWinAssets(r.assets || [], tag).error : !pickMacAssets(r.assets || []));
+    }) || null;
+}
+
+async function download(fetchFn, url) {
+    const res = await fetchFn(url, { headers: { 'User-Agent': 'aos-installer' }, redirect: 'follow' });
+    if (!res.ok) throw new Error(`download failed: HTTP ${res.status}`);
+    return Buffer.from(await res.arrayBuffer());
+}
+
+function findInstalled(state, roots, plutil) {
+    const candidates = [state && state.path, ...[roots.applications, roots.userApplications].map((r) => path.join(r, 'Codenotch.app'))].filter(Boolean);
+    for (const appPath of candidates) {
+        if (!fs.existsSync(appPath)) continue;
+        const info = readPlist(plutil, appPath);
+        const ours = !!(state && state.path === appPath && info && info.bundleId === state.bundleId && info.version === state.version);
+        return { appPath, info, ours };
+    }
+    return null;
+}
+
+const UNINSTALL_ROOT = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall';
+// UNVERIFIED: key name, DisplayVersion and UninstallString come from Tauri's stock NSIS template, not a real
+// build; check on Windows with the first CI-built installer. The DisplayName scan is the fallback.
+const NSIS_KEY = 'Codenotch';
+const INSTALLER_TIMEOUT_MS = 5 * 60 * 1000;
+
+function regValues(out) {
+    const vals = {};
+    for (const line of String(out).split(/\r?\n/)) {
+        const m = line.match(/^\s+(\S+)\s+REG_\w+\s+(.*?)\s*$/);
+        if (m) vals[m[1]] = m[2];
+    }
+    return vals;
+}
+
+function uninstallExeFrom(vals) {
+    const cmd = vals.QuietUninstallString || vals.UninstallString || '';
+    const m = cmd.match(/^\s*"([^"]+)"/) || cmd.match(/^\s*(.+?\.exe)/i);
+    if (m) return m[1];
+    return vals.InstallLocation ? path.win32.join(vals.InstallLocation, 'uninstall.exe') : null;
+}
+
+// Returns { version, uninstallPath } or null (not installed, key missing, or reg failing).
+function readWinInstall(reg) {
+    const read = (key) => { try { return regValues(reg(['query', key])); } catch { return null; } };
+    let vals = read(`${UNINSTALL_ROOT}\\${NSIS_KEY}`);
+    if (!vals || !vals.DisplayVersion) {
+        vals = null;
+        let listing = '';
+        try { listing = reg(['query', UNINSTALL_ROOT]); } catch { return null; }
+        for (const sub of String(listing).split(/\r?\n/).map((l) => l.trim()).filter((l) => /^HKEY_/i.test(l))) {
+            const v = read(sub);
+            if (v && /^codenotch$/i.test(v.DisplayName || '') && v.DisplayVersion) { vals = v; break; }
+        }
+    }
+    return vals ? { version: vals.DisplayVersion, uninstallPath: uninstallExeFrom(vals) } : null;
+}
+
+function runWinProgram(spawnSyncFn, exe, args, timeoutMs) {
+    const r = spawnSyncFn(exe, args, { timeout: timeoutMs, windowsHide: true, stdio: 'ignore' });
+    if (r.error) throw new Error(r.error.code === 'ETIMEDOUT' ? `timed out after ${Math.round(timeoutMs / 1000)}s` : r.error.message);
+    if (r.status !== 0) throw new Error(`exited with code ${r.status}`);
+}
+
+function pickWinAssets(assets, latest) {
+    const exact = assets.find((a) => a.name === `Codenotch-Setup-${latest}.exe`);
+    const exes = exact ? [exact] : assets.filter((a) => /Setup.*\.exe$/i.test(a.name));
+    if (exes.length !== 1) return { error: exes.length ? 'latest release has several Setup .exe assets; cannot pick one' : 'latest release has no Windows Setup .exe asset' };
+    const sha = assets.find((a) => a.name === `${exes[0].name}.sha256`);
+    return sha ? { exe: exes[0], sha } : { error: 'latest release has no matching .sha256 asset; refusing to run an unverified installer' };
+}
+
+async function installCodenotchWin(o, log) {
+    const home = o.home || os.homedir();
+    const tmp = (o.roots && o.roots.tmp) || os.tmpdir();
+    const stateFile = o.stateFile || stateFilePath(home);
+    const interactive = !!o.interactive;
+    const confirm = o.confirm || (async () => false);
+    const fail = (status, message) => { log.warn(`Codenotch: ${message}`); return { status, message }; };
+
+    const { release, error } = await fetchLatestRelease(o.fetch, 'win32');
+    if (error) return fail(/rate limit/.test(error) ? 'rate-limited' : /no public/.test(error) ? 'not-found' : 'error', error);
+    const latest = String(release.tag_name || '').replace(/^v/i, '');
+    const picked = pickWinAssets(release.assets || [], latest);
+    if (!latest || picked.error) return fail('error', picked.error || 'latest release has no tag');
+
+    const state = readState(stateFile);
+    const installed = readWinInstall(o.reg);
+    let replacing = false;
+    if (installed) {
+        if (compareVersions(installed.version, latest) >= 0) {
+            const message = `already installed (${installed.version})${installed.uninstallPath ? ` at ${installed.uninstallPath}` : ''}`;
+            log.info(`Codenotch: ${message}`);
+            return { status: 'up-to-date', message };
+        }
+        const ours = !!(state && state.platform === 'win32' && state.version === installed.version && state.uninstallPath === installed.uninstallPath);
+        if (!ours && !interactive) {
+            const message = `an existing Codenotch ${installed.version} was not installed by AOS; keeping it (latest ${latest})`;
+            log.info(`Codenotch: ${message}`);
+            return { status: 'kept-foreign', message };
+        }
+        if (interactive && !(await confirm(`Replace Codenotch ${installed.version} with ${latest}?`))) {
+            return { status: 'declined', message: 'kept the installed Codenotch' };
+        }
+        replacing = true;
+    }
+
+    const work = fs.mkdtempSync(path.join(tmp, 'aos-codenotch-'));
+    try {
+        const buf = await download(o.fetch, picked.exe.browser_download_url);
+        const expected = ((await download(o.fetch, picked.sha.browser_download_url)).toString('utf8').match(/[0-9a-f]{64}/i) || [])[0];
+        if (!expected || expected.toLowerCase() !== crypto.createHash('sha256').update(buf).digest('hex')) {
+            return fail('checksum-mismatch', `sha256 mismatch for ${picked.exe.name}; refusing to run it`);
+        }
+        const exePath = path.join(work, picked.exe.name);
+        fs.writeFileSync(exePath, buf);
+
+        try { o.runInstaller(exePath, ['/S'], o.timeoutMs || INSTALLER_TIMEOUT_MS); }
+        catch (e) { return fail('error', `silent installer failed: ${e.message}`); }
+
+        const after = readWinInstall(o.reg);
+        if (!after || compareVersions(after.version, latest) < 0) return fail('error', `installer finished but the registry shows ${after ? after.version : 'no Codenotch'}; not recorded`);
+        fs.mkdirSync(path.dirname(stateFile), { recursive: true });
+        fs.writeFileSync(stateFile, JSON.stringify({ platform: 'win32', uninstallPath: after.uninstallPath, version: after.version, installedAt: new Date().toISOString() }, null, 2));
+        const message = `${replacing ? 'updated' : 'installed'} Codenotch ${after.version}${after.uninstallPath ? ` (uninstaller: ${after.uninstallPath})` : ''}`;
+        log.success(`Codenotch: ${message}`);
+        return { status: replacing ? 'updated' : 'installed', message, path: after.uninstallPath, version: after.version };
+    } catch (e) {
+        return fail('error', e.message);
+    } finally {
+        fs.rmSync(work, { recursive: true, force: true });
+    }
+}
+
+// Returns { status, message }. Never throws, never elevates.
+async function installCodenotch(opts = {}) {
+    const o = { ...defaultDeps(), ...opts };
+    const platform = o.platform || process.platform;
+    const log = { info() {}, warn() {}, success() {}, ...(o.log || {}) };
+    if (platform === 'win32') return installCodenotchWin(o, log);
+    if (platform !== 'darwin') return { status: 'skipped-platform' };
+
+    const home = o.home || os.homedir();
+    const roots = { applications: '/Applications', userApplications: path.join(home, 'Applications'), tmp: os.tmpdir(), ...(o.roots || {}) };
+    const stateFile = o.stateFile || stateFilePath(home);
+    const interactive = !!o.interactive;
+    const confirm = o.confirm || (async () => false);
+    const fail = (status, message) => { log.warn(`Codenotch: ${message}`); return { status, message }; };
+
+    const { release, error } = await fetchLatestRelease(o.fetch, 'darwin');
+    if (error) return fail(/rate limit/.test(error) ? 'rate-limited' : /no public/.test(error) ? 'not-found' : 'error', error);
+
+    const latest = String(release.tag_name || '').replace(/^v/i, '');
+    const { dmg, sha: shaAsset } = pickMacAssets(release.assets || []);
+
+    const state = readState(stateFile);
+    const installed = findInstalled(state, roots, o.plutil);
+    let destDir = null, replacing = null;
+    if (installed) {
+        const cur = installed.info && installed.info.version;
+        if (cur && compareVersions(cur, latest) >= 0) {
+            const message = `already installed (${cur}) at ${installed.appPath}`;
+            log.info(`Codenotch: ${message}`);
+            return { status: 'up-to-date', message };
+        }
+        if (!installed.ours && !interactive) {
+            const message = `${installed.appPath} was not installed by AOS; keeping it (installed ${cur || 'unknown version'}, latest ${latest})`;
+            log.info(`Codenotch: ${message}`);
+            return { status: 'kept-foreign', message };
+        }
+        if (interactive && !(await confirm(`Replace Codenotch ${cur || '(unknown version)'} at ${installed.appPath} with ${latest}?`))) {
+            return { status: 'declined', message: 'kept the installed Codenotch' };
+        }
+        replacing = installed.appPath;
+        destDir = path.dirname(replacing);
+        if (!isWritableDir(destDir)) return fail('error', `${destDir} is not writable; update Codenotch manually`);
+    }
+
+    const work = fs.mkdtempSync(path.join(roots.tmp, 'aos-codenotch-'));
+    const mountPoint = path.join(work, 'mnt');
+    let mounted = false;
+    try {
+        const dmgBuf = await download(o.fetch, dmg.browser_download_url);
+        const expected = ((await download(o.fetch, shaAsset.browser_download_url)).toString('utf8').match(/[0-9a-f]{64}/i) || [])[0];
+        const actual = crypto.createHash('sha256').update(dmgBuf).digest('hex');
+        if (!expected || expected.toLowerCase() !== actual) return fail('checksum-mismatch', `sha256 mismatch for ${dmg.name}; refusing to mount it`);
+        const dmgPath = path.join(work, dmg.name);
+        fs.writeFileSync(dmgPath, dmgBuf);
+
+        fs.mkdirSync(mountPoint);
+        o.hdiutil(['attach', '-nobrowse', '-readonly', '-mountpoint', mountPoint, dmgPath]);
+        mounted = true;
+
+        const apps = fs.readdirSync(mountPoint, { withFileTypes: true }).filter((e) => e.isDirectory() && e.name.endsWith('.app'));
+        if (apps.length !== 1) return fail('error', `expected exactly one .app in the DMG, found ${apps.length}`);
+        const appName = apps[0].name;
+        const src = path.join(mountPoint, appName);
+
+        let dest;
+        if (replacing) dest = replacing;
+        else {
+            destDir = isWritableDir(roots.applications) ? roots.applications : roots.userApplications;
+            fs.mkdirSync(destDir, { recursive: true });
+            dest = path.join(destDir, appName);
+            if (fs.existsSync(dest)) {
+                const cur = readPlist(o.plutil, dest);
+                if (!interactive || !(cur && compareVersions(cur.version, latest) < 0) || !(await confirm(`Replace ${dest} (not installed by AOS) with Codenotch ${latest}?`))) {
+                    return { status: 'kept-foreign', message: `${dest} exists and was not installed by AOS; keeping it` };
+                }
+                replacing = dest;
+            }
+        }
+
+        const backup = replacing ? `${dest}.aos-old` : null;
+        if (backup) fs.renameSync(dest, backup);
+        try {
+            o.copyApp(src, dest);
+            o.xattr(['-dr', 'com.apple.quarantine', dest]);
+        } catch (e) {
+            fs.rmSync(dest, { recursive: true, force: true });
+            if (backup) fs.renameSync(backup, dest);
+            throw e;
+        }
+        if (backup) fs.rmSync(backup, { recursive: true, force: true });
+
+        const info = readPlist(o.plutil, dest) || { version: latest, bundleId: null };
+        fs.mkdirSync(path.dirname(stateFile), { recursive: true });
+        fs.writeFileSync(stateFile, JSON.stringify({ path: dest, version: info.version, bundleId: info.bundleId, installedAt: new Date().toISOString() }, null, 2));
+        const message = `${replacing ? 'updated' : 'installed'} Codenotch ${info.version} at ${dest} (ad-hoc signed; quarantine removed)`;
+        log.success(`Codenotch: ${message}`);
+        return { status: replacing ? 'updated' : 'installed', message, path: dest, version: info.version };
+    } catch (e) {
+        return fail('error', e.message);
+    } finally {
+        if (mounted) {
+            try { o.hdiutil(['detach', mountPoint]); } catch {
+                try { o.hdiutil(['detach', mountPoint, '-force']); } catch { /* leave to the OS */ }
+            }
+        }
+        fs.rmSync(work, { recursive: true, force: true });
+    }
+}
+
+// Pure planning for aos-uninstall: only the recorded install, only if still the recorded build.
+function planCodenotchUninstall({ stateFile = stateFilePath(), plutil = run('plutil'), reg = run('reg'), exists = fs.existsSync } = {}) {
+    const state = readState(stateFile);
+    if (!state) return null;
+    if (state.platform === 'win32') {
+        if (!state.uninstallPath) return null;
+        if (!exists(state.uninstallPath)) return { state, action: 'gone' };
+        const cur = readWinInstall(reg);
+        return { state, action: cur && cur.version === state.version && cur.uninstallPath === state.uninstallPath ? 'remove' : 'keep' };
+    }
+    if (!state.path) return null;
+    if (!fs.existsSync(state.path)) return { state, action: 'gone' };
+    const info = readPlist(plutil, state.path);
+    const same = info && info.bundleId === state.bundleId && info.version === state.version;
+    return { state, action: same ? 'remove' : 'keep' };
+}
+
+function uninstallCodenotch(plan, { stateFile = stateFilePath(), runUninstaller = (exe, args, t) => runWinProgram(require('child_process').spawnSync, exe, args, t) } = {}) {
+    if (!plan) return 'none';
+    if (plan.action === 'remove') {
+        if (plan.state.platform === 'win32') {
+            try { runUninstaller(plan.state.uninstallPath, ['/S'], INSTALLER_TIMEOUT_MS); } catch { return 'error'; }
+        } else fs.rmSync(plan.state.path, { recursive: true, force: true });
+    }
+    if (plan.action !== 'keep') fs.rmSync(stateFile, { force: true });
+    return plan.action;
+}
+
+// Never throws and never affects the caller's exit code. Returns a result or null (not run).
+async function runCodenotchStep({ platform = process.platform, argv = process.argv, env = process.env, interactive, dryRun, ask, log = {}, install = installCodenotch, ...rest } = {}) {
+    if (platform !== 'darwin' && platform !== 'win32') return null;
+    try {
+        const mode = codenotchMode(argv, env);
+        if (mode === 'off') return { status: 'opted-out' };
+        if (interactive && mode === 'default' && ask && !(await ask('Install BDB AO Codenotch? (SHA-256 verified)'))) return { status: 'declined' };
+        if (dryRun) { if (log.info) log.info('[dry-run] would install BDB AO Codenotch'); return null; }
+        return await install({ platform, interactive, confirm: ask && ((m) => ask(m, false)), log, ...rest });
+    } catch (e) {
+        if (log.warn) log.warn(`Codenotch: ${e.message}`);
+        return { status: 'error', message: e.message };
+    }
+}
+
+function codenotchSummaryLine(r) {
+    if (!r || r.status === 'skipped-platform') return null;
+    const how = (p) => `remove with aos-uninstall${p ? ` (app: ${p})` : ''}`;
+    switch (r.status) {
+        case 'installed': case 'updated': return `Codenotch: ${r.status} ${r.version || ''} (${r.path}); ${how(r.path)}`.replace('  ', ' ');
+        case 'up-to-date': case 'kept-foreign': return `Codenotch: skipped (${r.message}); ${how()}`;
+        case 'opted-out': return 'Codenotch: skipped (opted out)';
+        case 'declined': return 'Codenotch: skipped (declined)';
+        default: return `Codenotch: FAILED (${r.message || r.status}); AOS install is unaffected, rerun later or use --no-codenotch to opt out`;
+    }
+}
+
+module.exports = {
+    RELEASES_URL, selectRelease, stateFilePath, readWinInstall, runWinProgram, uninstallExeFrom, codenotchMode, runCodenotchStep, codenotchSummaryLine, compareVersions, readPlist,
+    installCodenotch, planCodenotchUninstall, uninstallCodenotch,
+};

package/lib/retired-skills.js

@@ -0,0 +1,101 @@
+'use strict';
+// Retires skills that left the package from installed copies. Pure of installer state: every path
+// derives from `home` or the passed roots. Only manifest-listed skill dirs are touched, and every
+// file that is not a hash-identical installer copy is backed up before its directory is removed.
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const RETIRED_SKILLS = {
+    bdbsaastraining: '4.4.2',
+    'bdb-dev-os-skill': '4.4.2',
+    bdbsaashost: '4.4.2',
+    'bdb-ecosystem-health': '4.4.2',
+    'bdbsaas-ops': '4.4.2',
+    'visual-edit': '4.17.0',
+    'visual-plan': '4.17.0',
+    'visual-recap': '4.17.0',
+};
+
+const hashOf = (file) => {
+    try { return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex'); } catch { return null; }
+};
+
+const defaultRoots = (home) => [
+    path.join(home, '.agents', 'skills'),
+    path.join(home, '.claude', 'skills'),
+    path.join(home, '.codex', 'skills'),
+    path.join(home, '.cursor', 'skills'),
+    path.join(home, '.roo', 'skills'),
+    path.join(home, '.gemini', 'config', 'skills'),
+];
+
+// Regular files of a dir tree; `unsafe` is true when a symlink or special entry is inside.
+function walkFiles(dir, out = { files: [], unsafe: false }) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { out.unsafe = true; return out; }
+    for (const e of entries) {
+        const abs = path.join(dir, e.name);
+        if (e.isDirectory()) walkFiles(abs, out);
+        else if (e.isFile()) out.files.push(abs);
+        else out.unsafe = true;
+    }
+    return out;
+}
+
+function backupFile(home, backupDir, abs) {
+    const rel = path.relative(home, abs);
+    const dest = path.join(backupDir, rel.startsWith('..') || path.isAbsolute(rel) ? path.basename(abs) : rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(abs, dest);
+}
+
+function pruneRetiredSkills({ home, manifest, roots = defaultRoots(home), backupDir, log = {} }) {
+    const res = { removed: [], backedUp: [] };
+    if (!manifest) return res;
+    const note = (level, msg) => { if (typeof log[level] === 'function') log[level](msg); };
+
+    const dirs = new Map();
+    for (const [file, entry] of Object.entries(manifest)) {
+        if (typeof file !== 'string' || !path.isAbsolute(file)) continue;
+        const root = roots.find((r) => file.startsWith(r + path.sep));
+        if (!root) continue;
+        const parts = file.slice(root.length + 1).split(path.sep);
+        if (parts.includes('..') || !Object.hasOwn(RETIRED_SKILLS, parts[0])) continue;
+        const dir = path.join(root, parts[0]);
+        if (!dirs.has(dir)) dirs.set(dir, new Map());
+        dirs.get(dir).set(path.resolve(file), { key: file, sha256: entry && entry.sha256 });
+    }
+
+    for (const [dir, owned] of dirs) {
+        let st;
+        try { st = fs.lstatSync(dir); } catch { for (const o of owned.values()) delete manifest[o.key]; continue; }
+        if (!st.isDirectory()) continue;
+        const { files, unsafe } = walkFiles(dir);
+        if (unsafe) { note('warn', `[retired-skills] ${dir} holds a symlink or special entry; left in place.`); continue; }
+
+        const toBackup = files.filter((f) => {
+            const o = owned.get(path.resolve(f));
+            return !o || hashOf(f) !== o.sha256;
+        });
+        try {
+            for (const f of toBackup) backupFile(home, backupDir, f);
+        } catch (e) {
+            note('warn', `[retired-skills] backup of ${dir} failed (${e.code || e.message}); left in place.`);
+            continue;
+        }
+        try { fs.rmSync(dir, { recursive: true, force: true }); } catch (e) {
+            note('warn', `[retired-skills] could not remove ${dir} (${e.code || e.message}).`);
+            continue;
+        }
+        res.backedUp.push(...toBackup);
+        res.removed.push(dir);
+        for (const o of owned.values()) delete manifest[o.key];
+    }
+
+    if (res.backedUp.length) note('warn', `[retired-skills] ${res.backedUp.length} edited or foreign file(s) from retired skills backed up to ${backupDir}.`);
+    if (res.removed.length) note('step', `Removed ${res.removed.length} retired skill install(s) no longer shipped.`);
+    return res;
+}
+
+module.exports = { RETIRED_SKILLS, pruneRetiredSkills, defaultRoots };

package/mcps/mcsc/README.md

@@ -7,7 +7,7 @@ native Claude Code subagents) are installed and authenticated on a machine, and
 routes delegated subtasks to the right one via a capability-tier YAML rulebook
 — never a pinned model ID, since free-tier model IDs churn within days.
 
-Status: Core package implemented and tested. Includes an **MCP Server** (`packages/mcp/server.js`) that allows any MCP-compatible client to securely delegate tasks to local agent CLIs. The architecture includes rigorous recursion protection (via `MCSC_CALLER` environment variables) to prevent autonomous agents from calling themselves in infinite loops.
+Status: Core package implemented and tested. Includes an **MCP Server** (`packages/mcp/server.js`) that allows any MCP-compatible client to securely delegate tasks to local agent CLIs. The architecture includes rigorous recursion protection (via `MCSC_CALLER` environment variables) to prevent autonomous agents from calling themselves in infinite loops. `MCSC_DEPTH` (raised by one in every adapter's child env) limits delegation to one level: a server that starts at depth 1 or more refuses all calls. `delegate_agy` is documented read-only; its `write` flag (`--mode accept-edits`) is untested.
 
 See [.openwiki/architecture.md](.openwiki/architecture.md) for the validated design.
 

package/mcps/mcsc/packages/core/src/adapters/agy.js

@@ -1,6 +1,7 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { emitTrail } from '../trail.js';
+import { childEnv } from '../depth.js';
 const execFileAsync = promisify(execFile);
 
 /**
@@ -22,6 +23,7 @@ export async function delegate(req) {
   try {
     const args = [];
     if (req.model) args.push('--model', req.model);
+    if (req.write === true) args.push('--mode', 'accept-edits');
     args.push(
       '--print-timeout',
       '15m',
@@ -33,7 +35,7 @@ export async function delegate(req) {
       req.prompt
     );
     
-    const env = { ...process.env, MCSC_CALLER: 'agy' };
+    const env = childEnv('agy');
 
     const run = execFileAsync(
       'agy',

package/mcps/mcsc/packages/core/src/adapters/codex.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import { emitTrail } from '../trail.js';
+import { childEnv } from '../depth.js';
 
 const MAX_OUTPUT = 1024 * 1024 * 50; // 50MB, mirrors the old execFile maxBuffer
 
@@ -39,7 +40,7 @@ export async function delegate(req) {
   };
   emitTrail({ ...trailEvent, hook_event_name: 'SessionStart' });
 
-  const env = { ...process.env, MCSC_CALLER: 'codex' };
+  const env = childEnv('codex');
   const args = ['exec', '--json', '--skip-git-repo-check'];
   if (req.model) args.push('-m', req.model);
   args.push(req.prompt);

package/mcps/mcsc/packages/core/src/adapters/opencode.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { emitTrail } from '../trail.js';
+import { childEnv } from '../depth.js';
 
 const MAX_OUTPUT = 1024 * 1024 * 50; // 50MB, mirrors the old execFile maxBuffer
 
@@ -25,7 +26,7 @@ export async function delegate(req) {
   };
   emitTrail({ ...trailEvent, hook_event_name: 'SessionStart' });
 
-  const env = { ...process.env, MCSC_CALLER: 'opencode' };
+  const env = childEnv('opencode');
   const args = ['run', '--auto', '--format', 'json'];
   if (req.model) args.push('--model', req.model);
   if (req.variant) args.push('--variant', String(req.variant));

package/mcps/mcsc/packages/core/src/depth.js

@@ -0,0 +1,16 @@
+// One level of delegation, like a fork: every adapter raises MCSC_DEPTH for its child,
+// and a server that starts with depth >= MAX_DEPTH refuses to delegate.
+export const MAX_DEPTH = 1;
+
+export const currentDepth = (env = process.env) => {
+  const n = Number.parseInt(env.MCSC_DEPTH ?? '', 10);
+  return Number.isInteger(n) && n > 0 ? n : 0;
+};
+
+export const childEnv = (caller, env = process.env) => ({
+  ...env,
+  MCSC_CALLER: caller,
+  MCSC_DEPTH: String(currentDepth(env) + 1),
+});
+
+export const depthExceeded = (env = process.env) => currentDepth(env) >= MAX_DEPTH;

package/mcps/mcsc/packages/mcp/server.js

@@ -11,6 +11,7 @@ import { getCached, setCached } from "../core/src/detect/cache.js";
 import { delegate as agyDelegate } from "../core/src/adapters/agy.js";
 import { delegate as opencodeDelegate } from "../core/src/adapters/opencode.js";
 import { delegate as codexDelegate } from "../core/src/adapters/codex.js";
+import { depthExceeded } from "../core/src/depth.js";
 import { decide } from "../core/src/rulebook/resolve.js";
 import { loadRulebook } from "../core/src/rulebook/load.js";
 import { buildOfferTable } from "../core/src/capabilities/buildOfferTable.js";
@@ -92,13 +93,14 @@ const server = new Server(
 // --- Tool Registration ---
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   const tools = [];
+  if (depthExceeded()) return { tools };
 
   // delegate_agy
   const agyHealth = inventory.get('agy');
   if (agyHealth && agyHealth.status === 'ready' && caller !== 'agy') {
     tools.push({
       name: "delegate_agy",
-      description: "Delegate a task to Antigravity CLI (Gemini 3.8 Flash or Claude 3.7 Sonnet). Provides full coding capabilities.",
+      description: "Delegate a READ-ONLY task to Antigravity CLI (Gemini 3.8 Flash or Claude 3.7 Sonnet). Write tasks are untested: do not rely on it for edits.",
       inputSchema: {
         type: "object",
         properties: {
@@ -110,6 +112,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             type: "string",
             description: "Optional model hint for the subagent (e.g., 'flash', 'pro'). Default varies by tool.",
             default: "flash"
+          },
+          write: {
+            type: "boolean",
+            description: "UNTESTED. Adds --mode accept-edits for a write task. Leave unset: delegate_agy is documented read-only."
           }
         },
         required: ["prompt"]
@@ -194,7 +200,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 
 // --- Tool Execution ---
 server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
-  const { name, arguments: args } = request.params;
+  const { name, arguments: args = {} } = request.params;
+  if (depthExceeded()) {
+    return {
+      content: [{ type: "text", text: "Delegation refused: MCSC_DEPTH limit reached (one level of delegation, like a fork). Do the task yourself." }],
+      isError: true,
+    };
+  }
   const signal = extra.signal;
 
   const req = {
@@ -202,6 +214,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     prompt: args.prompt,
     model: args.model,
     variant: args.variant,
+    write: args.write === true,
     signal
   };