@indigoai-us/hq-cli 5.324.0 → 5.326.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [5.326.0] — 2026-10-02
+- Company-scoped daemon tools now reject an explicit company that conflicts with the active session or repository binding.
+- Added a flag-gated `hq mcp serve` command and global install hook for the Anywhere runtime.
+- `hq mcp serve` can forward supported calls to hosted hq-mcp, including search and fetch, without a local hq-mcp process.
+- Make standalone HQ auth refresh entry points run through npm bin symlinks.
+
+## [5.325.0] — 2026-10-02
+- Match Bash pathname expansion in native derive-trigger-facts when a glob has missing suffixes, a trailing slash, or symlink path components.
+
 ## [5.324.0] — 2026-10-02
 - Keep the bundled shell runner out of native fast-route startup and defer timeout-guard flag snapshot imports until a timeout would block.
 - Reuse the parsed fast-route entry when dispatching the selected command.

package/dist/bin/hq-auth-refresh.js

@@ -15,8 +15,7 @@
 import "../node-preflight.js";
 import { acquireCurrentPackageUseLease } from "../utils/package-use-lease.js";
 import "../node-network-compat.js";
-import { fileURLToPath } from "node:url";
-import path from "node:path";
+import { isMainModule } from "../utils/is-main-module.js";
 const MIN_VALIDITY_FLAG = "--min-validity-seconds";
 function parseMinimumValiditySeconds(argv, env) {
     let raw;
@@ -109,7 +108,7 @@ export async function startAuthRefresh(acquireLease = acquireCurrentPackageUseLe
     initSentry();
     return runAuthRefresh();
 }
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isMainModule(import.meta.url)) {
     void startAuthRefresh().then((exitCode) => process.exit(exitCode));
 }
 //# sourceMappingURL=hq-auth-refresh.js.map

package/dist/command-catalog.generated.d.ts

