@indigoai-us/hq-cli 5.323.0 → 5.325.0

package/dist/commands/install-global.js

@@ -0,0 +1,674 @@
+/**
+ * `hq install --global --runtime claude` / `hq uninstall --global --runtime claude`
+ * (hq-anywhere-runtime US-005).
+ *
+ * Makes HQ skills, the charter, master-hook.sh and the HQ MCP server available in
+ * every Claude Code session. Every user config write goes through the
+ * mcp-registration safe-write substrate (lock, backup, atomic replace, verify).
+ * Install state, including the pre-install bytes of each touched file, lives in
+ * ~/.hq/anywhere/claude-install.json so uninstall can restore files byte-for-byte.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { claudeConfigFormat, codexConfigFormat, isCodexInstalled, jsonFormat, unregisterCodexServer, readConfigDoc, realpathOrSelf, resolveEnv, unregisterClaudeServer, writeConfigAtomic, } from './mcp-registration.js';
+import { seedRegistryFromHqRoot } from './link.js';
+import { resolveHqRoot } from './doctor.js';
+import { anywhereRuntimeEnabled, AnywhereRuntimeDisabledError } from './anywhere-runtime-flag.js';
+import { readRegistry, registryDir, registryFile, writeRegistry } from '../lib/registry/registry.js';
+import { addAgentsMdBlock, addCodexHooks, classifyLegacySkills, codexAdapterPath, codexCharterSource, codexTargets, hasAllCodexHooks, HQ_OWNED_MARKER, LEGACY_BACKUP_NAME, LEGACY_SKILLS_NAME, removeAgentsMdBlock, removeCodexHooks, } from '../lib/install/codex-targets.js';
+import { addClaudeMdBlock, addHqHooks, charterPath, claudeTargets, hasAllHqHooks, HQ_ANYWHERE_PACK, HQ_MCP_SERVER_NAME, hqSkillsSource, lineDiff, masterHookPath, removeClaudeMdBlock, removeHqHooks, SKILL_LINK_PREFIX, } from '../lib/install/claude-targets.js';
+export { AnywhereRuntimeDisabledError as AnywhereDisabledError };
+export const isAnywhereEnabled = (_home, env = process.env) => anywhereRuntimeEnabled(env);
+function readOrNull(file) {
+    try {
+        return fs.readFileSync(file, 'utf-8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return null;
+        throw e;
+    }
+}
+function writeFileAtomic(file, data) {
+    const target = realpathOrSelf(file);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const tmp = `${target}.hq-tmp-${process.pid}`;
+    fs.writeFileSync(tmp, data);
+    fs.renameSync(tmp, target);
+}
+function canonical(v) {
+    return JSON.stringify(v, (_k, val) => val && typeof val === 'object' && !Array.isArray(val)
+        ? Object.fromEntries(Object.keys(val).sort().map((k) => [k, val[k]]))
+        : val);
+}
+/** JSON settings format whose verify step checks every HQ hook is registered. */
+function settingsInstallFormat(hqRoot) {
+    return {
+        ...jsonFormat,
+        emptyDoc: () => ({}),
+        assertEntry(doc) {
+            if (!hasAllHqHooks(doc, hqRoot))
+                throw new Error('HQ hooks not present after write');
+        },
+    };
+}
+/**
+ * Removal format: verifies no HQ hook remains, and serializes a doc that equals
+ * the pre-install document back to the ORIGINAL bytes (byte-identical uninstall).
+ */
+function settingsRemovalFormat(hqRoot, original) {
+    return restoringRemovalFormat(original, (doc) => removeHqHooks(doc, hqRoot) !== doc);
+}
+/** Shared removal format for a JSON hooks file (see settingsRemovalFormat). */
+function restoringRemovalFormat(original, stillPresent) {
+    let originalCanon = null;
+    if (original !== null && original.trim() !== '') {
+        try {
+            originalCanon = canonical(JSON.parse(original));
+        }
+        catch {
+            originalCanon = null; // original was not JSON; nothing to restore byte-for-byte.
+        }
+    }
+    return {
+        ...jsonFormat,
+        emptyDoc: () => ({}),
+        serialize(doc) {
+            if (originalCanon !== null && canonical(doc) === originalCanon)
+                return original;
+            return jsonFormat.serialize(doc);
+        },
+        assertEntry(doc) {
+            if (stillPresent(doc))
+                throw new Error('HQ hooks still present after removal');
+        },
+    };
+}
+function planSkills(hqRoot, t, previouslyManaged = []) {
+    const source = hqSkillsSource(hqRoot);
+    const plan = { link: [], replace: [], already: [], skipped: [] };
+    let names;
+    try {
+        names = fs
+            .readdirSync(source, { withFileTypes: true })
+            .filter((d) => (d.isDirectory() || d.isSymbolicLink()) && !d.name.startsWith('_') && !d.name.startsWith('.'))
+            .map((d) => d.name)
+            .sort();
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return plan;
+        throw e;
+    }
+    for (const name of names) {
+        const link = path.join(t.skillsDir, `${SKILL_LINK_PREFIX}${name}`);
+        const target = path.join(source, name);
+        let st = null;
+        try {
+            st = fs.lstatSync(link);
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        if (!st)
+            plan.link.push(name);
+        else if (st.isSymbolicLink() && path.resolve(t.skillsDir, fs.readlinkSync(link)) === target)
+            plan.already.push(name);
+        else if (st.isSymbolicLink() && previouslyManaged.includes(name)) {
+            plan.link.push(name);
+            plan.replace.push(name);
+        }
+        else
+            plan.skipped.push(name);
+    }
+    return plan;
+}
+function removeSeeded(seeded, regFile) {
+    if (seeded.length === 0 || !fs.existsSync(regFile))
+        return;
+    const registry = readRegistry(regFile);
+    let removed = 0;
+    for (const key of seeded) {
+        if (registry.entries[key]?.source === 'manifest') {
+            delete registry.entries[key];
+            removed++;
+        }
+    }
+    if (removed > 0)
+        writeRegistry(registry, regFile);
+}
+function readState(t) {
+    const text = readOrNull(t.stateFile);
+    if (text === null)
+        return null;
+    return JSON.parse(text);
+}
+function assertHqRoot(hqRoot) {
+    if (!path.isAbsolute(hqRoot))
+        throw new Error(`HQ root must be absolute: ${hqRoot}`);
+    for (const p of [charterPath(hqRoot), masterHookPath(hqRoot)]) {
+        if (!fs.existsSync(p))
+            throw new Error(`${hqRoot} is not an HQ checkout (missing ${p})`);
+    }
+}
+/** Install HQ into Claude Code user scope. Returns the files touched (or that would be). */
+export function installGlobalClaude(opts) {
+    const home = resolveEnv({ home: opts.home }).home;
+    const env = opts.env ?? process.env;
+    const log = opts.log ?? ((l) => console.log(l));
+    const hqRoot = opts.hqRoot;
+    assertHqRoot(hqRoot);
+    if (!isAnywhereEnabled(home, env))
+        throw new AnywhereRuntimeDisabledError();
+    const t = claudeTargets(home);
+    const prior = readState(t);
+    const regFile = opts.registryFile ?? registryFile(registryDir(home, env));
+    const touched = [];
+    const pointerOld = readOrNull(t.hqPointer);
+    const pointerNew = `${hqRoot}\n`;
+    const mdOld = readOrNull(t.claudeMd);
+    const mdNew = addClaudeMdBlock(mdOld, hqRoot);
+    const skills = planSkills(hqRoot, t, prior?.skills.linked ?? []);
+    const settingsOld = readOrNull(t.settingsJson);
+    const settingsDoc = readConfigDoc(t.settingsJson, jsonFormat).doc;
+    const settingsNext = addHqHooks(settingsDoc, hqRoot);
+    if (pointerOld !== pointerNew)
+        touched.push(t.hqPointer);
+    if (mdOld !== mdNew)
+        touched.push(t.claudeMd);
+    for (const s of skills.link)
+        touched.push(path.join(t.skillsDir, `${SKILL_LINK_PREFIX}${s}`));
+    if (settingsNext !== settingsDoc)
+        touched.push(t.settingsJson);
+    touched.push(regFile, t.stateFile);
+    if (opts.dryRun) {
+        log(`hq install --global --runtime claude --dry-run (HQ root ${hqRoot})`);
+        log('Would write:');
+        for (const f of touched)
+            log(`  ${f}`);
+        if (skills.skipped.length > 0) {
+            log(`Would skip ${skills.skipped.length} skill(s) whose hq-<name> already exists and is not an HQ link: ${skills.skipped.join(', ')}`);
+        }
+        log(`\n--- ${t.settingsJson}`);
+        log(lineDiff(jsonFormat.serialize(settingsDoc), jsonFormat.serialize(settingsNext)));
+        return touched;
+    }
+    writeFileAtomic(t.hqPointer, pointerNew);
+    writeFileAtomic(t.claudeMd, mdNew);
+    fs.mkdirSync(t.skillsDir, { recursive: true });
+    for (const name of skills.replace)
+        fs.unlinkSync(path.join(t.skillsDir, `${SKILL_LINK_PREFIX}${name}`));
+    for (const name of skills.link) {
+        fs.symlinkSync(path.join(hqSkillsSource(hqRoot), name), path.join(t.skillsDir, `${SKILL_LINK_PREFIX}${name}`));
+    }
+    writeConfigAtomic({
+        target: t.settingsJson,
+        pack: HQ_ANYWHERE_PACK,
+        format: settingsInstallFormat(hqRoot),
+        merge: (doc) => addHqHooks(doc, hqRoot),
+        assertName: 'hooks',
+        env: { home },
+    });
+    // Seeding is best-effort: the runtime wiring above is already in place, so a
+    // missing or unreadable manifest is reported rather than aborting the install.
+    let seeded = [];
+    try {
+        seeded = seedRegistryFromHqRoot(hqRoot, { file: regFile }).owned;
+    }
+    catch (e) {
+        log(`Registry not seeded from companies/manifest.yaml: ${e.message}`);
+    }
+    const state = {
+        version: 1,
+        hqRoot,
+        // A re-install keeps the FIRST install's originals so uninstall restores pre-HQ bytes.
+        hqPointer: { original: prior ? prior.hqPointer.original : pointerOld },
+        claudeMd: { original: prior ? prior.claudeMd.original : mdOld, installed: readOrNull(t.claudeMd) ?? '' },
+        settings: { original: prior ? prior.settings.original : settingsOld, installed: readOrNull(t.settingsJson) ?? '' },
+        skills: {
+            linked: [...new Set([...(prior?.skills.linked ?? []), ...skills.link, ...skills.already])].sort(),
+            skipped: skills.skipped,
+        },
+        mcp: { name: HQ_MCP_SERVER_NAME, pack: HQ_ANYWHERE_PACK },
+        seeded: [...new Set([...(prior?.seeded ?? []), ...seeded])].sort(),
+    };
+    writeFileAtomic(t.stateFile, `${JSON.stringify(state, null, 2)}\n`);
+    log(`HQ installed for Claude Code from ${hqRoot}.`);
+    log(`  skills linked: ${skills.link.length} new, ${skills.already.length} already present, ${skills.skipped.length} skipped`);
+    log(`  hooks: master-hook.sh registered in ${t.settingsJson}`);
+    log('  MCP server registration is added by the stacked MCP shim change.');
+    log(`  registry: ${seeded.length} manifest entr${seeded.length === 1 ? 'y' : 'ies'} seeded`);
+    return touched;
+}
+/** Reverse every install step; non-HQ entries are left untouched. */
+export function uninstallGlobalClaude(opts = {}) {
+    const home = resolveEnv({ home: opts.home }).home;
+    const env = opts.env ?? process.env;
+    const log = opts.log ?? ((l) => console.log(l));
+    const t = claudeTargets(home);
+    const state = readState(t);
+    const hqRoot = state?.hqRoot ?? opts.hqRoot ?? readOrNull(t.hqPointer)?.trim();
+    if (!hqRoot)
+        throw new Error('No HQ global install found (no install state and no ~/.hq/root).');
+    const regFile = opts.registryFile ?? registryFile(registryDir(home, env));
+    const touched = [];
+    // MCP server (provenance-scoped: a foreign "hq" server is never removed).
+    const claudeDoc = readConfigDoc(t.claudeJson, claudeConfigFormat).doc;
+    const servers = claudeDoc.mcpServers;
+    if (servers?.[HQ_MCP_SERVER_NAME]?._hqPack === HQ_ANYWHERE_PACK)
+        touched.push(t.claudeJson);
+    // settings.json hooks.
+    const settingsOriginal = state ? state.settings.original : null;
+    const settingsDoc = readConfigDoc(t.settingsJson, jsonFormat).doc;
+    const settingsNext = removeHqHooks(settingsDoc, hqRoot);
+    if (settingsNext !== settingsDoc)
+        touched.push(t.settingsJson);
+    // Skills: only symlinks that point into this HQ checkout's skills dir.
+    const source = hqSkillsSource(hqRoot);
+    const links = [];
+    try {
+        for (const d of fs.readdirSync(t.skillsDir, { withFileTypes: true })) {
+            if (!d.name.startsWith(SKILL_LINK_PREFIX) || !d.isSymbolicLink())
+                continue;
+            const link = path.join(t.skillsDir, d.name);
+            const target = path.resolve(t.skillsDir, fs.readlinkSync(link));
+            if (path.dirname(target) === source)
+                links.push(link);
+        }
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    touched.push(...links);
+    const md = readOrNull(t.claudeMd);
+    let mdNext = md;
+    if (md !== null) {
+        if (state && md === state.claudeMd.installed)
+            mdNext = state.claudeMd.original;
+        else
+            mdNext = removeClaudeMdBlock(md);
+        if (mdNext !== md)
+            touched.push(t.claudeMd);
+    }
+    const pointer = readOrNull(t.hqPointer);
+    const codexStillInstalled = fs.existsSync(codexTargets(home).stateFile);
+    const pointerOwned = !codexStillInstalled && pointer !== null && pointer.trim() === hqRoot;
+    if (pointerOwned)
+        touched.push(t.hqPointer);
+    if (state)
+        touched.push(t.stateFile);
+    if (opts.dryRun) {
+        log('hq uninstall --global --runtime claude --dry-run');
+        log('Would change:');
+        for (const f of touched)
+            log(`  ${f}`);
+        log(`\n--- ${t.settingsJson}`);
+        log(lineDiff(jsonFormat.serialize(settingsDoc), jsonFormat.serialize(settingsNext)));
+        return touched;
+    }
+    unregisterClaudeServer({ name: HQ_MCP_SERVER_NAME, pack: HQ_ANYWHERE_PACK, env: { home } });
+    if (fs.existsSync(t.settingsJson)) {
+        writeConfigAtomic({
+            target: t.settingsJson,
+            pack: HQ_ANYWHERE_PACK,
+            format: settingsRemovalFormat(hqRoot, settingsOriginal),
+            merge: (doc) => removeHqHooks(doc, hqRoot),
+            assertName: 'hooks',
+            env: { home },
+        });
+        // The file did not exist before install and nothing else was added: remove it.
+        if (state && settingsOriginal === null && canonical(readConfigDoc(t.settingsJson, jsonFormat).doc) === '{}') {
+            fs.unlinkSync(t.settingsJson);
+        }
+    }
+    for (const link of links)
+        fs.unlinkSync(link);
+    if (md !== null && mdNext !== md) {
+        if (mdNext === null || (mdNext === '' && state?.claudeMd.original == null))
+            fs.unlinkSync(t.claudeMd);
+        else
+            writeFileAtomic(t.claudeMd, mdNext);
+    }
+    if (pointerOwned) {
+        const original = state?.hqPointer.original ?? null;
+        if (original === null)
+            fs.unlinkSync(t.hqPointer);
+        else
+            writeFileAtomic(t.hqPointer, original);
+    }
+    if (state && !codexStillInstalled)
+        removeSeeded(state.seeded, regFile);
+    if (state) {
+        fs.unlinkSync(t.stateFile);
+        try {
+            fs.rmdirSync(path.dirname(t.stateFile));
+        }
+        catch (e) {
+            if (e.code !== 'ENOTEMPTY' && e.code !== 'ENOENT')
+                throw e;
+        }
+    }
+    log(`HQ removed from Claude Code user scope (${links.length} skill link(s), hooks, MCP server, CLAUDE.md block).`);
+    return touched;
+}
+function readCodexState(t) {
+    const text = readOrNull(t.stateFile);
+    if (text === null)
+        return null;
+    return JSON.parse(text);
+}
+function assertCodexHqRoot(hqRoot) {
+    if (!path.isAbsolute(hqRoot))
+        throw new Error(`HQ root must be absolute: ${hqRoot}`);
+    for (const p of [codexCharterSource(hqRoot), codexAdapterPath(hqRoot)]) {
+        if (!fs.existsSync(p))
+            throw new Error(`${hqRoot} is not an HQ checkout (missing ${p})`);
+    }
+}
+function hooksInstallFormat(hqRoot) {
+    return {
+        ...jsonFormat,
+        emptyDoc: () => ({}),
+        assertEntry(doc) {
+            if (!hasAllCodexHooks(doc, hqRoot))
+                throw new Error('HQ Codex hooks not present after write');
+        },
+    };
+}
+function legacyWarning(skillsDir) {
+    return (`Left ${path.join(skillsDir, LEGACY_SKILLS_NAME)} in place: it is not an HQ-owned symlink and has no ` +
+        `${HQ_OWNED_MARKER} marker. Remove it yourself if it is an old HQ skills copy.`);
+}
+/** Install HQ into Codex user scope. Returns the files touched (or that would be). */
+export function installGlobalCodex(opts) {
+    const home = resolveEnv({ home: opts.home }).home;
+    const env = opts.env ?? process.env;
+    const log = opts.log ?? ((l) => console.log(l));
+    const hqRoot = opts.hqRoot;
+    assertCodexHqRoot(hqRoot);
+    if (!isCodexInstalled({ home })) {
+        throw Object.assign(new Error(`Codex is not installed (${path.join(home, '.codex')} is missing).`), {
+            expected: true,
+        });
+    }
+    if (!isAnywhereEnabled(home, env))
+        throw new AnywhereRuntimeDisabledError();
+    const t = codexTargets(home);
+    const hqPointer = claudeTargets(home).hqPointer;
+    const prior = readCodexState(t);
+    const regFile = opts.registryFile ?? registryFile(registryDir(home, env));
+    const touched = [];
+    const pointerOld = readOrNull(hqPointer);
+    const pointerNew = `${hqRoot}\n`;
+    const charter = fs.readFileSync(codexCharterSource(hqRoot), 'utf-8');
+    const mdOld = readOrNull(t.agentsMd);
+    const mdNew = addAgentsMdBlock(mdOld, charter);
+    const legacy = classifyLegacySkills(t.skillsDir, hqRoot);
+    const skills = planSkills(hqRoot, t, prior?.skills.linked ?? []);
+    const hooksOld = readOrNull(t.hooksJson);
+    const tomlOld = readOrNull(t.configToml);
+    const hooksDoc = readConfigDoc(t.hooksJson, jsonFormat).doc;
+    const hooksNext = addCodexHooks(hooksDoc, hqRoot);
+    if (pointerOld !== pointerNew)
+        touched.push(hqPointer);
+    if (mdOld !== mdNew)
+        touched.push(t.agentsMd);
+    if (legacy.kind === 'hq-symlink' || legacy.kind === 'hq-dir')
+        touched.push(path.join(t.skillsDir, LEGACY_SKILLS_NAME));
+    for (const s of skills.link)
+        touched.push(path.join(t.skillsDir, `${SKILL_LINK_PREFIX}${s}`));
+    if (hooksNext !== hooksDoc)
+        touched.push(t.hooksJson);
+    touched.push(regFile, t.stateFile);
+    if (opts.dryRun) {
+        log(`hq install --global --runtime codex --dry-run (HQ root ${hqRoot})`);
+        log('Would write:');
+        for (const f of touched)
+            log(`  ${f}`);
+        if (legacy.kind === 'hq-symlink' || legacy.kind === 'hq-dir') {
+            log(`Would replace the HQ-owned legacy mirror ${path.join(t.skillsDir, LEGACY_SKILLS_NAME)} with hq-<skill> links`);
+        }
+        else if (legacy.kind === 'foreign')
+            log(legacyWarning(t.skillsDir));
+        if (skills.skipped.length > 0) {
+            log(`Would skip ${skills.skipped.length} skill(s) whose hq-<name> already exists and is not an HQ link: ${skills.skipped.join(', ')}`);
+        }
+        log(`\n--- ${t.hooksJson}`);
+        log(lineDiff(jsonFormat.serialize(hooksDoc), jsonFormat.serialize(hooksNext)));
+        return touched;
+    }
+    if (legacy.kind === 'hq-dir' && fs.existsSync(path.join(t.skillsDir, LEGACY_BACKUP_NAME))) {
+        throw new Error(`${path.join(t.skillsDir, LEGACY_BACKUP_NAME)} already exists; move it away before installing.`);
+    }
+    writeFileAtomic(hqPointer, pointerNew);
+    writeFileAtomic(t.agentsMd, mdNew);
+    // Legacy mirror: replace only when HQ-owned; record enough to put it back.
+    let legacyRecord = prior?.legacy ?? { kind: 'none' };
+    const legacyPath = path.join(t.skillsDir, LEGACY_SKILLS_NAME);
+    if (legacy.kind === 'hq-symlink') {
+        fs.unlinkSync(legacyPath);
+        legacyRecord = { kind: 'symlink', target: legacy.target };
+    }
+    else if (legacy.kind === 'hq-dir') {
+        const backup = path.join(t.skillsDir, LEGACY_BACKUP_NAME);
+        fs.renameSync(legacyPath, backup);
+        legacyRecord = { kind: 'dir', backup };
+    }
+    else if (legacy.kind === 'foreign')
+        log(legacyWarning(t.skillsDir));
+    fs.mkdirSync(t.skillsDir, { recursive: true });
+    for (const name of skills.replace)
+        fs.unlinkSync(path.join(t.skillsDir, `${SKILL_LINK_PREFIX}${name}`));
+    for (const name of skills.link) {
+        fs.symlinkSync(path.join(hqSkillsSource(hqRoot), name), path.join(t.skillsDir, `${SKILL_LINK_PREFIX}${name}`));
+    }
+    writeConfigAtomic({
+        target: t.hooksJson,
+        pack: HQ_ANYWHERE_PACK,
+        format: hooksInstallFormat(hqRoot),
+        merge: (doc) => addCodexHooks(doc, hqRoot),
+        assertName: 'hooks',
+        env: { home },
+    });
+    let seeded = [];
+    try {
+        seeded = seedRegistryFromHqRoot(hqRoot, { file: regFile }).owned;
+    }
+    catch (e) {
+        log(`Registry not seeded from companies/manifest.yaml: ${e.message}`);
+    }
+    const state = {
+        version: 1,
+        hqRoot,
+        hqPointer: { original: prior ? prior.hqPointer.original : pointerOld },
+        agentsMd: { original: prior ? prior.agentsMd.original : mdOld, installed: readOrNull(t.agentsMd) ?? '' },
+        hooks: { original: prior ? prior.hooks.original : hooksOld, installed: readOrNull(t.hooksJson) ?? '' },
+        configToml: { original: prior ? prior.configToml.original : tomlOld },
+        skills: {
+            linked: [...new Set([...(prior?.skills.linked ?? []), ...skills.link, ...skills.already])].sort(),
+            skipped: skills.skipped,
+        },
+        legacy: legacyRecord,
+        mcp: { name: HQ_MCP_SERVER_NAME, pack: HQ_ANYWHERE_PACK },
+        seeded: [...new Set([...(prior?.seeded ?? []), ...seeded])].sort(),
+    };
+    writeFileAtomic(t.stateFile, `${JSON.stringify(state, null, 2)}\n`);
+    log(`HQ installed for Codex from ${hqRoot}.`);
+    log(`  skills linked: ${skills.link.length} new, ${skills.already.length} already present, ${skills.skipped.length} skipped`);
+    log(`  hooks: ${codexAdapterPath(hqRoot)} registered in ${t.hooksJson}`);
+    log('  MCP server registration is added by the stacked MCP shim change.');
+    return touched;
+}
+/** Reverse every Codex install step; non-HQ entries are left untouched. */
+export function uninstallGlobalCodex(opts = {}) {
+    const home = resolveEnv({ home: opts.home }).home;
+    const env = opts.env ?? process.env;
+    const log = opts.log ?? ((l) => console.log(l));
+    const t = codexTargets(home);
+    const hqPointer = claudeTargets(home).hqPointer;
+    const state = readCodexState(t);
+    const hqRoot = state?.hqRoot ?? opts.hqRoot ?? readOrNull(hqPointer)?.trim();
+    if (!hqRoot)
+        throw new Error('No HQ global install found (no install state and no ~/.hq/root).');
+    const regFile = opts.registryFile ?? registryFile(registryDir(home, env));
+    const claudeStillInstalled = fs.existsSync(claudeTargets(home).stateFile);
+    const touched = [];
+    const tomlDoc = readConfigDoc(t.configToml, codexConfigFormat).doc;
+    const servers = tomlDoc.value.mcp_servers;
+    if (servers?.[HQ_MCP_SERVER_NAME]?._hqPack === HQ_ANYWHERE_PACK)
+        touched.push(t.configToml);
+    const hooksOriginal = state ? state.hooks.original : null;
+    const hooksDoc = readConfigDoc(t.hooksJson, jsonFormat).doc;
+    const hooksNext = removeCodexHooks(hooksDoc, hqRoot);
+    if (hooksNext !== hooksDoc)
+        touched.push(t.hooksJson);
+    const source = hqSkillsSource(hqRoot);
+    const links = [];
+    try {
+        for (const d of fs.readdirSync(t.skillsDir, { withFileTypes: true })) {
+            if (!d.name.startsWith(SKILL_LINK_PREFIX) || !d.isSymbolicLink())
+                continue;
+            const link = path.join(t.skillsDir, d.name);
+            const target = path.resolve(t.skillsDir, fs.readlinkSync(link));
+            if (path.dirname(target) === source)
+                links.push(link);
+        }
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    touched.push(...links);
+    const legacyPath = path.join(t.skillsDir, LEGACY_SKILLS_NAME);
+    const restoreLegacy = state !== null && state.legacy.kind !== 'none' && !fs.existsSync(legacyPath);
+    if (restoreLegacy)
+        touched.push(legacyPath);
+    const md = readOrNull(t.agentsMd);
+    let mdNext = md;
+    if (md !== null) {
+        if (state && md === state.agentsMd.installed)
+            mdNext = state.agentsMd.original;
+        else
+            mdNext = removeAgentsMdBlock(md);
+        if (mdNext !== md)
+            touched.push(t.agentsMd);
+    }
+    const pointer = readOrNull(hqPointer);
+    const pointerOwned = !claudeStillInstalled && pointer !== null && pointer.trim() === hqRoot;
+    if (pointerOwned)
+        touched.push(hqPointer);
+    if (state)
+        touched.push(t.stateFile);
+    if (opts.dryRun) {
+        log('hq uninstall --global --runtime codex --dry-run');
+        log('Would change:');
+        for (const f of touched)
+            log(`  ${f}`);
+        log(`\n--- ${t.hooksJson}`);
+        log(lineDiff(jsonFormat.serialize(hooksDoc), jsonFormat.serialize(hooksNext)));
+        return touched;
+    }
+    unregisterCodexServer({ name: HQ_MCP_SERVER_NAME, pack: HQ_ANYWHERE_PACK, env: { home } });
+    // Removal re-serializes the TOML (dropping comments). When what is left equals
+    // the pre-install document, put the original bytes back.
+    const tomlOriginal = state?.configToml.original ?? null;
+    if (tomlOriginal !== null && fs.existsSync(t.configToml)) {
+        const now = readConfigDoc(t.configToml, codexConfigFormat).doc.value;
+        if (canonical(now) === canonical(codexConfigFormat.parse(tomlOriginal).value)) {
+            writeFileAtomic(realpathOrSelf(t.configToml), tomlOriginal);
+        }
+    }
+    if (fs.existsSync(t.hooksJson)) {
+        writeConfigAtomic({
+            target: t.hooksJson,
+            pack: HQ_ANYWHERE_PACK,
+            format: restoringRemovalFormat(hooksOriginal, (doc) => removeCodexHooks(doc, hqRoot) !== doc),
+            merge: (doc) => removeCodexHooks(doc, hqRoot),
+            assertName: 'hooks',
+            env: { home },
+        });
+        if (state && hooksOriginal === null && canonical(readConfigDoc(t.hooksJson, jsonFormat).doc) === '{}') {
+            fs.unlinkSync(t.hooksJson);
+        }
+    }
+    for (const link of links)
+        fs.unlinkSync(link);
+    if (restoreLegacy && state) {
+        if (state.legacy.kind === 'symlink')
+            fs.symlinkSync(state.legacy.target, legacyPath);
+        else if (state.legacy.kind === 'dir' && fs.existsSync(state.legacy.backup))
+            fs.renameSync(state.legacy.backup, legacyPath);
+    }
+    if (md !== null && mdNext !== md) {
+        if (mdNext === null || (mdNext === '' && state?.agentsMd.original == null))
+            fs.unlinkSync(t.agentsMd);
+        else
+            writeFileAtomic(t.agentsMd, mdNext);
+    }
+    if (pointerOwned) {
+        const original = state?.hqPointer.original ?? null;
+        if (original === null)
+            fs.unlinkSync(hqPointer);
+        else
+            writeFileAtomic(hqPointer, original);
+    }
+    if (state && !claudeStillInstalled)
+        removeSeeded(state.seeded, regFile);
+    if (state) {
+        fs.unlinkSync(t.stateFile);
+        try {
+            fs.rmdirSync(path.dirname(t.stateFile));
+        }
+        catch (e) {
+            if (e.code !== 'ENOTEMPTY' && e.code !== 'ENOENT')
+                throw e;
+        }
+    }
+    log(`HQ removed from Codex user scope (${links.length} skill link(s), hooks, MCP server, AGENTS.md block).`);
+    return touched;
+}
+function assertRuntime(runtime) {
+    const r = runtime ?? 'claude';
+    if (r !== 'claude' && r !== 'codex') {
+        throw Object.assign(new Error(`--runtime ${r} is not supported. Use --runtime claude or --runtime codex.`), {
+            expected: true,
+        });
+    }
+    return r;
+}
+function resolveInstallRoot(explicit) {
+    const fromFlag = explicit?.trim() || process.env.HQ_ROOT?.trim();
+    const root = fromFlag ? path.resolve(fromFlag) : resolveHqRoot();
+    if (!root) {
+        throw Object.assign(new Error('Run from inside your HQ checkout, or pass --hq-root <dir>.'), { expected: true });
+    }
+    return root;
+}
+/** Entry used by `hq install --global` (wired from pkg-install.ts). */
+export function runInstallGlobal(opts) {
+    const runtime = assertRuntime(opts.runtime);
+    const install = runtime === 'codex' ? installGlobalCodex : installGlobalClaude;
+    install({ hqRoot: resolveInstallRoot(opts.hqRoot), dryRun: opts.dryRun });
+}
+export function registerUninstallCommand(program) {
+    program
+        .command('uninstall')
+        .description('Remove the HQ global install from an agent runtime (use with --global)')
+        .option('--global', 'Reverse `hq install --global`')
+        .option('--runtime <runtime>', 'Runtime to uninstall from (claude | codex)', 'claude')
+        .option('--dry-run', 'Print what would change without writing')
+        .option('--hq-root <dir>', 'HQ checkout (only needed when install state is missing)')
+        .action((opts) => {
+        if (!opts.global) {
+            console.error('hq uninstall currently supports only --global. For packs use `hq packs uninstall <name>`.');
+            process.exitCode = 1;
+            return;
+        }
+        const runtime = assertRuntime(opts.runtime);
+        const uninstall = runtime === 'codex' ? uninstallGlobalCodex : uninstallGlobalClaude;
+        uninstall({ hqRoot: opts.hqRoot, dryRun: opts.dryRun });
+    });
+}
+//# sourceMappingURL=install-global.js.map