@indigoai-us/hq-cli 5.345.148 → 5.345.149

package/dist/lib/db/sql.js

@@ -5,7 +5,7 @@
  * resolved company slug from HQ session/flags. Path overrides that open
  * another company's DB are denied unless an explicit dangerous flag is set.
  */
-import Database from "better-sqlite3";
+import { loadBetterSqlite3 } from "./sqlite-binding.js";
 import { openLocalDb } from "./local.js";
 import { normalizeCompanySlugForLocalDb, resolveLocalDbPath, } from "./paths.js";
 const WRITE_PATTERN = /^\s*(INSERT|UPDATE|DELETE|REPLACE|CREATE|DROP|ALTER|TRUNCATE|REINDEX|VACUUM|BEGIN|COMMIT|ROLLBACK)\b/i;
@@ -49,7 +49,7 @@ export function resolveSqlDbPath(opts) {
     return opts.dbPathOverride;
 }
 function openByPath(dbPath) {
-    const db = new Database(dbPath);
+    const db = new (loadBetterSqlite3())(dbPath);
     db.pragma("journal_mode = WAL");
     db.pragma("foreign_keys = ON");
     return db;

package/dist/lib/db/sqlite-binding.d.ts

@@ -0,0 +1,22 @@
+import type BetterSqlite3 from "better-sqlite3";
+import { type SpawnPlan } from "../../utils/windows-spawn.js";
+export type BetterSqlite3Constructor = typeof BetterSqlite3;
+export declare class SqliteBindingError extends Error {
+    constructor(cause?: unknown);
+}
+export interface LoadBetterSqlite3Options {
+    importDatabase?: () => BetterSqlite3Constructor;
+    /** Return true when the native binary is ready to load again. */
+    repair?: () => boolean;
+}
+export declare function resetSqliteBindingForTests(): void;
+export declare function clearBetterSqlite3RequireCache(): void;
+/**
+ * A `.js` bin runs under this Node. A `.cmd` shim goes through the escaped
+ * cmd.exe plan, so a profile path with spaces or `&` stays one argument.
+ */
+export declare function planRepairToolSpawn(cmd: string, args: readonly string[], env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): SpawnPlan;
+/** Download or build better-sqlite3's native binary inside its own package directory. */
+export declare function repairBetterSqlite3(): boolean;
+export declare function loadBetterSqlite3(options?: LoadBetterSqlite3Options): BetterSqlite3Constructor;
+//# sourceMappingURL=sqlite-binding.d.ts.map

package/dist/lib/db/sqlite-binding.js

@@ -0,0 +1,168 @@
+/**
+ * Load better-sqlite3 without requiring the user to approve npm scripts.
+ * npm 11 skips dependency install scripts, so the prebuilt binary is often
+ * missing after `npm install -g`. Try a one-shot prebuild download from the
+ * installed package, then surface the exact allow-scripts command.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { planResolvedCommandSpawn } from "../../utils/windows-spawn.js";
+const require = createRequire(import.meta.url);
+export class SqliteBindingError extends Error {
+    constructor(cause) {
+        super("better-sqlite3 did not load. npm 11.16 and later skip its install script unless scripts are allowed, so the prebuilt binary was not downloaded. " +
+            "HQ tried to download the prebuild and it still failed. " +
+            "Fix: npm install -g @indigoai-us/hq-cli --allow-scripts=better-sqlite3");
+        this.name = "SqliteBindingError";
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+let cached;
+let failed;
+let defaultRepairAttempted = false;
+export function resetSqliteBindingForTests() {
+    cached = undefined;
+    failed = undefined;
+    defaultRepairAttempted = false;
+}
+function isNativeBindingError(error) {
+    const record = error;
+    const text = error instanceof Error ? `${record?.code ?? ""} ${error.message}` : String(error);
+    return /better_sqlite3\.node|could not locate the bindings file|NODE_MODULE_VERSION|was compiled against a different node|not a valid win32 application|dlopen|ERR_DLOPEN_FAILED|MODULE_NOT_FOUND/i.test(text);
+}
+export function clearBetterSqlite3RequireCache() {
+    for (const id of Object.keys(require.cache)) {
+        if (id.includes(`${path.sep}better-sqlite3${path.sep}`))
+            delete require.cache[id];
+    }
+}
+function defaultImport() {
+    return require("better-sqlite3");
+}
+function resolveTool(dir, tool) {
+    const names = process.platform === "win32" ? [`${tool}.cmd`, `${tool}.exe`, tool] : [tool];
+    const bins = [path.join(path.dirname(dir), ".bin"), path.join(dir, "node_modules", ".bin")];
+    for (const bin of bins) {
+        for (const name of names) {
+            const candidate = path.join(bin, name);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+    }
+    try {
+        const localRequire = createRequire(path.join(dir, "package.json"));
+        const pkgJson = localRequire.resolve(`${tool}/package.json`);
+        const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf8"));
+        const rel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.[tool];
+        if (typeof rel === "string")
+            return path.join(path.dirname(pkgJson), rel);
+    }
+    catch {
+        // The tool is not installed next to better-sqlite3.
+    }
+    return null;
+}
+/**
+ * A `.js` bin runs under this Node. A `.cmd` shim goes through the escaped
+ * cmd.exe plan, so a profile path with spaces or `&` stays one argument.
+ */
+export function planRepairToolSpawn(cmd, args, env = process.env, platform = process.platform) {
+    if (cmd.endsWith(".js"))
+        return { cmd: process.execPath, args: [cmd, ...args], shell: false };
+    return planResolvedCommandSpawn(cmd, args, env, platform);
+}
+function runTool(cmd, args, cwd) {
+    const plan = planRepairToolSpawn(cmd, args);
+    spawnSync(plan.cmd, plan.args, {
+        cwd,
+        timeout: 60_000,
+        windowsHide: true,
+        stdio: "ignore",
+        shell: plan.shell,
+        ...(plan.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
+    });
+}
+/** Download or build better-sqlite3's native binary inside its own package directory. */
+export function repairBetterSqlite3() {
+    let dir;
+    try {
+        dir = path.dirname(require.resolve("better-sqlite3/package.json"));
+    }
+    catch {
+        return false;
+    }
+    const artifact = path.join(dir, "build", "Release", "better_sqlite3.node");
+    if (fs.existsSync(artifact))
+        return true;
+    const prebuild = resolveTool(dir, "prebuild-install");
+    if (prebuild)
+        runTool(prebuild, [], dir);
+    if (fs.existsSync(artifact))
+        return true;
+    const nodeGyp = resolveTool(dir, "node-gyp");
+    if (nodeGyp)
+        runTool(nodeGyp, ["rebuild", "--release"], dir);
+    return fs.existsSync(artifact);
+}
+function attemptRepair(options) {
+    if (options.repair) {
+        try {
+            return options.repair();
+        }
+        catch {
+            return false;
+        }
+    }
+    if (defaultRepairAttempted)
+        return false;
+    defaultRepairAttempted = true;
+    try {
+        return repairBetterSqlite3();
+    }
+    catch {
+        return false;
+    }
+}
+export function loadBetterSqlite3(options = {}) {
+    const injected = options.importDatabase !== undefined;
+    if (!injected && cached)
+        return cached;
+    if (!injected && failed)
+        throw failed;
+    const importDatabase = options.importDatabase ?? defaultImport;
+    const load = () => {
+        const ctor = importDatabase();
+        if (!injected)
+            cached = ctor;
+        return ctor;
+    };
+    try {
+        return load();
+    }
+    catch (error) {
+        if (!isNativeBindingError(error))
+            throw error;
+        const repaired = attemptRepair(options);
+        if (!repaired) {
+            const wrapped = new SqliteBindingError(error);
+            if (!injected)
+                failed = wrapped;
+            throw wrapped;
+        }
+        if (!injected)
+            clearBetterSqlite3RequireCache();
+        try {
+            return load();
+        }
+        catch (retryError) {
+            const wrapped = new SqliteBindingError(retryError);
+            if (!injected)
+                failed = wrapped;
+            throw wrapped;
+        }
+    }
+}
+//# sourceMappingURL=sqlite-binding.js.map

package/dist/lib/doctor/checks/anywhere.d.ts

@@ -48,10 +48,22 @@ export interface AnywhereDeps {
     serviceState?: () => DaemonServiceState;
     /** Is an hqd process alive? Default: the daemon lock names a live hqd pid. */
     daemonRunning?: () => boolean;
+    /** Transport to report when health throws. Production uses the platform default. */
+    unreachableTransport?: "windows_named_pipe" | "unix_socket";
     now?: () => Date;
 }
+export interface PipeConnectFailure {
+    code?: string;
+    detail?: string;
+}
 export declare function createAnywhereFamily(deps?: AnywhereDeps): CheckFamily;
 export declare const anywhereFamily: CheckFamily;
+/**
+ * What to say when the Windows named pipe cannot be used. The old wording
+ * guessed an ACL refusal whenever any process looked like a daemon. This
+ * reports the connect error that was actually observed.
+ */
+export declare function windowsNamedPipeUnreachableMessage(socketPath: string, daemonRunning: boolean, failure?: PipeConnectFailure): string;
 export declare function defaultServiceState(home: string, options?: DaemonServiceProbeOptions): DaemonServiceState;
 export {};
 //# sourceMappingURL=anywhere.d.ts.map

package/dist/lib/doctor/checks/anywhere.js

@@ -63,6 +63,7 @@ async function runAnywhereChecks(context, deps = {}) {
         : result(personSetting ? "PASS" : "WARN", "person-setting", `HQ Anywhere person setting is ${personSetting ? "on" : "off"}`);
     let health;
     let healthUnsupported = false;
+    let connectFailure;
     try {
         if (deps.health) {
             health = await deps.health(cwd);
@@ -107,12 +108,14 @@ async function runAnywhereChecks(context, deps = {}) {
                 };
                 healthUnsupported = true;
             }
-            catch {
-                health = unreachableHealth(socketPath);
+            catch (inner) {
+                health = unreachableHealth(socketPath, deps.unreachableTransport);
+                connectFailure = connectFailureFrom(inner);
             }
         }
         else {
-            health = unreachableHealth(socketPath);
+            health = unreachableHealth(socketPath, deps.unreachableTransport);
+            connectFailure = connectFailureFrom(error);
         }
     }
     const claude = claudeTargets(home);
@@ -126,7 +129,7 @@ async function runAnywhereChecks(context, deps = {}) {
     const daemonRunning = health.reachable
         ? true
         : (deps.daemonRunning ?? (() => runningDaemonPid(daemonPaths(home, env).lockPath) !== null))();
-    const healthCheck = runtimeHealthCheck(health, healthUnsupported, serviceState, daemonRunning);
+    const healthCheck = runtimeHealthCheck(health, healthUnsupported, serviceState, daemonRunning, connectFailure);
     if (!runtimeEnabled)
         return [healthCheck, settingCheck];
     const remoteModes = [
@@ -177,17 +180,67 @@ async function runAnywhereChecks(context, deps = {}) {
         out.push(checkSkillLinks("codex", codex.skillsDir, REMEDIATION.installCodex, REMEDIATION.repairCodexSkills));
     return out;
 }
-function unreachableHealth(socketPath) {
+function unreachableHealth(socketPath, transport) {
     return {
         reachable: false,
         version: null,
         uptimeMs: null,
         flag: { enabled: null, lastSuccessfulReadAgeMs: null, heldThroughReadError: false },
         resolution: { scope: "unknown", company: null, fallbackReason: null },
-        socket: { path: socketPath, transport: process.platform === "win32" ? "windows_named_pipe" : "unix_socket", mode: null, ownerMatchesUser: null, userOnly: null },
+        socket: {
+            path: socketPath,
+            transport: transport ?? (process.platform === "win32" ? "windows_named_pipe" : "unix_socket"),
+            mode: null,
+            ownerMatchesUser: null,
+            userOnly: null,
+        },
     };
 }
-function runtimeHealthCheck(health, healthUnsupported = false, serviceState, daemonRunning = true) {
+function connectFailureFrom(error) {
+    if (error instanceof HqdClientError)
+        return { code: error.code, detail: error.message };
+    if (error instanceof Error) {
+        const code = error.code;
+        return { code: typeof code === "string" ? code : undefined, detail: error.message };
+    }
+    return { detail: String(error) };
+}
+function failureSuffix(failure) {
+    if (!failure)
+        return "";
+    const parts = [failure.code, failure.detail].filter((part) => Boolean(part && part.trim()));
+    return parts.length === 0 ? "" : ` (${parts.join(": ")})`;
+}
+function accessDenied(failure) {
+    const code = (failure?.code ?? "").toUpperCase();
+    if (code === "EACCES" || code === "EPERM")
+        return true;
+    return /access is denied|unsafe acl/i.test(failure?.detail ?? "");
+}
+/**
+ * What to say when the Windows named pipe cannot be used. The old wording
+ * guessed an ACL refusal whenever any process looked like a daemon. This
+ * reports the connect error that was actually observed.
+ */
+export function windowsNamedPipeUnreachableMessage(socketPath, daemonRunning, failure) {
+    const suffix = failureSuffix(failure);
+    if (!daemonRunning) {
+        return `hqd is not running, so its named pipe ${socketPath} does not exist${suffix}. Run ${REMEDIATION.daemonStatus} to see why it has not started.`;
+    }
+    if (accessDenied(failure)) {
+        return `hqd is running but access to named pipe ${socketPath} was denied${suffix}. The pipe ACL does not allow this user. Run ${REMEDIATION.daemonRestart} to recreate the pipe.`;
+    }
+    const code = (failure?.code ?? "").toUpperCase();
+    if (code === "ENOENT") {
+        return `hqd is running but named pipe ${socketPath} does not exist${suffix}. Run ${REMEDIATION.daemonRestart} to recreate the pipe.`;
+    }
+    if (code === "ETIMEDOUT") {
+        return `hqd is running but did not answer on named pipe ${socketPath}${suffix}. Run ${REMEDIATION.daemonStatus}, then ${REMEDIATION.daemonRestart}.`;
+    }
+    const observed = suffix || " (observed)";
+    return `hqd is not reachable on ${socketPath}${observed}. HQ did not see an access-denied error, so this is not a named-pipe ACL refusal. Run ${REMEDIATION.daemonStatus} to see why, then ${REMEDIATION.daemonRestart}.`;
+}
+function runtimeHealthCheck(health, healthUnsupported = false, serviceState, daemonRunning = true, failure) {
     const { flag, resolution, socket } = health;
     const age = flag.lastSuccessfulReadAgeMs === null
         ? "unknown"
@@ -204,11 +257,9 @@ function runtimeHealthCheck(health, healthUnsupported = false, serviceState, dae
         ? "Windows named pipe (mode and owner are not reported)"
         : `mode ${socket.mode ?? "unknown"}; owner matches current user: ${socket.ownerMatchesUser === null ? "unknown" : socket.ownerMatchesUser ? "yes" : "no"}; user-only: ${socket.userOnly === null ? "unknown" : socket.userOnly ? "yes" : "no"}`;
     const pipeWithoutDaemon = socket.transport === "windows_named_pipe" && !daemonRunning;
-    const unreachableMessage = pipeWithoutDaemon
-        ? `hqd is not running, so its named pipe ${socket.path} does not exist. Run ${REMEDIATION.daemonStatus} to see why it has not started.`
-        : socket.transport === "windows_named_pipe"
-            ? `hqd is not reachable on ${socket.path}; secure Windows named-pipe setup may have refused an unsafe ACL`
-            : `hqd is not reachable on ${socket.path}; version, uptime, flag state, and cwd binding are unavailable`;
+    const unreachableMessage = socket.transport === "windows_named_pipe"
+        ? windowsNamedPipeUnreachableMessage(socket.path, daemonRunning, failure)
+        : `hqd is not reachable on ${socket.path}; version, uptime, flag state, and cwd binding are unavailable`;
     const socketNotUserOnly = health.reachable && socket.transport === "unix_socket" && (socket.userOnly !== true || socket.ownerMatchesUser !== true);
     const warningNotes = [
         healthUnsupported ? "resident hqd does not support detailed health; restart hqd for full diagnostics" : null,

package/dist/lib/doctor/checks/cli-path.d.ts

@@ -4,7 +4,8 @@ export declare const CLI_PATH_FAMILY_ID = "cli-path";
 export declare const CLI_PATH_CHECK_ID = "cli-path.npm-shim-on-path";
 /**
  * Windows: is the folder holding the npm `hq.cmd` shim on the PATH a new
- * terminal gets? Reads the registry only; never edits PATH.
+ * terminal gets? This check only reads. The CLI adds the folder to HKCU Path
+ * on startup; the warning is the fallback when that add did not stick.
  */
 export declare const cliPathFamily: CheckFamily;
 export declare function checkCliPath(_context: CheckContext, check?: () => ShimPathCheck | null): CheckResult[];

package/dist/lib/doctor/checks/cli-path.js

@@ -3,7 +3,8 @@ export const CLI_PATH_FAMILY_ID = "cli-path";
 export const CLI_PATH_CHECK_ID = "cli-path.npm-shim-on-path";
 /**
  * Windows: is the folder holding the npm `hq.cmd` shim on the PATH a new
- * terminal gets? Reads the registry only; never edits PATH.
+ * terminal gets? This check only reads. The CLI adds the folder to HKCU Path
+ * on startup; the warning is the fallback when that add did not stick.
  */
 export const cliPathFamily = {
     id: CLI_PATH_FAMILY_ID,

package/dist/lib/doctor/checks/hook-engine.js

@@ -1,3 +1,4 @@
+import { launcherEnabled } from '../../hook-engine/registration.js';
 import { findHookEngine, hookEngineRequired, pinnedHookEngineMatches, HOOK_ENGINE_REPAIR, HOOK_ENGINE_REPAIR_PIN } from '../../hook-engine/resolve.js';
 export function checkHookEngine() {
     const required = hookEngineRequired();
@@ -5,7 +6,7 @@ export function checkHookEngine() {
     try {
         const engine = findHookEngine();
         if (engine && pinnedHookEngineMatches(engine))
-            return { checkId: 'hooks.native-engine', status: 'PASS', target: engine.pinned, message: `Native hook engine ${engine.version} installed at its version-pinned path.` };
+            return { checkId: 'hooks.native-engine', status: 'PASS', target: engine.pinned, message: `Native hook engine ${engine.version} installed at its version-pinned path. Launcher flag: ${launcherEnabled() ? 'on (run hq reindex to reconcile settings)' : 'off (bash registration)'}.` };
         return { checkId: 'hooks.native-engine', status: required ? 'FAIL' : 'WARN', message: `Native hook engine is missing or damaged. ${fallback}`, remediation: engine ? `Close HQ sessions, then run ${HOOK_ENGINE_REPAIR_PIN}` : HOOK_ENGINE_REPAIR };
     }
     catch (error) {

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/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;
     }