@indigoai-us/hq-cli 5.345.147 → 5.345.149

package/dist/lib/flag-registry.js

@@ -12,6 +12,7 @@ import { FLAG_REGISTRY_WORKER_SOURCE } from "./flag-registry-worker-source.gener
 import { resolveFlagSnapshotCompanyUid, resolveProcessFlagCompanyContext } from "./process-flag-company-context.js";
 import { registerFlagRegistryRefreshWaiter } from "./flag-registry-refresh-wait.js";
 import { flagSnapshotWriteFailureTags, readDefaultOnFlagSnapshot, readFlagSnapshotFile, writePersonFlagSnapshotFile, writeFlagSnapshotFile, } from "./flag-snapshot-file.js";
+import { freshAnywhereRuntimeFlags } from "./anywhere-runtime-flag-key.js";
 function captureFlagRegistryException(error, tags, sentry) {
     if (!sentry)
         return;
@@ -42,6 +43,7 @@ function normalizedCompanyUid(value) {
     return COMPANY_UID_RE.test(candidate) ? candidate : undefined;
 }
 let heldSnapshot = null;
+let heldSnapshotFetchedAt = 0;
 let processReader = null;
 let refreshCompletion = Promise.resolve();
 let completeRefresh = null;
@@ -113,7 +115,10 @@ function localOverrideOrFallback(flagKey, legacyFallback, env = process.env) {
     return processLocalOverride(flagKey, env) ?? legacyFallback();
 }
 /** Create the same snapshot-backed reader used by process gates. */
-export function createProcessSnapshotReader(companyIdentifiers, getSnapshot = () => heldSnapshot, env = process.env) {
+export function createProcessSnapshotReader(companyIdentifiers, getSnapshot = () => heldSnapshot && ({
+    ...heldSnapshot,
+    flags: freshAnywhereRuntimeFlags(heldSnapshot.flags, heldSnapshotFetchedAt),
+}), env = process.env) {
     return {
         isEnabled(flagKey, lookup = {}) {
             return resolveFlag({
@@ -169,6 +174,7 @@ export function kickFlagRegistryReadiness(dependencies = {}) {
         : null;
     if (persistedSnapshot) {
         heldSnapshot = { version: 0, flags: persistedSnapshot.flags };
+        heldSnapshotFetchedAt = Date.parse(persistedSnapshot.fetched_at);
     }
     refreshCompletion = Promise.resolve();
     completeRefresh = null;
@@ -234,6 +240,7 @@ export function kickFlagRegistryReadiness(dependencies = {}) {
         worker.on("message", (value) => {
             if (isFlagSnapshot(value)) {
                 heldSnapshot = value;
+                heldSnapshotFetchedAt = Date.now();
                 if (completeRefresh)
                     refreshPendingSnapshot = value;
                 if (refreshCompanyUid && refreshPendingSnapshot) {
@@ -392,6 +399,7 @@ export function currentFlagSnapshot() {
 /** Test-only reset for process-global readiness state. */
 export function _resetFlagRegistryForTests() {
     heldSnapshot = null;
+    heldSnapshotFetchedAt = 0;
     processReader = null;
     refreshCompletion = Promise.resolve();
     completeRefresh = null;

package/dist/lib/flag-snapshot-file.js

@@ -2,6 +2,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { freshAnywhereRuntimeFlags, HQ_ANYWHERE_RUNTIME_FLAG, HQ_ANYWHERE_RUNTIME_FALSE_MAX_AGE_MS } from "./anywhere-runtime-flag-key.js";
 export const FLAG_SNAPSHOT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 const COMPANY_UID_RE = /^cmp_[A-Za-z0-9]{3,128}$/;
 function markWriteFailure(error, context) {
@@ -263,7 +264,7 @@ export function readPersonFlagSnapshotFile(options = {}) {
             continue;
         if (file === fallback && fallback)
             fallbackCacheUsed = true;
-        return { scope: "person", fetched_at: value.fetched_at, flags: flags };
+        return { scope: "person", fetched_at: value.fetched_at, flags: freshAnywhereRuntimeFlags(flags, fetchedAt, options.now) };
     }
     return null;
 }
@@ -348,7 +349,7 @@ function parseSnapshotFile(companyUid, file, options) {
     return {
         company_uid: companyUid,
         fetched_at: value.fetched_at,
-        flags: flags,
+        flags: freshAnywhereRuntimeFlags(flags, fetchedAt, options.now),
     };
 }
 /** Return null for every miss, malformed file, company mismatch, or stale file. */
@@ -374,7 +375,11 @@ export function readFlagSnapshotFile(companyUid, options = {}) {
 }
 /** Resolve a default-on kill switch from offline snapshots, allowing stale decisions. */
 export function readDefaultOnFlagSnapshot(flagKey, companyUid, env = process.env) {
-    const options = { env, maxAgeMs: Number.POSITIVE_INFINITY };
+    // Native-route kill switches intentionally retain stale decisions. Only
+    // Anywhere has the GA one-hour disable limit; do not change other gates.
+    const options = { env, maxAgeMs: flagKey === HQ_ANYWHERE_RUNTIME_FLAG
+            ? HQ_ANYWHERE_RUNTIME_FALSE_MAX_AGE_MS
+            : Number.POSITIVE_INFINITY };
     if (companyUid)
         return readFlagSnapshotFile(companyUid, options)?.flags[flagKey] !== false;
     const directories = new Set([path.dirname(personFlagSnapshotPath(env))]);

package/dist/lib/hook-engine/reconcile.d.ts

@@ -0,0 +1,9 @@
+export interface ReconcileResult {
+    /** Codex user-scope trust keys for the HQ entries in the global hooks.json. */
+    codexUserKeys: string[];
+    /** One `<file>: <reason>` line per registration file left unchanged by an error. */
+    failures: string[];
+}
+/** Reconcile existing registrations only; reindex must not install a runtime. */
+export declare function reconcileHookRegistrations(root: string, home?: string, env?: NodeJS.ProcessEnv, daemonInstalled?: boolean): ReconcileResult;
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/lib/hook-engine/reconcile.js

@@ -0,0 +1,134 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { writeConfigAtomic, jsonFormat } from '../../commands/mcp-registration.js';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { addHqHooks, removeHqHooks } from '../install/claude-targets.js';
+import { hookTargetFor } from '../install/hook-target.js';
+import { addCodexHooks, removeCodexHooks, codexHookEntry, codexHookTrustKeys } from '../install/codex-targets.js';
+import { engineArgs, isNativeEntry, registrationEngine } from './registration.js';
+/** The project master-hook command shipped in HQ's .claude/settings.json. */
+function projectClaudeCommand(event) {
+    return 'env BASH_ENV=/dev/null bash "$CLAUDE_PROJECT_DIR/.claude/hooks/master-hook.sh" ' + event;
+}
+/**
+ * Rewrite matching entries where they sit. Groups, order, foreign entries and
+ * extra fields such as timeout are kept, so a flag-on then flag-off pass
+ * restores the original file.
+ */
+function rewriteEntries(doc, convert) {
+    let changed = false;
+    const hooks = {};
+    for (const [event, groups] of Object.entries(doc.hooks)) {
+        hooks[event] = !Array.isArray(groups) ? groups : groups.map((group) => {
+            if (!Array.isArray(group?.hooks))
+                return group;
+            return { ...group, hooks: group.hooks.map((entry) => {
+                    const next = entry && typeof entry === 'object' ? convert(entry, event) : undefined;
+                    if (!next)
+                        return entry;
+                    changed = true;
+                    return next;
+                }) };
+        });
+    }
+    return changed ? { ...doc, hooks } : doc;
+}
+/** Reconcile existing registrations only; reindex must not install a runtime. */
+export function reconcileHookRegistrations(root, home = homedir(), env = process.env, daemonInstalled) {
+    const result = { codexUserKeys: [], failures: [] };
+    const engine = registrationEngine(home, env);
+    // Flag-off rollback restores the same bash target install would choose (the
+    // hqd shim when the daemon serves this root). Resolved only when a
+    // registration is rewritten, so the default-off path reads no daemon state.
+    let target;
+    const globalTarget = () => (target ??= engine ? { engine } : hookTargetFor(root, home, daemonInstalled, env));
+    const codexBash = (event) => [codexHookEntry(root, event, 'master').command, codexHookEntry(root, event, 'shim').command];
+    for (const [file, runtime, global] of [
+        [join(root, '.claude/settings.json'), 'claude', false],
+        [join(env.CLAUDE_CONFIG_DIR || join(home, '.claude'), 'settings.json'), 'claude', true],
+        [join(env.CODEX_HOME || join(home, '.codex'), 'hooks.json'), 'codex', true],
+        [join(root, '.codex/hooks.json'), 'codex', false],
+    ]) {
+        // Each file stands alone: an unreadable or locked project file must not
+        // undo or hide the trust keys of a global file already rewritten.
+        try {
+            if (!existsSync(file))
+                continue;
+            // Default-off must not acquire a write lock or create backups for a legacy
+            // registration. The merge below repeats this check under the lock when a
+            // native entry was found, so a concurrent writer still wins safely.
+            if (!engine) {
+                let current;
+                // A file we cannot parse holds no native entry of ours; leave it untouched.
+                try {
+                    current = jsonFormat.parse(readFileSync(file, 'utf8'));
+                }
+                catch {
+                    continue;
+                }
+                const entries = current?.hooks && typeof current.hooks === 'object'
+                    ? Object.values(current.hooks).flatMap(groups => Array.isArray(groups) ? groups.flatMap(g => Array.isArray(g?.hooks) ? g.hooks : []) : [])
+                    : [];
+                if (!entries.some(e => e && isNativeEntry(e, root)))
+                    continue;
+            }
+            let expected;
+            let codexKeys;
+            writeConfigAtomic({ target: file, pack: 'hq-hook-engine', format: {
+                    ...jsonFormat,
+                    assertEntry: (doc) => {
+                        if (expected !== undefined && JSON.stringify(doc) !== expected)
+                            throw new Error('Hook registration verification failed');
+                    },
+                }, env: { home }, assertName: 'hooks', merge: (doc) => {
+                    if (!doc || typeof doc !== 'object' || !doc.hooks || typeof doc.hooks !== 'object')
+                        return doc;
+                    const entries = Object.values(doc.hooks).flatMap(groups => Array.isArray(groups) ? groups.flatMap(g => Array.isArray(g?.hooks) ? g.hooks : []) : []);
+                    if (!engine && !entries.some(e => e && isNativeEntry(e, root)))
+                        return doc;
+                    if (global && (runtime === 'codex' ? removeCodexHooks(doc, root) : removeHqHooks(doc, root)) === doc)
+                        return doc;
+                    let next;
+                    if (global)
+                        next = runtime === 'codex' ? addCodexHooks(doc, root, globalTarget()) : addHqHooks(doc, root, globalTarget());
+                    else if (runtime === 'codex') {
+                        // Only an entry install itself writes is converted. HQ's own project
+                        // file routes through hook-gate.sh and has none, so it stays as is.
+                        next = rewriteEntries(doc, (entry, event) => {
+                            if (!isNativeEntry(entry, root) && !codexBash(event).includes(entry.command))
+                                return undefined;
+                            const { command: _command, commandWindows: _windows, ...rest } = entry;
+                            const { command, commandWindows } = codexHookEntry(root, event, globalTarget());
+                            return { ...rest, command, ...(commandWindows ? { commandWindows } : {}) };
+                        });
+                    }
+                    else {
+                        // Only the exact shipped master-hook command is converted; a wrapped
+                        // or extended invocation is someone's edit and is left alone.
+                        next = rewriteEntries(doc, (entry, event) => {
+                            if (!isNativeEntry(entry, root) && entry.command !== projectClaudeCommand(event))
+                                return undefined;
+                            const { args, commandWindows: _windows, ...rest } = entry;
+                            if (engine)
+                                return { ...rest, command: engine, args: engineArgs(root, event, 'claude') };
+                            return { ...rest, command: projectClaudeCommand(Array.isArray(args) && typeof args[0] === 'string' ? args[0] : event) };
+                        });
+                    }
+                    expected = JSON.stringify(next);
+                    if (runtime === 'codex' && global)
+                        codexKeys = codexHookTrustKeys(next, file, root);
+                    return next;
+                } });
+            // Keys are positions in the file. Only once the write and its verify have
+            // succeeded do they point at HQ's entries; a failed write leaves the old
+            // file, where the same position can hold a foreign hook.
+            if (codexKeys)
+                result.codexUserKeys = codexKeys;
+        }
+        catch (error) {
+            result.failures.push(`${file}: ${error.message}`);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=reconcile.js.map

package/dist/lib/hook-engine/registration.d.ts

@@ -0,0 +1,17 @@
+export declare function launcherEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function registrationEngine(home: string, env?: NodeJS.ProcessEnv): string | null;
+export interface NativeTarget {
+    engine: string;
+}
+/**
+ * Root spelling passed to the launcher. A trailing separator is dropped because
+ * Windows PowerShell 5.1 re-quotes a native argument containing a space as
+ * "...", and a final backslash would then escape the closing quote.
+ */
+export declare function launcherRoot(root: string): string;
+export declare function engineArgs(root: string, event: string, runtime: 'claude' | 'codex', global?: boolean): string[];
+/** Recognize only our pinned executable with the exact root argument. */
+export declare function isNativeEntry(entry: Record<string, unknown>, root: string): boolean;
+export declare function quotePosix(value: string): string;
+export declare function quoteWindows(value: string): string;
+//# sourceMappingURL=registration.d.ts.map

package/dist/lib/hook-engine/registration.js

@@ -0,0 +1,50 @@
+/** Offline, default-off registration gate. No network work on the hook path. */
+import { readFlagSnapshotFile, readPersonFlagSnapshotFile } from '../flag-snapshot-file.js';
+import { resolveProcessFlagCompanyContext } from '../process-flag-company-context.js';
+import { installHookEngine } from './resolve.js';
+export function launcherEnabled(env = process.env) {
+    const { companyUid: uid, companySlug } = resolveProcessFlagCompanyContext(env);
+    if (!uid && companySlug)
+        return false;
+    const snapshot = uid ? readFlagSnapshotFile(uid, { env }) : readPersonFlagSnapshotFile({ env });
+    return snapshot?.flags['hook-engine-launcher'] === true;
+}
+export function registrationEngine(home, env = process.env) {
+    if (!launcherEnabled({ ...env, HOME: home, USERPROFILE: home }))
+        return null;
+    return installHookEngine({ home });
+}
+/**
+ * Root spelling passed to the launcher. A trailing separator is dropped because
+ * Windows PowerShell 5.1 re-quotes a native argument containing a space as
+ * "...", and a final backslash would then escape the closing quote.
+ */
+export function launcherRoot(root) {
+    const trimmed = root.replace(/[\\/]+$/, '');
+    return trimmed === '' || /^[A-Za-z]:$/.test(trimmed) ? root : trimmed;
+}
+export function engineArgs(root, event, runtime, global = false) {
+    return [event, '--hq-root', launcherRoot(root), '--runtime', runtime, ...(global && runtime === 'claude' ? ['--global'] : [])];
+}
+/** Recognize only our pinned executable with the exact root argument. */
+export function isNativeEntry(entry, root) {
+    if (typeof entry.command !== 'string')
+        return false;
+    const pinned = /[\\/]\.hq[\\/]bin[\\/]hq-hook[\\/]\d+\.\d+\.\d+[^\\/]*[\\/]/;
+    if (!pinned.test(entry.command))
+        return false;
+    const spelling = launcherRoot(root);
+    if (Array.isArray(entry.args)) {
+        const i = entry.args.indexOf('--hq-root');
+        return i >= 0 && entry.args[i + 1] === spelling;
+    }
+    return entry.command.includes(quotePosix('--hq-root') + ' ' + quotePosix(spelling));
+}
+export function quotePosix(value) { return "'" + value.replace(/'/g, "'\\''") + "'"; }
+export function quoteWindows(value) {
+    // Codex 0.162.1 uses its Windows PowerShell runtime shell for hooks.
+    // Single-quoted literals prevent variable, subexpression and wildcard expansion.
+    // PowerShell also closes them on the typographic quotes U+2018-U+201B.
+    return "'" + value.replace(/['‘’‚‛]/g, '$&$&') + "'";
+}
+//# sourceMappingURL=registration.js.map

package/dist/lib/hook-engine/resolve.d.ts

@@ -0,0 +1,31 @@
+export declare const HOOK_ENGINE_REPAIR = "npm install -g @indigoai-us/hq-cli --include=optional";
+export declare const HOOK_ENGINE_REPAIR_PIN = "hq core hook-engine-path --repair";
+export interface EngineOptions {
+    home?: string;
+    platform?: string;
+    arch?: string;
+    version?: string;
+    resolvePackage?: (name: string) => string;
+    repair?: boolean;
+}
+export interface EnginePackage {
+    source: string;
+    pinned: string;
+    version: string;
+    sourceDirectory: string;
+    pinnedDirectory: string;
+}
+/** US-020 must set this package capability when the replaced bash hooks retire. */
+export declare function hookEngineRequired(): boolean;
+/** Check the whole signed bundle, including its resource seal and stapled ticket. */
+export declare function pinnedHookEngineMatches(engine: EnginePackage): boolean;
+/** Offline lookup. Never silently use an engine from a different CLI version. */
+export declare function findHookEngine(options?: EngineOptions): EnginePackage | null;
+/** Never truncate or replace a running Windows executable. */
+export declare function installHookEngine(options?: EngineOptions): string | null;
+/** Call only after settings no longer reference these old versions. Windows
+ * refuses unlink of a mapped executable; a busy version stays for a later pass.
+ * POSIX permits unlink while running, so retain those versions conservatively.
+ */
+export declare function pruneHookEngines(current: string, referencedVersions: readonly string[], options?: EngineOptions): string[];
+//# sourceMappingURL=resolve.d.ts.map

package/dist/lib/hook-engine/resolve.js

@@ -0,0 +1,134 @@
+import { createRequire } from 'node:module';
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, rmdirSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const require = createRequire(import.meta.url);
+// Capture metadata while the package-use lease protects this install tree.
+// Resident commands may call doctor after an update removes the old manifest.
+const cliManifest = JSON.parse(readFileSync(new URL('../../../package.json', import.meta.url), 'utf8'));
+export const HOOK_ENGINE_REPAIR = 'npm install -g @indigoai-us/hq-cli --include=optional';
+export const HOOK_ENGINE_REPAIR_PIN = 'hq core hook-engine-path --repair';
+const platforms = new Set(['win32-x64', 'win32-arm64', 'darwin-x64', 'darwin-arm64', 'linux-x64', 'linux-arm64']);
+/** US-020 must set this package capability when the replaced bash hooks retire. */
+export function hookEngineRequired() {
+    return cliManifest.hqHookEngineRequired === true;
+}
+/** Check the whole signed bundle, including its resource seal and stapled ticket. */
+export function pinnedHookEngineMatches(engine) {
+    function equal(source, pinned) {
+        if (!existsSync(pinned))
+            return false;
+        const a = lstatSync(source);
+        const b = lstatSync(pinned);
+        if (a.isSymbolicLink())
+            return b.isSymbolicLink() && readlinkSync(source) === readlinkSync(pinned);
+        if (a.isDirectory()) {
+            if (!b.isDirectory())
+                return false;
+            const names = readdirSync(source).sort();
+            if (JSON.stringify(names) !== JSON.stringify(readdirSync(pinned).sort()))
+                return false;
+            return names.every(name => equal(join(source, name), join(pinned, name)));
+        }
+        return a.isFile() && b.isFile() && readFileSync(source).equals(readFileSync(pinned));
+    }
+    return equal(engine.sourceDirectory, engine.pinnedDirectory);
+}
+/** Offline lookup. Never silently use an engine from a different CLI version. */
+export function findHookEngine(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const key = `${platform}-${options.arch ?? process.arch}`;
+    if (!platforms.has(key))
+        return null;
+    const version = options.version ?? cliManifest.version;
+    if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version))
+        throw new Error('Invalid hook engine version');
+    let manifest;
+    try {
+        manifest = (options.resolvePackage ?? require.resolve)(`@indigoai-us/hq-hook-${key}/package.json`);
+    }
+    catch (error) {
+        if (error.code === 'MODULE_NOT_FOUND')
+            return null;
+        throw error;
+    }
+    const pkg = JSON.parse(readFileSync(manifest, 'utf8'));
+    if (pkg.version !== version)
+        return null;
+    const binary = platform === 'win32' ? 'hq-hook.exe' : platform === 'darwin' ? join('hq-hook.app', 'Contents', 'MacOS', 'hq-hook') : 'hq-hook';
+    const sourceDirectory = join(dirname(manifest), 'bin');
+    const pinnedDirectory = join(options.home ?? homedir(), '.hq', 'bin', 'hq-hook', version);
+    const source = join(sourceDirectory, binary);
+    if (!existsSync(source))
+        return null;
+    return { source, version, sourceDirectory, pinnedDirectory, pinned: join(pinnedDirectory, binary) };
+}
+/** Never truncate or replace a running Windows executable. */
+export function installHookEngine(options = {}) {
+    const engine = findHookEngine(options);
+    if (!engine)
+        return null;
+    if (options.repair && existsSync(engine.pinnedDirectory)) {
+        // Unlink the executable first: Windows refuses this if any process maps it.
+        // Never recursively remove the bundle before that lock check has succeeded.
+        try {
+            unlinkSync(engine.pinned);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw new Error('Close running HQ hook processes before repairing the pinned engine', { cause: error });
+        }
+        rmSync(engine.pinnedDirectory, { recursive: true });
+    }
+    mkdirSync(dirname(engine.pinnedDirectory), { recursive: true });
+    if (!existsSync(engine.pinnedDirectory)) {
+        const stage = mkdtempSync(join(dirname(engine.pinnedDirectory), '.install-'));
+        try {
+            cpSync(engine.sourceDirectory, stage, { recursive: true, errorOnExist: true, force: false });
+            try {
+                renameSync(stage, engine.pinnedDirectory);
+            }
+            catch (error) {
+                if (!existsSync(engine.pinned))
+                    throw error;
+            }
+        }
+        finally {
+            rmSync(stage, { recursive: true, force: true });
+        }
+    }
+    if (!pinnedHookEngineMatches(engine)) {
+        throw new Error(`Hook engine ${engine.version} differs from its pinned copy; close HQ sessions and repair with: ${HOOK_ENGINE_REPAIR_PIN}`);
+    }
+    return engine.pinned;
+}
+/** Call only after settings no longer reference these old versions. Windows
+ * refuses unlink of a mapped executable; a busy version stays for a later pass.
+ * POSIX permits unlink while running, so retain those versions conservatively.
+ */
+export function pruneHookEngines(current, referencedVersions, options = {}) {
+    if ((options.platform ?? process.platform) !== 'win32')
+        return [];
+    const root = join(options.home ?? homedir(), '.hq', 'bin', 'hq-hook');
+    if (!existsSync(root))
+        return [];
+    const removed = [];
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name === current || referencedVersions.includes(entry.name) || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(entry.name))
+            continue;
+        const dir = join(root, entry.name);
+        if (readdirSync(dir).some(name => name !== 'hq-hook.exe'))
+            continue;
+        try {
+            unlinkSync(join(dir, 'hq-hook.exe'));
+            rmdirSync(dir);
+            removed.push(entry.name);
+        }
+        catch (error) {
+            if (!['EPERM', 'EACCES', 'EBUSY', 'ENOENT', 'ENOTEMPTY'].includes(error.code ?? ''))
+                throw error;
+        }
+    }
+    return removed;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/lib/install/claude-targets.d.ts

@@ -1,3 +1,4 @@
+import { type NativeTarget } from '../hook-engine/registration.js';
 /** Name of the HQ MCP server entry in ~/.claude.json. */
 export declare const HQ_MCP_SERVER_NAME = "hq";
 /** `_hqPack` provenance stamped on the HQ MCP server entry. */
@@ -21,7 +22,7 @@ export declare function masterHookPath(hqRoot: string): string;
 /** hqd hook shim (US-010): registered instead of master-hook.sh once hqd is installed. */
 export declare function shimPath(hqRoot: string): string;
 /** Which HQ hook script the user-scope install registers. */
-export type HookTarget = 'master' | 'shim';
+export type HookTarget = 'master' | 'shim' | NativeTarget;
 export declare function charterPath(hqRoot: string): string;
 export declare function hqSkillsSource(hqRoot: string): string;
 /** The exact hook command registered for one event (absolute path, quoted). */

package/dist/lib/install/claude-targets.js

@@ -5,6 +5,7 @@
  * safe-write substrate.
  */
 import * as path from 'path';
+import { engineArgs, isNativeEntry } from '../hook-engine/registration.js';
 /** Events master-hook.sh is registered for at user scope. */
 const GLOBAL_HOOK_EVENTS = [
     'SessionStart',
@@ -98,6 +99,8 @@ export function removeClaudeMdBlock(current) {
 function isHqHookEntry(entry, hqRoot) {
     if (!entry || typeof entry !== 'object')
         return false;
+    if (isNativeEntry(entry, hqRoot))
+        return true;
     const cmd = entry.command;
     if (typeof cmd !== 'string')
         return false;
@@ -111,13 +114,15 @@ export function addHqHooks(doc, hqRoot, target = 'master') {
     const hooks = { ...(doc.hooks ?? {}) };
     let changed = false;
     for (const event of GLOBAL_HOOK_EVENTS) {
-        const want = hookCommand(hqRoot, event, target);
+        const want = typeof target === 'object'
+            ? { type: 'command', command: target.engine, args: engineArgs(hqRoot, event, 'claude', true), timeout: 300 }
+            : { type: 'command', command: hookCommand(hqRoot, event, target), timeout: 300 };
         let groups = Array.isArray(hooks[event]) ? [...hooks[event]] : [];
-        const present = groups.some((g) => Array.isArray(g?.hooks) && g.hooks.some((h) => h.command === want));
+        const present = groups.some((g) => Array.isArray(g?.hooks) && g.hooks.some((h) => h.command === want.command && JSON.stringify(h.args) === JSON.stringify('args' in want ? want.args : undefined)));
         if (present)
             continue;
         groups = removeHqHooks({ hooks: { [event]: groups } }, hqRoot).hooks?.[event] ?? [];
-        groups.push({ hooks: [{ type: 'command', command: want, timeout: 300 }] });
+        groups.push({ hooks: [want] });
         hooks[event] = groups;
         changed = true;
     }

package/dist/lib/install/codex-targets.d.ts

@@ -23,6 +23,9 @@ export declare function addAgentsMdBlock(current: string | null, charter: string
 /** Strip the HQ block, plus the separator `addAgentsMdBlock` put before it. */
 export declare function removeAgentsMdBlock(current: string): string;
 type Doc = Record<string, unknown>;
+export declare function isAdapterEntry(entry: unknown, hqRoot: string): boolean;
+/** The HQ hooks.json entry for one event and target. */
+export declare function codexHookEntry(hqRoot: string, event: string, target?: HookTarget): Record<string, unknown>;
 /**
  * Add one HQ hook group per event; idempotent. An HQ entry for the other
  * target (adapter vs the hqd shim) is swapped out. Foreign hooks are untouched.

package/dist/lib/install/codex-targets.js

@@ -10,6 +10,7 @@
  * module never writes a second adapter.
  */
 import * as fs from 'fs';
+import { engineArgs, isNativeEntry, quotePosix, quoteWindows } from '../hook-engine/registration.js';
 import * as path from 'path';
 import { shimPath } from './claude-targets.js';
 /** Events the Codex hook adapter is registered for at user scope. */
@@ -88,15 +89,25 @@ export function removeAgentsMdBlock(current) {
         start -= 1;
     return current.slice(0, start) + current.slice(end);
 }
-function isAdapterEntry(entry, hqRoot) {
+export function isAdapterEntry(entry, hqRoot) {
     if (!entry || typeof entry !== 'object')
         return false;
+    if (isNativeEntry(entry, hqRoot))
+        return true;
     const cmd = entry.command;
     return (typeof cmd === 'string' &&
         (cmd.includes(JSON.stringify(codexAdapterPath(hqRoot))) ||
             cmd.includes(JSON.stringify(shimPath(hqRoot))) ||
             cmd.includes(JSON.stringify(path.join(hqRoot, 'core', 'packages', 'hq-anywhere', 'hooks', 'codex.sh')))));
 }
+/** The HQ hooks.json entry for one event and target. */
+export function codexHookEntry(hqRoot, event, target = 'master') {
+    const timeout = event === 'SessionEnd' ? 3 : 300;
+    if (typeof target !== 'object')
+        return { type: 'command', command: codexHookCommand(hqRoot, target), timeout };
+    const argv = [target.engine, ...engineArgs(hqRoot, event, 'codex')];
+    return { type: 'command', command: argv.map(quotePosix).join(' '), ...(target.engine.endsWith('.exe') ? { commandWindows: '& ' + argv.map(quoteWindows).join(' ') } : {}), timeout };
+}
 /**
  * Add one HQ hook group per event; idempotent. An HQ entry for the other
  * target (adapter vs the hqd shim) is swapped out. Foreign hooks are untouched.
@@ -104,14 +115,14 @@ function isAdapterEntry(entry, hqRoot) {
 export function addCodexHooks(doc, hqRoot, target = 'master') {
     const hooks = { ...(doc.hooks ?? {}) };
     let changed = false;
-    const want = codexHookCommand(hqRoot, target);
     for (const event of CODEX_HOOK_EVENTS) {
+        const want = codexHookEntry(hqRoot, event, target);
         let groups = Array.isArray(hooks[event]) ? [...hooks[event]] : [];
-        const present = groups.some((g) => Array.isArray(g?.hooks) && g.hooks.some((h) => h.command === want));
+        const present = groups.some((g) => Array.isArray(g?.hooks) && g.hooks.some((h) => h.command === want.command && h.commandWindows === ('commandWindows' in want ? want.commandWindows : undefined)));
         if (present)
             continue;
         groups = removeCodexHooks({ hooks: { [event]: groups } }, hqRoot).hooks?.[event] ?? [];
-        groups.push({ hooks: [{ type: 'command', command: want, timeout: event === 'SessionEnd' ? 3 : 300 }] });
+        groups.push({ hooks: [want] });
         hooks[event] = groups;
         changed = true;
     }

package/dist/lib/install/hook-target.d.ts

@@ -0,0 +1,9 @@
+import { type HookTarget } from './claude-targets.js';
+/** 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;
+//# sourceMappingURL=hook-target.d.ts.map

package/dist/lib/install/hook-target.js

@@ -0,0 +1,39 @@
+/**
+ * Which hook target a user-scope registration uses. Kept apart from
+ * install-global so hq reindex can reconcile registrations without loading the
+ * install command graph.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { realpathOrSelf } from '../../commands/mcp-registration.js';
+import { DAEMON_LAUNCHD_LABEL, DAEMON_SYSTEMD_UNIT, DAEMON_WINDOWS_TASK, SYSTEM_UNIT_DIR } from '../daemon/install.js';
+import { readDaemonConfig } from '../daemon/config.js';
+import { daemonPaths } from '../daemon/paths.js';
+import { registrationEngine } from '../hook-engine/registration.js';
+import { shimPath } from './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 engine = registrationEngine(home, env);
+    if (engine)
+        return { engine };
+    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';
+}
+//# sourceMappingURL=hook-target.js.map

package/dist/lib/lanes/admission-host.d.ts

@@ -13,6 +13,7 @@ export type OutpostIdentity = {
 export declare function readOutpostIdentity(existsSync?: (p: string) => boolean, readFileSync?: (p: string) => string): OutpostIdentity;
 export declare function resolveAdmissionHost(deps?: {
     hostname?: () => string;
+    homedir?: () => string;
     readOutpostIdentity?: () => OutpostIdentity;
     existsSync?: (p: string) => boolean;
     readFileSync?: (p: string) => string;