@@ -3720,6 +3720,15 @@ export declare const COMMAND_CATALOG: readonly [{
     readonly arguments: readonly [];
     readonly options: readonly [];
     readonly subcommands: readonly [{
+        readonly name: "serve";
+        readonly description: "Run the HQ stdio MCP server; every tool call is answered by hqd (`hq daemon status`)";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options]";
+        readonly arguments: readonly [];
+        readonly options: readonly [];
+        readonly subcommands: readonly [];
+    }, {
         readonly name: "status";
         readonly description: "Show installed MCP packs/servers and their health in BOTH Claude and Codex (PARTIAL/DRIFT flagged; secrets redacted)";
         readonly aliases: readonly ["list"];
@@ -9927,7 +9936,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "call";
-        readonly description: "Send one request to hqd (policy.check, journal.append, memory.get, memory.put, mesh.presence, …) and print the result as JSON";
+        readonly description: "Send one request to hqd (policy.check, journal.append, memory.get, memory.put, mesh.presence, mcp.call, …) and print the result as JSON";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly usage: "[options] <op>";

package/dist/command-catalog.generated.js

@@ -4801,6 +4801,16 @@ export const COMMAND_CATALOG = [
         "arguments": [],
         "options": [],
         "subcommands": [
+            {
+                "name": "serve",
+                "description": "Run the HQ stdio MCP server; every tool call is answered by hqd (`hq daemon status`)",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options]",
+                "arguments": [],
+                "options": [],
+                "subcommands": []
+            },
             {
                 "name": "status",
                 "description": "Show installed MCP packs/servers and their health in BOTH Claude and Codex (PARTIAL/DRIFT flagged; secrets redacted)",
@@ -12789,7 +12799,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "call",
-                "description": "Send one request to hqd (policy.check, journal.append, memory.get, memory.put, mesh.presence, …) and print the result as JSON",
+                "description": "Send one request to hqd (policy.check, journal.append, memory.get, memory.put, mesh.presence, mcp.call, …) and print the result as JSON",
                 "aliases": [],
                 "hidden": false,
                 "usage": "[options] <op>",

package/dist/commands/anywhere-runtime-flag.d.ts

@@ -1,5 +1,5 @@
-/** hq-flags key for the staged HQ Anywhere runtime. The registry default is off. */
-export declare const HQ_ANYWHERE_RUNTIME_FLAG = "hq-anywhere-runtime";
+import { HQ_ANYWHERE_RUNTIME_FLAG } from "../lib/anywhere-runtime-flag-key.js";
+export { HQ_ANYWHERE_RUNTIME_FLAG };
 export declare class AnywhereRuntimeDisabledError extends Error {
     readonly expected: true;
     constructor();

package/dist/commands/anywhere-runtime-flag.js

@@ -1,6 +1,6 @@
 import { resolveFlagGate, resolveProcessFlagGate } from "../lib/flag-registry.js";
-/** hq-flags key for the staged HQ Anywhere runtime. The registry default is off. */
-export const HQ_ANYWHERE_RUNTIME_FLAG = "hq-anywhere-runtime";
+import { HQ_ANYWHERE_RUNTIME_FLAG } from "../lib/anywhere-runtime-flag-key.js";
+export { HQ_ANYWHERE_RUNTIME_FLAG };
 export class AnywhereRuntimeDisabledError extends Error {
     expected = true;
     constructor() {

package/dist/commands/core-derive-trigger-facts-native.js

@@ -62,22 +62,50 @@ function globSegmentMatches(pattern, value) {
         return false;
     }
 }
+function filesystemPath(candidate, cwd) {
+    const value = candidate || ".";
+    return path.isAbsolute(value) ? value : `${cwd}${path.sep}${value}`;
+}
+function isDirectoryPath(candidate, cwd) {
+    try {
+        return fs.statSync(filesystemPath(candidate, cwd)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function pathEntryExists(candidate, cwd) {
+    try {
+        fs.lstatSync(filesystemPath(candidate, cwd));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function expandBashGlob(token, cwd) {
     if (!hasGlobPattern(token))
         return [token];
     const absolute = token.startsWith(path.sep);
+    const trailingSlash = token.endsWith(path.sep);
     const parts = token.split(path.sep).filter((part, index) => !(absolute && index === 0));
+    if (trailingSlash)
+        parts.pop();
     let candidates = [absolute ? path.sep : ""];
     let matchedPattern = false;
-    for (const part of parts) {
+    for (const [index, part] of parts.entries()) {
         if (!hasGlobPattern(part)) {
             candidates = candidates.map((parent) => !parent ? part : parent === path.sep ? `${path.sep}${part}` : `${parent}${path.sep}${part}`);
+            if (matchedPattern) {
+                const needsDirectory = index < parts.length - 1 || trailingSlash;
+                candidates = candidates.filter((candidate) => needsDirectory ? isDirectoryPath(candidate, cwd) : pathEntryExists(candidate, cwd));
+            }
             continue;
         }
         matchedPattern = true;
         const expanded = [];
         for (const parent of candidates) {
-            const directory = absolute ? (parent || path.sep) : path.resolve(cwd, parent || ".");
+            const directory = filesystemPath(parent || ".", cwd);
             let names;
             try {
                 names = fs.readdirSync(directory).sort();
@@ -97,7 +125,13 @@ function expandBashGlob(token, cwd) {
             return [token];
         candidates = expanded;
     }
-    return matchedPattern ? candidates : [token];
+    if (trailingSlash) {
+        candidates = candidates
+            .filter((candidate) => isDirectoryPath(candidate, cwd))
+            .map((candidate) => candidate.endsWith(path.sep) ? candidate : `${candidate}${path.sep}`)
+            .sort();
+    }
+    return matchedPattern && candidates.length > 0 ? candidates : [token];
 }
 function bashUnquotedWords(facts, cwd) {
     return facts.join(" ").split(/[\t\n ]+/).filter(Boolean).flatMap((word) => expandBashGlob(word, cwd));

package/dist/commands/core-job-remote-launcher.js

@@ -1,7 +1,6 @@
 import { spawn } from "node:child_process";
 import * as fs from "node:fs";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
+import { isMainModule } from "../utils/is-main-module.js";
 function signalNumber(signal) {
     if (!signal)
         return 0;
@@ -40,7 +39,7 @@ export async function runRemoteLauncher(argv, injected = {}) {
     await deps.sleep(15_000);
     return exitCode;
 }
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isMainModule(import.meta.url)) {
     void runRemoteLauncher(process.argv.slice(2))
         .then((exitCode) => { process.exitCode = exitCode; })
         .catch((error) => {

package/dist/commands/daemon.js

@@ -769,7 +769,7 @@ export function registerDaemonCommand(program, over = {}) {
     }));
     daemon
         .command("call <op>")
-        .description("Send one request to hqd (policy.check, journal.append, memory.get, memory.put, mesh.presence, …) and print the result as JSON")
+        .description("Send one request to hqd (policy.check, journal.append, memory.get, memory.put, mesh.presence, mcp.call, …) and print the result as JSON")
         .option("--json <args>", "Request args as a JSON object", "{}")
         .option("--timeout <ms>", "Give up after this many milliseconds")
         .action(wrap(async (d, op, opts) => {

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

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
 import { AnywhereRuntimeDisabledError } from './anywhere-runtime-flag.js';
+import { type HookTarget } from '../lib/install/claude-targets.js';
 export interface GlobalInstallOptions {
     /** HQ checkout to install from (absolute). */
     hqRoot: string;
@@ -14,7 +15,16 @@ export interface GlobalInstallOptions {
     /** Registry file override (default ~/.hq/registry.json under `home`). */
     registryFile?: string;
     log?: (line: string) => void;
+    /** Is the hq daemon installed? Default: look for its launchd/systemd unit under `home`. */
+    daemonInstalled?: boolean;
 }
+/** 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;
+/**
+ * US-010: with hqd installed (and the checkout shipping the shim), hooks go to
+ * 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 { 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). */

package/dist/commands/install-global.js

@@ -10,13 +10,38 @@
  */
 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 { spawnSync } from 'node:child_process';
+import { buildCodexServerDef, claudeConfigFormat, codexConfigFormat, isCodexInstalled, jsonFormat, mergeCodexServer, registerCodexServer, unregisterCodexServer, mergeClaudeServer, readConfigDoc, realpathOrSelf, registerClaudeServer, 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 { DAEMON_LAUNCHD_LABEL, DAEMON_SYSTEMD_UNIT, DAEMON_WINDOWS_TASK, SYSTEM_UNIT_DIR } from '../lib/daemon/install.js';
+import { readDaemonConfig } from '../lib/daemon/config.js';
+import { daemonPaths } from '../lib/daemon/paths.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';
+import { addClaudeMdBlock, addHqHooks, charterPath, claudeTargets, hasAllHqHooks, HQ_ANYWHERE_PACK, HQ_MCP_SERVER_NAME, hqSkillsSource, lineDiff, masterHookPath, shimPath, MCP_SUBPROCESS_PATH, removeClaudeMdBlock, removeHqHooks, SKILL_LINK_PREFIX, } from '../lib/install/claude-targets.js';
+/** True when an hq daemon unit (launchd plist or systemd unit) exists. */
+export function isDaemonInstalled(home, platform = process.platform, queryTask = (task) => spawnSync('schtasks.exe', ['/Query', '/TN', task], { encoding: 'utf8', windowsHide: true }).status === 0) {
+    if (platform === 'win32')
+        return queryTask(DAEMON_WINDOWS_TASK);
+    const candidates = platform === 'darwin'
+        ? [path.join(home, 'Library', 'LaunchAgents', `${DAEMON_LAUNCHD_LABEL}.plist`)]
+        : platform === 'linux'
+            ? [path.join(home, '.config', 'systemd', 'user', DAEMON_SYSTEMD_UNIT), path.join(SYSTEM_UNIT_DIR, DAEMON_SYSTEMD_UNIT)]
+            : [];
+    return candidates.some((p) => fs.existsSync(p));
+}
+/**
+ * US-010: with hqd installed (and the checkout shipping the shim), hooks go to
+ * the hqd shim; otherwise to master-hook.sh / the Codex adapter.
+ */
+export function hookTargetFor(hqRoot, home, daemonInstalled, env = process.env) {
+    const installed = daemonInstalled ?? isDaemonInstalled(home);
+    const configuredRoot = readDaemonConfig(daemonPaths(home, env).configPath).hqRoot;
+    const daemonMatchesRoot = configuredRoot !== undefined && realpathOrSelf(configuredRoot) === realpathOrSelf(hqRoot);
+    return installed && daemonMatchesRoot && fs.existsSync(shimPath(hqRoot)) ? 'shim' : 'master';
+}
 export { AnywhereRuntimeDisabledError as AnywhereDisabledError };
 export const isAnywhereEnabled = (_home, env = process.env) => anywhereRuntimeEnabled(env);
 function readOrNull(file) {
@@ -30,11 +55,10 @@ function readOrNull(file) {
     }
 }
 function writeFileAtomic(file, data) {
-    const target = realpathOrSelf(file);
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    const tmp = `${target}.hq-tmp-${process.pid}`;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.hq-tmp-${process.pid}`;
     fs.writeFileSync(tmp, data);
-    fs.renameSync(tmp, target);
+    fs.renameSync(tmp, file);
 }
 function canonical(v) {
     return JSON.stringify(v, (_k, val) => val && typeof val === 'object' && !Array.isArray(val)
@@ -42,12 +66,12 @@ function canonical(v) {
         : val);
 }
 /** JSON settings format whose verify step checks every HQ hook is registered. */
-function settingsInstallFormat(hqRoot) {
+function settingsInstallFormat(hqRoot, target) {
     return {
         ...jsonFormat,
         emptyDoc: () => ({}),
         assertEntry(doc) {
-            if (!hasAllHqHooks(doc, hqRoot))
+            if (!hasAllHqHooks(doc, hqRoot, target))
                 throw new Error('HQ hooks not present after write');
         },
     };
@@ -84,9 +108,18 @@ function restoringRemovalFormat(original, stillPresent) {
         },
     };
 }
-function planSkills(hqRoot, t, previouslyManaged = []) {
+function mcpManifest(opts) {
+    const command = opts.nodePath ?? process.execPath;
+    const entry = opts.cliEntry ?? fs.realpathSync(process.argv[1] ?? '');
+    for (const p of [command, entry]) {
+        if (!path.isAbsolute(p))
+            throw new Error(`HQ MCP server path must be absolute: ${p}`);
+    }
+    return { type: 'stdio', command, args: [entry, 'mcp', 'serve'], env: { PATH: MCP_SUBPROCESS_PATH } };
+}
+function planSkills(hqRoot, t) {
     const source = hqSkillsSource(hqRoot);
-    const plan = { link: [], replace: [], already: [], skipped: [] };
+    const plan = { link: [], already: [], skipped: [] };
     let names;
     try {
         names = fs
@@ -115,10 +148,6 @@ function planSkills(hqRoot, t, previouslyManaged = []) {
             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);
     }
@@ -164,15 +193,23 @@ export function installGlobalClaude(opts) {
     const t = claudeTargets(home);
     const prior = readState(t);
     const regFile = opts.registryFile ?? registryFile(registryDir(home, env));
+    const manifest = 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, prior?.skills.linked ?? []);
+    const skills = planSkills(hqRoot, t);
     const settingsOld = readOrNull(t.settingsJson);
     const settingsDoc = readConfigDoc(t.settingsJson, jsonFormat).doc;
-    const settingsNext = addHqHooks(settingsDoc, hqRoot);
+    const hookTarget = hookTargetFor(hqRoot, home, opts.daemonInstalled, env);
+    const settingsNext = addHqHooks(settingsDoc, hqRoot, hookTarget);
+    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, {
+        ...manifest,
+        _hqPack: HQ_ANYWHERE_PACK,
+    })(claudeDoc);
     if (pointerOld !== pointerNew)
         touched.push(t.hqPointer);
     if (mdOld !== mdNew)
@@ -181,6 +218,8 @@ export function installGlobalClaude(opts) {
         touched.push(path.join(t.skillsDir, `${SKILL_LINK_PREFIX}${s}`));
     if (settingsNext !== settingsDoc)
         touched.push(t.settingsJson);
+    if (claudeNext !== claudeDoc)
+        touched.push(t.claudeJson);
     touched.push(regFile, t.stateFile);
     if (opts.dryRun) {
         log(`hq install --global --runtime claude --dry-run (HQ root ${hqRoot})`);
@@ -192,29 +231,33 @@ export function installGlobalClaude(opts) {
         }
         log(`\n--- ${t.settingsJson}`);
         log(lineDiff(jsonFormat.serialize(settingsDoc), jsonFormat.serialize(settingsNext)));
+        log(`\n--- ${t.claudeJson}`);
+        log(lineDiff(jsonFormat.serialize(claudeDoc), jsonFormat.serialize(claudeNext)));
         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),
+        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 } });
     // 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 = [];
+    let ownedSeeded = [];
     try {
-        seeded = seedRegistryFromHqRoot(hqRoot, { file: regFile }).owned;
+        const result = seedRegistryFromHqRoot(hqRoot, { file: regFile });
+        seeded = result.added;
+        ownedSeeded = result.owned;
     }
     catch (e) {
         log(`Registry not seeded from companies/manifest.yaml: ${e.message}`);
@@ -231,13 +274,13 @@ export function installGlobalClaude(opts) {
             skipped: skills.skipped,
         },
         mcp: { name: HQ_MCP_SERVER_NAME, pack: HQ_ANYWHERE_PACK },
-        seeded: [...new Set([...(prior?.seeded ?? []), ...seeded])].sort(),
+        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: master-hook.sh registered in ${t.settingsJson}`);
-    log('  MCP server registration is added by the stacked MCP shim change.');
+    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;
 }
@@ -367,12 +410,12 @@ function assertCodexHqRoot(hqRoot) {
             throw new Error(`${hqRoot} is not an HQ checkout (missing ${p})`);
     }
 }
-function hooksInstallFormat(hqRoot) {
+function hooksInstallFormat(hqRoot, target) {
     return {
         ...jsonFormat,
         emptyDoc: () => ({}),
         assertEntry(doc) {
-            if (!hasAllCodexHooks(doc, hqRoot))
+            if (!hasAllCodexHooks(doc, hqRoot, target))
                 throw new Error('HQ Codex hooks not present after write');
         },
     };
@@ -399,6 +442,7 @@ export function installGlobalCodex(opts) {
     const hqPointer = claudeTargets(home).hqPointer;
     const prior = readCodexState(t);
     const regFile = opts.registryFile ?? registryFile(registryDir(home, env));
+    const manifest = mcpManifest(opts);
     const touched = [];
     const pointerOld = readOrNull(hqPointer);
     const pointerNew = `${hqRoot}\n`;
@@ -406,11 +450,20 @@ export function installGlobalCodex(opts) {
     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 legacyPath = path.join(t.skillsDir, LEGACY_SKILLS_NAME);
+    const legacyBackupPath = path.join(t.skillsDir, LEGACY_BACKUP_NAME);
+    if (legacy.kind === 'hq-dir' && fs.existsSync(legacyBackupPath)) {
+        throw new Error(`${legacyBackupPath} already exists; move it away before installing.`);
+    }
+    const skills = planSkills(hqRoot, t);
     const hooksOld = readOrNull(t.hooksJson);
-    const tomlOld = readOrNull(t.configToml);
     const hooksDoc = readConfigDoc(t.hooksJson, jsonFormat).doc;
-    const hooksNext = addCodexHooks(hooksDoc, hqRoot);
+    const hookTarget = hookTargetFor(hqRoot, home, opts.daemonInstalled, env);
+    const hooksNext = addCodexHooks(hooksDoc, hqRoot, hookTarget);
+    const tomlOld = readOrNull(t.configToml);
+    const tomlDoc = readConfigDoc(t.configToml, codexConfigFormat).doc;
+    // Collision check runs here too, so a dry run surfaces a conflicting "hq" server.
+    const tomlNext = mergeCodexServer(HQ_MCP_SERVER_NAME, buildCodexServerDef(manifest, HQ_ANYWHERE_PACK, () => null, new Set()))(tomlDoc);
     if (pointerOld !== pointerNew)
         touched.push(hqPointer);
     if (mdOld !== mdNew)
@@ -421,6 +474,8 @@ export function installGlobalCodex(opts) {
         touched.push(path.join(t.skillsDir, `${SKILL_LINK_PREFIX}${s}`));
     if (hooksNext !== hooksDoc)
         touched.push(t.hooksJson);
+    if (tomlNext !== tomlDoc)
+        touched.push(t.configToml);
     touched.push(regFile, t.stateFile);
     if (opts.dryRun) {
         log(`hq install --global --runtime codex --dry-run (HQ root ${hqRoot})`);
@@ -437,16 +492,14 @@ export function installGlobalCodex(opts) {
         }
         log(`\n--- ${t.hooksJson}`);
         log(lineDiff(jsonFormat.serialize(hooksDoc), jsonFormat.serialize(hooksNext)));
+        log(`\n--- ${t.configToml}`);
+        log(lineDiff(codexConfigFormat.serialize(tomlDoc), codexConfigFormat.serialize(tomlNext)));
         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 };
@@ -459,22 +512,24 @@ export function installGlobalCodex(opts) {
     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),
+        format: hooksInstallFormat(hqRoot, hookTarget),
+        merge: (doc) => addCodexHooks(doc, hqRoot, hookTarget),
         assertName: 'hooks',
         env: { home },
     });
+    registerCodexServer({ name: HQ_MCP_SERVER_NAME, manifest, pack: HQ_ANYWHERE_PACK, env: { home } });
     let seeded = [];
+    let ownedSeeded = [];
     try {
-        seeded = seedRegistryFromHqRoot(hqRoot, { file: regFile }).owned;
+        const result = seedRegistryFromHqRoot(hqRoot, { file: regFile });
+        seeded = result.added;
+        ownedSeeded = result.owned;
     }
     catch (e) {
         log(`Registry not seeded from companies/manifest.yaml: ${e.message}`);
@@ -492,13 +547,13 @@ export function installGlobalCodex(opts) {
         },
         legacy: legacyRecord,
         mcp: { name: HQ_MCP_SERVER_NAME, pack: HQ_ANYWHERE_PACK },
-        seeded: [...new Set([...(prior?.seeded ?? []), ...seeded])].sort(),
+        seeded: [...new Set([...(prior?.seeded ?? []), ...ownedSeeded])].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.');
+    log(`  hooks: ${hookTarget === 'shim' ? shimPath(hqRoot) : codexAdapterPath(hqRoot)} registered in ${t.hooksJson}`);
+    log(`  MCP: "${HQ_MCP_SERVER_NAME}" registered in ${t.configToml}`);
     return touched;
 }
 /** Reverse every Codex install step; non-HQ entries are left untouched. */

package/dist/commands/mcp-serve.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `hq mcp serve` (hq-anywhere US-011): a stdio MCP server that forwards every
+ * tool call to hqd over its socket.
+ *
+ * It keeps no state between requests, so an orphaned instance costs nothing
+ * (policy mcp-process-cleanup). src/index.ts routes `hq mcp serve` straight to
+ * {@link runMcpServe} without loading the command graph, which keeps start-up
+ * under 100ms. The MCP SDK is not loaded either: the stdio transport is
+ * newline-delimited JSON-RPC 2.0 and is handled here directly.
+ *
+ * When hqd is unreachable every tool call returns an isError result naming
+ * `hq daemon status`, and the server keeps running.
+ */
+export declare const MCP_PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+export interface McpServeOptions {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    cwd?: string;
+    /** Per-call hqd budget. Default 120s; policy checks and hq-mcp tools can be slow. */
+    timeoutMs?: number;
+}
+/** HQ root for prompts: HQ_ROOT, else the ~/.hq/root pointer written by `hq install --global`. */
+export declare function readHqRoot(env: NodeJS.ProcessEnv, home: string): string | null;
+/** Run the server until input ends. Resolves when stdin closes. */
+export declare function runMcpServe(opts?: McpServeOptions): Promise<void>;
+//# sourceMappingURL=mcp-serve.d.ts.map