@indigoai-us/hq-cli 5.327.0 → 5.329.0

package/dist/command-help.d.ts

@@ -0,0 +1,2 @@
+export declare function runCommandHelp(argv: readonly string[]): Promise<void>;
+//# sourceMappingURL=command-help.d.ts.map

package/dist/command-help.js

@@ -0,0 +1,13 @@
+import { Command } from "commander";
+import { CLI_VERSION } from "./cli-version.js";
+import { registerCommandCatalog } from "./lazy-commands.js";
+export async function runCommandHelp(argv) {
+    const program = new Command()
+        .name("hq")
+        .description("HQ management CLI — modules, packages, and cloud sync")
+        .version(CLI_VERSION)
+        .option("--verbose", "Show verbose diagnostics, including SDK runtime warnings");
+    registerCommandCatalog(program);
+    await program.parseAsync([...argv]);
+}
+//# sourceMappingURL=command-help.js.map

package/dist/commands/install-global.d.ts

@@ -17,6 +17,12 @@ export interface GlobalInstallOptions {
     log?: (line: string) => void;
     /** Is the hq daemon installed? Default: look for its launchd/systemd unit under `home`. */
     daemonInstalled?: boolean;
+    /** Install Claude Code through a local plugin marketplace instead of direct hooks/MCP. */
+    via?: 'direct' | 'plugin';
+    /** Local Claude Code marketplace directory (or HQ_CLAUDE_PLUGIN_MARKETPLACE). */
+    marketplaceDir?: string;
+    /** Test seam for the Claude Code CLI; production uses `claude`. */
+    runClaude?: (args: string[], home: string, env: NodeJS.ProcessEnv) => void;
 }
 /** True when an hq daemon unit (launchd plist or systemd unit) exists. */
 export declare function isDaemonInstalled(home: string, platform?: NodeJS.Platform, queryTask?: (task: string) => boolean): boolean;
@@ -25,6 +31,14 @@ export declare function isDaemonInstalled(home: string, platform?: NodeJS.Platfo
  * the hqd shim; otherwise to master-hook.sh / the Codex adapter.
  */
 export declare function hookTargetFor(hqRoot: string, home: string, daemonInstalled?: boolean, env?: NodeJS.ProcessEnv): HookTarget;
+export interface ClaudePluginSource {
+    sourceDir: string;
+    marketplaceName: string;
+    pluginName: string;
+    pluginId: string;
+}
+/** Resolve the local marketplace source; published hosting remains an operator decision. */
+export declare function resolveClaudePluginSource(explicitDir?: string, env?: NodeJS.ProcessEnv): ClaudePluginSource;
 export { AnywhereRuntimeDisabledError as AnywhereDisabledError };
 export declare const isAnywhereEnabled: (_home: string, env?: NodeJS.ProcessEnv) => boolean;
 /** Install HQ into Claude Code user scope. Returns the files touched (or that would be). */
@@ -37,6 +51,8 @@ export interface GlobalUninstallOptions {
     env?: NodeJS.ProcessEnv;
     registryFile?: string;
     log?: (line: string) => void;
+    /** Test seam for the Claude Code CLI; production uses `claude`. */
+    runClaude?: (args: string[], home: string, env: NodeJS.ProcessEnv) => void;
 }
 /** Reverse every install step; non-HQ entries are left untouched. */
 export declare function uninstallGlobalClaude(opts?: GlobalUninstallOptions): string[];
@@ -49,6 +65,11 @@ export interface GlobalCommandOpts {
     runtime?: string;
     dryRun?: boolean;
     hqRoot?: string;
+    via?: 'direct' | 'plugin';
+    marketplaceDir?: string;
+    /** Dependency injection for tests. */
+    env?: NodeJS.ProcessEnv;
+    log?: (line: string) => void;
 }
 /** Entry used by `hq install --global` (wired from pkg-install.ts). */
 export declare function runInstallGlobal(opts: GlobalCommandOpts): void;

package/dist/commands/install-global.js

@@ -15,6 +15,9 @@ import { buildCodexServerDef, claudeConfigFormat, codexConfigFormat, isCodexInst
 import { seedRegistryFromHqRoot } from './link.js';
 import { resolveHqRoot } from './doctor.js';
 import { anywhereRuntimeEnabled, AnywhereRuntimeDisabledError } from './anywhere-runtime-flag.js';
+import { resolveHqMcpEndpoint } from '../lib/daemon/mcp-endpoint.js';
+import { chatgptConnectorInstructions } from '../lib/install/chatgpt-targets.js';
+import { grokConnectorInstructions } from '../lib/install/grok-targets.js';
 import { readRegistry, registryDir, registryFile, writeRegistry } from '../lib/registry/registry.js';
 import { DAEMON_LAUNCHD_LABEL, DAEMON_SYSTEMD_UNIT, DAEMON_WINDOWS_TASK, SYSTEM_UNIT_DIR } from '../lib/daemon/install.js';
 import { readDaemonConfig } from '../lib/daemon/config.js';
@@ -42,6 +45,64 @@ export function hookTargetFor(hqRoot, home, daemonInstalled, env = process.env)
     const daemonMatchesRoot = configuredRoot !== undefined && realpathOrSelf(configuredRoot) === realpathOrSelf(hqRoot);
     return installed && daemonMatchesRoot && fs.existsSync(shimPath(hqRoot)) ? 'shim' : 'master';
 }
+/** Resolve the local marketplace source; published hosting remains an operator decision. */
+export function resolveClaudePluginSource(explicitDir, env = process.env) {
+    const configured = explicitDir?.trim() || env.HQ_CLAUDE_PLUGIN_MARKETPLACE?.trim();
+    if (!configured) {
+        throw Object.assign(new Error('Published HQ Claude plugin source is not configured; its repository/host awaits an operator decision. Pass --marketplace-dir <dir> or set HQ_CLAUDE_PLUGIN_MARKETPLACE.'), { expected: true });
+    }
+    const sourceDir = path.resolve(configured);
+    const manifestPath = path.join(sourceDir, '.claude-plugin', 'marketplace.json');
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        throw Object.assign(new Error(`Cannot read Claude marketplace manifest at ${manifestPath}: ${error.message}`), { expected: true });
+    }
+    if (typeof manifest.name !== 'string' || !Array.isArray(manifest.plugins)) {
+        throw Object.assign(new Error(`Invalid Claude marketplace manifest at ${manifestPath}: expected string name and plugins array.`), { expected: true });
+    }
+    const hqPlugin = manifest.plugins.find((p) => !!p && typeof p === 'object' && p.name === 'hq');
+    if (!hqPlugin) {
+        throw Object.assign(new Error(`Claude marketplace ${manifest.name} does not contain the HQ plugin named "hq".`), { expected: true });
+    }
+    return { sourceDir, marketplaceName: manifest.name, pluginName: hqPlugin.name, pluginId: `${hqPlugin.name}@${manifest.name}` };
+}
+function runClaudeCli(args, home, env) {
+    const childEnv = { ...process.env, ...env, HOME: home, CLAUDE_CONFIG_DIR: path.join(home, '.claude') };
+    const result = spawnSync('claude', ['plugin', ...args], { encoding: 'utf8', env: childEnv, timeout: 120_000, windowsHide: true });
+    if (result.error || result.status !== 0) {
+        const cause = result.error?.message ?? `exit status ${String(result.status)}`;
+        throw Object.assign(new Error(`Claude Code plugin command failed (${cause}). Ensure the Claude Code CLI is installed and try again.`), { expected: true });
+    }
+}
+function removePluginSettings(doc, plugin, removePlugin, removeMarketplace, pluginSettingBefore) {
+    const next = { ...doc };
+    const enabled = next.enabledPlugins;
+    if (removePlugin && enabled && typeof enabled === 'object' && !Array.isArray(enabled)) {
+        const entries = { ...enabled };
+        delete entries[plugin.pluginId];
+        if (pluginSettingBefore !== undefined)
+            entries[plugin.pluginId] = pluginSettingBefore;
+        if (Object.keys(entries).length === 0)
+            delete next.enabledPlugins;
+        else
+            next.enabledPlugins = entries;
+    }
+    const marketplaces = next.extraKnownMarketplaces;
+    if (marketplaces && typeof marketplaces === 'object' && !Array.isArray(marketplaces)) {
+        const entries = { ...marketplaces };
+        const registration = entries[plugin.marketplaceName];
+        if (removeMarketplace && registration?.source?.source === 'directory' && registration.source.path === plugin.sourceDir)
+            delete entries[plugin.marketplaceName];
+        if (Object.keys(entries).length === 0)
+            delete next.extraKnownMarketplaces;
+        else
+            next.extraKnownMarketplaces = entries;
+    }
+    return canonical(next) === canonical(doc) ? doc : next;
+}
 export { AnywhereRuntimeDisabledError as AnywhereDisabledError };
 export const isAnywhereEnabled = (_home, env = process.env) => anywhereRuntimeEnabled(env);
 function readOrNull(file) {
@@ -80,8 +141,9 @@ function settingsInstallFormat(hqRoot, target) {
  * 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);
+function settingsRemovalFormat(hqRoots, original) {
+    const roots = Array.isArray(hqRoots) ? hqRoots : [hqRoots];
+    return restoringRemovalFormat(original, (doc) => roots.reduce((current, root) => removeHqHooks(current, root), doc) !== doc);
 }
 /** Shared removal format for a JSON hooks file (see settingsRemovalFormat). */
 function restoringRemovalFormat(original, stillPresent) {
@@ -153,6 +215,30 @@ function planSkills(hqRoot, t) {
     }
     return plan;
 }
+function hqSkillLinksForRoot(skillsDir, hqRoot) {
+    let names;
+    try {
+        names = fs.readdirSync(skillsDir).filter((name) => name.startsWith(SKILL_LINK_PREFIX));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    return names.filter((name) => {
+        const link = path.join(skillsDir, name);
+        try {
+            if (!fs.lstatSync(link).isSymbolicLink())
+                return false;
+            return path.dirname(path.resolve(skillsDir, fs.readlinkSync(link))) === hqSkillsSource(hqRoot);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+    }).map((name) => path.join(skillsDir, name));
+}
 function removeSeeded(seeded, regFile) {
     if (seeded.length === 0 || !fs.existsSync(regFile))
         return;
@@ -192,21 +278,58 @@ export function installGlobalClaude(opts) {
         throw new AnywhereRuntimeDisabledError();
     const t = claudeTargets(home);
     const prior = readState(t);
+    const pluginSource = opts.via === 'plugin' ? resolveClaudePluginSource(opts.marketplaceDir, env) : undefined;
+    if (prior?.plugin && !pluginSource) {
+        throw Object.assign(new Error('HQ is installed through a Claude plugin marketplace. Run `hq uninstall --global --runtime claude` before switching back to direct installation.'), { expected: true });
+    }
+    if (prior?.plugin && pluginSource && (prior.plugin.pluginId !== pluginSource.pluginId || prior.plugin.sourceDir !== pluginSource.sourceDir)) {
+        throw Object.assign(new Error('A different HQ Claude plugin marketplace is already recorded for this install. Uninstall it before changing marketplace source.'), { expected: true });
+    }
+    const runClaude = opts.runClaude ?? runClaudeCli;
     const regFile = opts.registryFile ?? registryFile(registryDir(home, env));
-    const manifest = mcpManifest(opts);
+    const manifest = pluginSource ? undefined : mcpManifest(opts);
     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);
+    const legacyRoot = prior?.hqRoot ?? (pluginSource ? pointerOld?.trim() : undefined);
+    const cleanupRoots = [...new Set([hqRoot, ...(legacyRoot ? [legacyRoot] : [])])];
+    const mdOriginal = pluginSource
+        ? (prior && mdOld === prior.claudeMd.installed
+            ? prior.claudeMd.original
+            : mdOld === null ? null : (removeClaudeMdBlock(mdOld) || null))
+        : prior ? prior.claudeMd.original : mdOld;
+    const mdNew = pluginSource ? mdOriginal : addClaudeMdBlock(mdOld, hqRoot);
+    const skills = pluginSource ? { link: [], already: [], skipped: [] } : planSkills(hqRoot, t);
     const settingsOld = readOrNull(t.settingsJson);
     const settingsDoc = readConfigDoc(t.settingsJson, jsonFormat).doc;
+    const directHooksRemoved = pluginSource
+        ? cleanupRoots.reduce((doc, root) => removeHqHooks(doc, root), settingsDoc)
+        : settingsDoc;
+    const settingsOriginal = prior
+        ? prior.settings.original
+        : pluginSource && directHooksRemoved !== settingsDoc ? jsonFormat.serialize(directHooksRemoved) : settingsOld;
+    const enabledPlugins = settingsDoc.enabledPlugins;
+    const knownMarketplaces = settingsDoc.extraKnownMarketplaces;
+    const existingMarketplace = pluginSource ? knownMarketplaces?.[pluginSource.marketplaceName] : undefined;
+    if (pluginSource && existingMarketplace && (existingMarketplace.source?.source !== 'directory' || existingMarketplace.source.path !== pluginSource.sourceDir)) {
+        throw Object.assign(new Error(`Claude marketplace "${pluginSource.marketplaceName}" is already registered from a different source. Remove or rename that marketplace before installing HQ.`), { expected: true });
+    }
+    const hadPluginSetting = !!pluginSource && !!enabledPlugins && Object.prototype.hasOwnProperty.call(enabledPlugins, pluginSource.pluginId);
+    const currentPluginSetting = pluginSource && hadPluginSetting ? enabledPlugins[pluginSource.pluginId] : undefined;
+    const pluginSettingBefore = prior?.plugin ? prior.plugin.pluginSettingBefore : currentPluginSetting;
+    const pluginNeedsInstall = !!pluginSource && currentPluginSetting !== true;
+    const marketplaceNeedsAdd = !!pluginSource && existingMarketplace === undefined;
+    const pluginAdded = !!pluginSource && (prior?.plugin?.pluginAdded === true || pluginNeedsInstall);
+    const marketplaceAdded = !!pluginSource && (prior?.plugin?.marketplaceAdded === true || marketplaceNeedsAdd);
     const hookTarget = hookTargetFor(hqRoot, home, opts.daemonInstalled, env);
-    const settingsNext = addHqHooks(settingsDoc, hqRoot, hookTarget);
+    const settingsNext = pluginSource
+        ? cleanupRoots.reduce((doc, root) => removeHqHooks(doc, root), settingsDoc)
+        : addHqHooks(settingsDoc, hqRoot, hookTarget);
+    const skillLinksToRemove = pluginSource ? cleanupRoots.flatMap((root) => hqSkillLinksForRoot(t.skillsDir, root)) : [];
     const claudeDoc = readConfigDoc(t.claudeJson, claudeConfigFormat).doc;
     // Collision check runs here too, so a dry run surfaces a conflicting "hq" server.
-    const claudeNext = mergeClaudeServer(HQ_MCP_SERVER_NAME, {
+    const claudeNext = pluginSource ? claudeDoc : mergeClaudeServer(HQ_MCP_SERVER_NAME, {
         ...manifest,
         _hqPack: HQ_ANYWHERE_PACK,
     })(claudeDoc);
@@ -216,10 +339,13 @@ export function installGlobalClaude(opts) {
         touched.push(t.claudeMd);
     for (const s of skills.link)
         touched.push(path.join(t.skillsDir, `${SKILL_LINK_PREFIX}${s}`));
+    touched.push(...skillLinksToRemove);
     if (settingsNext !== settingsDoc)
         touched.push(t.settingsJson);
     if (claudeNext !== claudeDoc)
         touched.push(t.claudeJson);
+    if (pluginSource)
+        touched.push(t.settingsJson);
     touched.push(regFile, t.stateFile);
     if (opts.dryRun) {
         log(`hq install --global --runtime claude --dry-run (HQ root ${hqRoot})`);
@@ -233,23 +359,86 @@ export function installGlobalClaude(opts) {
         log(lineDiff(jsonFormat.serialize(settingsDoc), jsonFormat.serialize(settingsNext)));
         log(`\n--- ${t.claudeJson}`);
         log(lineDiff(jsonFormat.serialize(claudeDoc), jsonFormat.serialize(claudeNext)));
+        if (pluginSource)
+            log(`Would run: claude plugin marketplace add --scope user ${pluginSource.sourceDir}; claude plugin install --scope user -y ${pluginSource.pluginId}`);
         return touched;
     }
+    if (pluginSource && (marketplaceNeedsAdd || pluginNeedsInstall)) {
+        let marketplaceMayNeedRollback = false;
+        try {
+            if (marketplaceNeedsAdd) {
+                marketplaceMayNeedRollback = true;
+                runClaude(['marketplace', 'add', '--scope', 'user', '--json', pluginSource.sourceDir], home, env);
+            }
+            if (pluginNeedsInstall)
+                runClaude(['install', '--scope', 'user', '--json', '-y', pluginSource.pluginId], home, env);
+        }
+        catch (error) {
+            const rollbackErrors = [];
+            if (pluginNeedsInstall && pluginAdded) {
+                try {
+                    runClaude(['uninstall', '--scope', 'user', '--json', pluginSource.pluginId], home, env);
+                }
+                catch (rollbackError) {
+                    rollbackErrors.push(`plugin uninstall: ${rollbackError.message}`);
+                }
+            }
+            if (marketplaceMayNeedRollback) {
+                try {
+                    runClaude(['marketplace', 'remove', '--scope', 'user', '--json', pluginSource.marketplaceName], home, env);
+                }
+                catch (rollbackError) {
+                    rollbackErrors.push(`marketplace removal: ${rollbackError.message}`);
+                }
+            }
+            if (rollbackErrors.length > 0)
+                throw Object.assign(new Error(`Claude plugin installation failed and rollback was incomplete (${rollbackErrors.join('; ')})`), { cause: error, expected: true });
+            throw error;
+        }
+    }
     writeFileAtomic(t.hqPointer, pointerNew);
-    writeFileAtomic(t.claudeMd, mdNew);
-    fs.mkdirSync(t.skillsDir, { recursive: true });
+    if (mdOld !== mdNew) {
+        if (mdNew === null) {
+            if (fs.existsSync(t.claudeMd))
+                fs.unlinkSync(t.claudeMd);
+        }
+        else
+            writeFileAtomic(t.claudeMd, mdNew);
+    }
+    if (!pluginSource)
+        fs.mkdirSync(t.skillsDir, { recursive: true });
     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, hookTarget),
-        merge: (doc) => addHqHooks(doc, hqRoot, hookTarget),
-        assertName: 'hooks',
-        env: { home },
-    });
-    registerClaudeServer({ name: HQ_MCP_SERVER_NAME, manifest, pack: HQ_ANYWHERE_PACK, env: { home } });
+    if (pluginSource)
+        for (const link of skillLinksToRemove)
+            fs.unlinkSync(link);
+    if (pluginSource) {
+        // Migrate a prior direct install: remove only our old hook/MCP entries while
+        // retaining the original user settings for a later uninstall restore.
+        if (fs.existsSync(t.settingsJson)) {
+            writeConfigAtomic({
+                target: t.settingsJson,
+                pack: HQ_ANYWHERE_PACK,
+                format: settingsRemovalFormat(cleanupRoots, settingsOriginal),
+                merge: (doc) => cleanupRoots.reduce((current, root) => removeHqHooks(current, root), doc),
+                assertName: 'hooks',
+                env: { home },
+            });
+        }
+        unregisterClaudeServer({ name: HQ_MCP_SERVER_NAME, pack: HQ_ANYWHERE_PACK, env: { home } });
+    }
+    else {
+        writeConfigAtomic({
+            target: t.settingsJson,
+            pack: HQ_ANYWHERE_PACK,
+            format: settingsInstallFormat(hqRoot, hookTarget),
+            merge: (doc) => addHqHooks(doc, hqRoot, hookTarget),
+            assertName: 'hooks',
+            env: { home },
+        });
+        registerClaudeServer({ name: HQ_MCP_SERVER_NAME, manifest: manifest, pack: HQ_ANYWHERE_PACK, 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 = [];
@@ -262,25 +451,38 @@ export function installGlobalClaude(opts) {
     catch (e) {
         log(`Registry not seeded from companies/manifest.yaml: ${e.message}`);
     }
+    const recoveredDirectPointer = !!pluginSource && !prior && legacyRoot === pointerOld?.trim() && (directHooksRemoved !== settingsDoc || (mdOld !== null && removeClaudeMdBlock(mdOld) !== mdOld) || skillLinksToRemove.length > 0);
     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) ?? '' },
+        hqPointer: { original: prior ? prior.hqPointer.original : recoveredDirectPointer ? null : pointerOld },
+        claudeMd: { original: mdOriginal, installed: readOrNull(t.claudeMd) ?? '' },
+        settings: { original: settingsOriginal, installed: readOrNull(t.settingsJson) ?? '' },
         skills: {
-            linked: [...new Set([...(prior?.skills.linked ?? []), ...skills.link, ...skills.already])].sort(),
+            linked: pluginSource ? [] : [...new Set([...(prior?.skills.linked ?? []), ...skills.link, ...skills.already])].sort(),
             skipped: skills.skipped,
         },
         mcp: { name: HQ_MCP_SERVER_NAME, pack: HQ_ANYWHERE_PACK },
+        ...(pluginSource ? { plugin: {
+                pluginId: pluginSource.pluginId,
+                marketplaceName: pluginSource.marketplaceName,
+                sourceDir: pluginSource.sourceDir,
+                pluginAdded,
+                marketplaceAdded,
+                ...(hadPluginSetting ? { pluginSettingBefore } : {}),
+            } } : {}),
         seeded: [...new Set([...(prior?.seeded ?? []), ...ownedSeeded])].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: ${hookTarget === 'shim' ? 'hqd-hook-shim.sh' : 'master-hook.sh'} registered in ${t.settingsJson}`);
-    log(`  MCP: "${HQ_MCP_SERVER_NAME}" registered in ${t.claudeJson}`);
+    if (pluginSource)
+        log(`  plugin: ${pluginSource.pluginId} installed from ${pluginSource.sourceDir}; direct hooks and MCP entries removed`);
+    else {
+        log(`  hooks: ${hookTarget === 'shim' ? 'hqd-hook-shim.sh' : 'master-hook.sh'} registered in ${t.settingsJson}`);
+        log(`  MCP: "${HQ_MCP_SERVER_NAME}" registered in ${t.claudeJson}`);
+    }
     log(`  registry: ${seeded.length} manifest entr${seeded.length === 1 ? 'y' : 'ies'} seeded`);
     return touched;
 }
@@ -294,6 +496,13 @@ export function uninstallGlobalClaude(opts = {}) {
     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 pluginSource = state?.plugin ? {
+        sourceDir: state.plugin.sourceDir,
+        marketplaceName: state.plugin.marketplaceName,
+        pluginName: state.plugin.pluginId.slice(0, state.plugin.pluginId.lastIndexOf('@')),
+        pluginId: state.plugin.pluginId,
+    } : undefined;
+    const runClaude = opts.runClaude ?? runClaudeCli;
     const regFile = opts.registryFile ?? registryFile(registryDir(home, env));
     const touched = [];
     // MCP server (provenance-scoped: a foreign "hq" server is never removed).
@@ -304,7 +513,9 @@ export function uninstallGlobalClaude(opts = {}) {
     // settings.json hooks.
     const settingsOriginal = state ? state.settings.original : null;
     const settingsDoc = readConfigDoc(t.settingsJson, jsonFormat).doc;
-    const settingsNext = removeHqHooks(settingsDoc, hqRoot);
+    const settingsNext = pluginSource
+        ? removePluginSettings(removeHqHooks(settingsDoc, hqRoot), pluginSource, state?.plugin?.pluginAdded ?? true, state?.plugin?.marketplaceAdded ?? true, state?.plugin?.pluginSettingBefore)
+        : removeHqHooks(settingsDoc, hqRoot);
     if (settingsNext !== settingsDoc)
         touched.push(t.settingsJson);
     // Skills: only symlinks that point into this HQ checkout's skills dir.
@@ -349,15 +560,27 @@ export function uninstallGlobalClaude(opts = {}) {
             log(`  ${f}`);
         log(`\n--- ${t.settingsJson}`);
         log(lineDiff(jsonFormat.serialize(settingsDoc), jsonFormat.serialize(settingsNext)));
+        if (pluginSource)
+            log(`Would run: ${state?.plugin?.pluginAdded ? `claude plugin uninstall --scope user ${pluginSource.pluginId}` : '(plugin was pre-existing; leave it installed)'}${state?.plugin?.marketplaceAdded ? `; claude plugin marketplace remove --scope user ${pluginSource.marketplaceName}` : ''}`);
         return touched;
     }
+    if (pluginSource && state?.plugin?.pluginAdded) {
+        runClaude(['uninstall', '--scope', 'user', '--json', pluginSource.pluginId], home, env);
+    }
+    if (pluginSource && state?.plugin?.marketplaceAdded) {
+        runClaude(['marketplace', 'remove', '--scope', 'user', '--json', pluginSource.marketplaceName], home, env);
+    }
     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),
+            format: restoringRemovalFormat(settingsOriginal, (doc) => (pluginSource
+                ? removePluginSettings(removeHqHooks(doc, hqRoot), pluginSource, state?.plugin?.pluginAdded ?? true, state?.plugin?.marketplaceAdded ?? true, state?.plugin?.pluginSettingBefore) !== doc
+                : removeHqHooks(doc, hqRoot) !== doc)),
+            merge: (doc) => pluginSource
+                ? removePluginSettings(removeHqHooks(doc, hqRoot), pluginSource, state?.plugin?.pluginAdded ?? true, state?.plugin?.marketplaceAdded ?? true, state?.plugin?.pluginSettingBefore)
+                : removeHqHooks(doc, hqRoot),
             assertName: 'hooks',
             env: { home },
         });
@@ -393,7 +616,7 @@ export function uninstallGlobalClaude(opts = {}) {
                 throw e;
         }
     }
-    log(`HQ removed from Claude Code user scope (${links.length} skill link(s), hooks, MCP server, CLAUDE.md block).`);
+    log(`HQ removed from Claude Code user scope (${links.length} skill link(s), ${pluginSource ? 'plugin' : 'hooks and MCP server'}, CLAUDE.md block).`);
     return touched;
 }
 function readCodexState(t) {
@@ -686,8 +909,8 @@ export function uninstallGlobalCodex(opts = {}) {
 }
 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.`), {
+    if (r !== 'claude' && r !== 'codex' && r !== 'chatgpt' && r !== 'grok') {
+        throw Object.assign(new Error(`--runtime ${r} is not supported. Use --runtime claude, codex, chatgpt, or grok.`), {
             expected: true,
         });
     }
@@ -704,8 +927,17 @@ function resolveInstallRoot(explicit) {
 /** Entry used by `hq install --global` (wired from pkg-install.ts). */
 export function runInstallGlobal(opts) {
     const runtime = assertRuntime(opts.runtime);
+    if (runtime === 'chatgpt' || runtime === 'grok') {
+        if (!anywhereRuntimeEnabled(opts.env ?? process.env))
+            throw new AnywhereRuntimeDisabledError();
+        const endpoint = resolveHqMcpEndpoint(opts.env ?? process.env).toString();
+        const lines = runtime === 'chatgpt' ? chatgptConnectorInstructions(endpoint) : grokConnectorInstructions(endpoint);
+        for (const line of lines)
+            (opts.log ?? console.log)(line);
+        return;
+    }
     const install = runtime === 'codex' ? installGlobalCodex : installGlobalClaude;
-    install({ hqRoot: resolveInstallRoot(opts.hqRoot), dryRun: opts.dryRun });
+    install({ hqRoot: resolveInstallRoot(opts.hqRoot), dryRun: opts.dryRun, via: opts.via, marketplaceDir: opts.marketplaceDir });
 }
 export function registerUninstallCommand(program) {
     program
@@ -721,7 +953,10 @@ export function registerUninstallCommand(program) {
             process.exitCode = 1;
             return;
         }
-        const runtime = assertRuntime(opts.runtime);
+        const runtime = opts.runtime ?? 'claude';
+        if (runtime !== 'claude' && runtime !== 'codex') {
+            throw Object.assign(new Error(`--runtime ${runtime} has no local configuration to uninstall; remove its connector in the host application.`), { expected: true });
+        }
         const uninstall = runtime === 'codex' ? uninstallGlobalCodex : uninstallGlobalClaude;
         uninstall({ hqRoot: opts.hqRoot, dryRun: opts.dryRun });
     });

package/dist/commands/mcp-serve.js

@@ -15,7 +15,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { CLI_VERSION } from "../cli-version.js";
-import { HQ_ANYWHERE_RUNTIME_FLAG } from "./anywhere-runtime-flag.js";
+import { HQ_ANYWHERE_RUNTIME_FLAG } from "../lib/anywhere-runtime-flag-key.js";
 import { anywhereRuntimeEnabledFromSnapshot } from "../lib/anywhere-runtime-fast-flag.js";
 import { createLineSplitter, HqdClientError, hqdRequest, hqdSocketPath } from "../lib/daemon/protocol.js";
 export const MCP_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];

package/dist/commands/mcp-status.js

@@ -24,6 +24,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { anywhereRuntimeEnabled } from './anywhere-runtime-flag.js';
+import { claudeTargets } from '../lib/install/claude-targets.js';
 import { HQ_PACK_PROVENANCE_KEY, SECRET_REDACTION, backupRoot, claudeConfigFormat, claudeConfigPath, codexConfigFormat, codexConfigPath, CODEX_MCP_SERVERS_KEY, ConfigParseError, isCodexInstalled, readConfigDoc, resolveEnv, } from './mcp-registration.js';
 // ---------------------------------------------------------------------------
 // Pure status computation.
@@ -84,6 +85,49 @@ function summarizeDef(def) {
 function summariesDiffer(a, b) {
     return JSON.stringify(a) !== JSON.stringify(b);
 }
+function findAnywherePluginMcp(home) {
+    const claude = path.join(home, '.claude');
+    try {
+        const targets = claudeTargets(home);
+        const state = JSON.parse(fs.readFileSync(targets.stateFile, 'utf8'));
+        const pluginId = state.plugin?.pluginId;
+        if (typeof pluginId !== 'string' || pluginId.length === 0)
+            return undefined;
+        const settings = JSON.parse(fs.readFileSync(targets.settingsJson, 'utf8'));
+        if (settings.enabledPlugins?.[pluginId] !== true)
+            return undefined;
+        const installedFile = path.join(claude, 'plugins', 'installed_plugins.json');
+        const installed = JSON.parse(fs.readFileSync(installedFile, 'utf8'));
+        const install = installed.plugins?.[pluginId]?.find((entry) => typeof entry.installPath === 'string');
+        if (!install || typeof install.installPath !== 'string' || !path.isAbsolute(install.installPath))
+            return undefined;
+        const installDir = path.resolve(install.installPath);
+        const cacheRoot = path.resolve(claude, 'plugins', 'cache');
+        const cacheRelative = path.relative(cacheRoot, installDir);
+        if (cacheRelative.startsWith('..') || path.isAbsolute(cacheRelative) || !cacheRelative.split(path.sep).includes('hq'))
+            return undefined;
+        const file = path.join(installDir, '.mcp.json');
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            return undefined;
+        const doc = JSON.parse(fs.readFileSync(file, 'utf8'));
+        const server = doc.mcpServers?.hq;
+        return server && typeof server === 'object' && !Array.isArray(server) ? server : undefined;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        console.warn(`Skipping unavailable hq-anywhere plugin MCP metadata: ${error.message}`);
+        return undefined;
+    }
+}
+function pluginAndCodexMcpEquivalent(plugin, codex) {
+    const pArgs = Array.isArray(plugin.args) ? plugin.args : [];
+    const cArgs = Array.isArray(codex.args) ? codex.args : [];
+    const pluginTarget = plugin.type === 'stdio' && plugin.command === '/bin/sh' && pArgs.length === 3 && pArgs[0] === '${CLAUDE_PLUGIN_ROOT}/scripts/hq-claude-plugin-launch.sh' && pArgs[1] === 'mcp' && pArgs[2] === 'serve';
+    const codexTarget = codex.type === 'stdio' && typeof codex.command === 'string' && /(^|\/)hq$/.test(codex.command) && cArgs.length === 2 && cArgs[0] === 'mcp' && cArgs[1] === 'serve';
+    return pluginTarget && codexTarget && JSON.stringify(headerKeysOf(plugin)) === JSON.stringify(headerKeysOf(codex)) && JSON.stringify(envKeysOf(plugin)) === JSON.stringify(envKeysOf(codex));
+}
 /** Scan the Claude runtime: read `~/.claude.json`, collect HQ-owned servers. */
 function scanClaude(env) {
     const configPath = claudeConfigPath(env);
@@ -201,6 +245,17 @@ export function computeMcpStatus(env) {
     const checkHealth = anywhereRuntimeEnabled();
     const claudeScan = scanClaude(env);
     const codexScan = scanCodex(env);
+    // Claude plugins keep their MCP manifest beside the installed plugin rather
+    // than in ~/.claude.json. Pair the HQ plugin with the HQ pack's Codex entry
+    // so equivalent launchers do not show as absent or drifted.
+    const pluginMcp = checkHealth ? findAnywherePluginMcp(env.home) : undefined;
+    if (pluginMcp) {
+        for (const [name, found] of codexScan.hqServers) {
+            if (found.pack === 'hq-anywhere' || found.pack.endsWith('/hq-anywhere')) {
+                claudeScan.hqServers.set(name, { def: pluginMcp, pack: found.pack });
+            }
+        }
+    }
     // Union of every HQ-owned server name across both runtimes.
     const names = new Set([...claudeScan.hqServers.keys(), ...codexScan.hqServers.keys()]);
     const servers = [];
@@ -232,7 +287,9 @@ export function computeMcpStatus(env) {
         // DRIFT = present in both but transport-relevant content differs (no header VALUES).
         let drifted = false;
         if (onClaude && onCodex && claudeFound && codexFound) {
-            drifted = summariesDiffer(summarizeDef(claudeFound.def), summarizeDef(codexFound.def));
+            drifted = pluginMcp && claudeFound.def === pluginMcp && pluginAndCodexMcpEquivalent(pluginMcp, codexFound.def)
+                ? false
+                : summariesDiffer(summarizeDef(claudeFound.def), summarizeDef(codexFound.def));
         }
         servers.push({
             server: name,

package/dist/commands/pack-install.d.ts

@@ -278,7 +278,9 @@ export declare function verifyArtifact(input: VerifyArtifactInput): void;
  * @param item       the bare server name declared under `contributes.mcp`
  */
 export declare function validateMcpManifest(payloadDir: string, item: string): void;
-export declare function validateManifest(payloadDir: string, hqVersion: string | null): PackManifest;
+export declare function validateManifest(payloadDir: string, hqVersion: string | null, options?: {
+    allowReservedName?: boolean;
+}): PackManifest;
 /**
  * Enforce a pack's `requires.packs`: every named dependency MUST already be
  * installed (and satisfy its optional semver RANGE) before we write anything.