@indigoai-us/hq-cli 5.345.148 → 5.345.150

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

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/index.d.ts

@@ -20,7 +20,7 @@ export { LANE_STORY_LEDGER_FLAG, buildLaneStatusSnapshot, formatLaneStatusHuman,
 export type { LaneStatusSnapshot, ProjectStoryLedger, StoryLedgerWriteDeps } from "./story-ledger.js";
 export { buildOutpostPickupCommand, parseOutpostPickupPayload, } from "./outpost-dispatch.js";
 export type { OutpostDispatchResult, OutpostPickupPayload, } from "./outpost-dispatch.js";
-export { LANES_STORE_REL, LANE_RECORDS_DIR, PENDING_INDEX_DIR, QUESTION_RECORDS_DIR, appendCappedHistory, appendLaneAttribution, appendLaneSeniorHistory, appendQuestionRouting, createLane, createQuestion, isConflictSidecarName, laneRecordPath, lanesStoreRoot, listLaneIds, listQuestionIds, mergeLaneRecords, mergeQuestionRecords, mintLaneId, mintQuestionId, parseLaneRecord, parseQuestionRecord, pendingMarkerPath, questionRecordPath, readAllLanes, readLane, readQuestion, resolveStoreHqRoot, sanitizeHostComponent, tryReadLane, tryReadQuestion, retryUpdateLane, retryUpdateQuestion, syncLaneRecordFromOwner, updateLane, updateQuestion, withLaneHireLocks, } from "./store.js";
+export { LANES_STORE_REL, LANE_RECORDS_DIR, PENDING_INDEX_DIR, QUESTION_RECORDS_DIR, appendCappedHistory, appendLaneAttribution, appendLaneSeniorHistory, appendQuestionRouting, createLane, createQuestion, isConflictSidecarName, laneRecordPath, lanesStoreRoot, listLaneIds, expandLocalLaneIdPrefix, LANE_ID_PREFIX_MIN, listQuestionIds, mergeLaneRecords, mergeQuestionRecords, mintLaneId, mintQuestionId, parseLaneRecord, parseQuestionRecord, pendingMarkerPath, questionRecordPath, readAllLanes, readLane, readQuestion, resolveStoreHqRoot, sanitizeHostComponent, tryReadLane, tryReadQuestion, retryUpdateLane, retryUpdateQuestion, syncLaneRecordFromOwner, updateLane, updateQuestion, withLaneHireLocks, } from "./store.js";
 export type { StoreDeps } from "./store.js";
 export { DEFAULT_LANE_WATCH_INTERVAL_MS, MAX_LANE_WATCH_INTERVAL_MS, MAX_WATCHED_LANES, MAX_WATCH_OUTPUT_LINES, runLaneWatch, } from "./watch.js";
 export type { LaneWatchDeps, LaneWatchResult } from "./watch.js";

package/dist/lib/lanes/index.js

@@ -12,7 +12,7 @@ export { DEFAULT_ACCOUNT_HOMES, DEFAULT_AUTO_COMPACT_TOKENS, DEFAULT_COMPACT_AFT
 export { resolveLanesHqRoot } from "./hq-root.js";
 export { LANE_STORY_LEDGER_FLAG, buildLaneStatusSnapshot, formatLaneStatusHuman, laneStoryLedgerEnabled, resolveProjectStoryLedger, syncLaneToProjectStoryLedger, removeLaneFromProjectStoryLedger, validateProjectStories, } from "./story-ledger.js";
 export { buildOutpostPickupCommand, parseOutpostPickupPayload, } from "./outpost-dispatch.js";
-export { LANES_STORE_REL, LANE_RECORDS_DIR, PENDING_INDEX_DIR, QUESTION_RECORDS_DIR, appendCappedHistory, appendLaneAttribution, appendLaneSeniorHistory, appendQuestionRouting, createLane, createQuestion, isConflictSidecarName, laneRecordPath, lanesStoreRoot, listLaneIds, listQuestionIds, mergeLaneRecords, mergeQuestionRecords, mintLaneId, mintQuestionId, parseLaneRecord, parseQuestionRecord, pendingMarkerPath, questionRecordPath, readAllLanes, readLane, readQuestion, resolveStoreHqRoot, sanitizeHostComponent, tryReadLane, tryReadQuestion, retryUpdateLane, retryUpdateQuestion, syncLaneRecordFromOwner, updateLane, updateQuestion, withLaneHireLocks, } from "./store.js";
+export { LANES_STORE_REL, LANE_RECORDS_DIR, PENDING_INDEX_DIR, QUESTION_RECORDS_DIR, appendCappedHistory, appendLaneAttribution, appendLaneSeniorHistory, appendQuestionRouting, createLane, createQuestion, isConflictSidecarName, laneRecordPath, lanesStoreRoot, listLaneIds, expandLocalLaneIdPrefix, LANE_ID_PREFIX_MIN, listQuestionIds, mergeLaneRecords, mergeQuestionRecords, mintLaneId, mintQuestionId, parseLaneRecord, parseQuestionRecord, pendingMarkerPath, questionRecordPath, readAllLanes, readLane, readQuestion, resolveStoreHqRoot, sanitizeHostComponent, tryReadLane, tryReadQuestion, retryUpdateLane, retryUpdateQuestion, syncLaneRecordFromOwner, updateLane, updateQuestion, withLaneHireLocks, } from "./store.js";
 export { DEFAULT_LANE_WATCH_INTERVAL_MS, MAX_LANE_WATCH_INTERVAL_MS, MAX_WATCHED_LANES, MAX_WATCH_OUTPUT_LINES, runLaneWatch, } from "./watch.js";
 export { MONITOR_ERROR_EXIT_CODE, MONITOR_ENGINES, MONITOR_MAX_TIMEOUT_MS, MONITOR_TASK_OUTPUT_MAX_BYTES, MONITOR_TRANSCRIPT_MAX_BYTES, MONITOR_UNCOVERED_EXIT_CODE, coveredLaneIds, isMonitorTaskLive, monitorReminderText, parseCanonicalWatchCommand, parseMonitorTranscript, readLiveMonitorEvidence, } from "./monitor.js";
 export { IMDS_HOST, IMDS_INSTANCE_ID_URL, IMDS_TIMEOUT_MS, IMDS_TOKEN_URL, defaultReadImdsInstanceId, resolveMachineIdentity, } from "./machine-identity.js";

package/dist/lib/lanes/store.d.ts

@@ -87,5 +87,16 @@ export declare function createQuestion(hqRoot: string, init: Omit<QuestionRecord
 export declare function updateQuestion(hqRoot: string, questionId: string, expectedVersion: number, updater: (current: QuestionRecord) => QuestionRecord, deps?: StoreDeps): QuestionRecord;
 export declare function appendQuestionRouting(hqRoot: string, questionId: string, expectedVersion: number, entry: RoutingHistoryEntry, deps?: StoreDeps): QuestionRecord;
 export declare function listLaneIds(hqRoot: string, deps?: StoreDeps): string[];
+/** Shortest lane-id prefix a command expands to a full local lane id. */
+export declare const LANE_ID_PREFIX_MIN = 8;
+/**
+ * Expand a short lane-id prefix (at least `LANE_ID_PREFIX_MIN` ULID chars,
+ * no host suffix) to the one local lane id it starts. Returns `undefined`
+ * when the input is not such a prefix or matches no local lane, and throws
+ * `lane_id_ambiguous` listing every candidate when it matches more than one.
+ * Lane records, questions, run dirs and envelopes are always keyed by the
+ * full lane id; a prefix is only ever a lookup convenience.
+ */
+export declare function expandLocalLaneIdPrefix(hqRoot: string, input: string, deps?: StoreDeps): string | undefined;
 export declare function listQuestionIds(hqRoot: string, deps?: StoreDeps): string[];
 //# sourceMappingURL=store.d.ts.map

package/dist/lib/lanes/store.js

@@ -2072,6 +2072,26 @@ function listRecordIds(dir, label, deps) {
 export function listLaneIds(hqRoot, deps = defaultStoreDeps()) {
     return listRecordIds(path.join(lanesStoreRoot(hqRoot), LANE_RECORDS_DIR), "lane", deps);
 }
+/** Shortest lane-id prefix a command expands to a full local lane id. */
+export const LANE_ID_PREFIX_MIN = 8;
+/**
+ * Expand a short lane-id prefix (at least `LANE_ID_PREFIX_MIN` ULID chars,
+ * no host suffix) to the one local lane id it starts. Returns `undefined`
+ * when the input is not such a prefix or matches no local lane, and throws
+ * `lane_id_ambiguous` listing every candidate when it matches more than one.
+ * Lane records, questions, run dirs and envelopes are always keyed by the
+ * full lane id; a prefix is only ever a lookup convenience.
+ */
+export function expandLocalLaneIdPrefix(hqRoot, input, deps = defaultStoreDeps()) {
+    if (!new RegExp(`^[0-9A-HJKMNP-TV-Z]{${LANE_ID_PREFIX_MIN},26}$`, "i").test(input))
+        return undefined;
+    const prefix = input.toUpperCase();
+    const matches = listLaneIds(hqRoot, deps).filter((laneId) => laneId.toUpperCase().startsWith(prefix)).sort();
+    if (matches.length > 1) {
+        throw new LanesError("lane_id_ambiguous", `Lane id prefix ${input} matches ${matches.length} lanes: ${matches.join(", ")}. Pass the full lane id.`, { lane_id: input, matches });
+    }
+    return matches[0];
+}
 export function listQuestionIds(hqRoot, deps = defaultStoreDeps()) {
     return listRecordIds(path.join(lanesStoreRoot(hqRoot), QUESTION_RECORDS_DIR), "question", deps);
 }

package/dist/lib/lanes/watch.js

@@ -1,4 +1,4 @@
-import { listQuestionIds, readLane, readQuestion, } from "./store.js";
+import { expandLocalLaneIdPrefix, listQuestionIds, readLane, readQuestion, } from "./store.js";
 import { LaneNotFoundError, LanesError } from "./errors.js";
 import { providerSupportsSessionResume } from "./delivery.js";
 import { canResumeDoneKeepAliveLane, hasPendingKeepAliveWork, keepAliveNextCheckAtMs, LEAD_LANE_KEEP_ALIVE_MAX_RESUMES, } from "./keep-alive.js";
@@ -62,7 +62,9 @@ function canResumeKeepAliveLane(hqRoot, lane, nowMs = Date.now()) {
     return false;
 }
 export async function runLaneWatch(hqRoot, laneIds, deps = {}) {
-    const watchedIds = validateLaneIds(laneIds);
+    // Watch by full lane id: a short prefix expands only when it names exactly
+    // one local lane, and an ambiguous prefix is refused with its candidates.
+    const watchedIds = [...new Set(validateLaneIds(laneIds).map((laneId) => expandLocalLaneIdPrefix(hqRoot, laneId) ?? laneId))];
     const readLaneRecord = deps.readLane ?? readLane;
     const listQuestions = deps.listQuestionIds ?? listQuestionIds;
     const readQuestionRecord = deps.readQuestion ?? readQuestion;
@@ -130,7 +132,7 @@ export async function runLaneWatch(hqRoot, laneIds, deps = {}) {
             }
             records.push(record);
             if (previousStates.get(laneId) !== record.state) {
-                emit(`lane ${laneId}: state=${record.state}${isTerminalLaneState(record.state) ? " (terminal)" : ""}`);
+                emit(`lane ${record.lane_id}: state=${record.state}${isTerminalLaneState(record.state) ? " (terminal)" : ""}`);
                 previousStates.set(laneId, record.state);
             }
         }

package/dist/lib/windows/console-encoding.d.ts

@@ -0,0 +1,24 @@
+/** ASCII stand-ins for characters cmd.exe cannot show on code page 437. */
+export declare function toAscii(text: string): string;
+/** Parse `chcp` output (`Active code page: 437`). Null when the number is missing. */
+export declare function parseChcpOutput(text: string): number | null;
+type ChcpRun = () => {
+    status: number | null;
+    stdout: string;
+};
+export declare function readConsoleCodePage(run?: ChcpRun): number | null;
+export interface ConsoleEncodingDeps {
+    platform?: NodeJS.Platform;
+    stdout?: NodeJS.WriteStream;
+    stderr?: NodeJS.WriteStream;
+    /** Known code page. Null means the page could not be read and is treated as not UTF-8. */
+    codePage?: number | null;
+    readCodePage?: () => number | null;
+}
+/**
+ * Wrap console stdout and stderr on Windows when the code page is not UTF-8.
+ * Returns false when no wrap was installed.
+ */
+export declare function installWindowsConsoleEncoding(deps?: ConsoleEncodingDeps): boolean;
+export {};
+//# sourceMappingURL=console-encoding.d.ts.map

package/dist/lib/windows/console-encoding.js

@@ -0,0 +1,83 @@
+/**
+ * cmd.exe on a non-UTF-8 code page prints UTF-8 em dashes as mojibake.
+ * When stdout or stderr is a console and the code page is not 65001, string
+ * writes are transliterated to ASCII. Pipes are left as UTF-8 so captured
+ * logs stay intact. Buffer writes are not modified.
+ */
+import { spawnSync } from "node:child_process";
+const WRAP = Symbol.for("hq.windowsConsoleEncoding");
+const REPLACEMENTS = [
+    [/\u2014/g, "--"],
+    [/\u2013/g, "-"],
+    [/\u2018|\u2019|\u201A/g, "'"],
+    [/\u201C|\u201D|\u201E/g, "\""],
+    [/\u2026/g, "..."],
+    [/\u00A0/g, " "],
+    [/\u2022/g, "*"],
+    [/\u2192/g, "->"],
+    [/\u2190/g, "<-"],
+    [/\u21D2/g, "=>"],
+    [/\u00D7/g, "x"],
+];
+/** ASCII stand-ins for characters cmd.exe cannot show on code page 437. */
+export function toAscii(text) {
+    let out = text;
+    for (const [pattern, replacement] of REPLACEMENTS)
+        out = out.replace(pattern, replacement);
+    return out.replace(/[^\t\n\r\x20-\x7E]/g, "?");
+}
+/** Parse `chcp` output (`Active code page: 437`). Null when the number is missing. */
+export function parseChcpOutput(text) {
+    const match = /:\s*(\d+)/.exec(text);
+    if (!match)
+        return null;
+    const codePage = Number(match[1]);
+    return Number.isInteger(codePage) ? codePage : null;
+}
+function defaultChcp() {
+    const result = spawnSync("chcp", [], { encoding: "utf8", windowsHide: true, timeout: 2000 });
+    return { status: result.status, stdout: result.stdout ?? "" };
+}
+export function readConsoleCodePage(run = defaultChcp) {
+    try {
+        const result = run();
+        if (result.status !== 0)
+            return null;
+        return parseChcpOutput(result.stdout);
+    }
+    catch {
+        return null;
+    }
+}
+function wrapStream(stream) {
+    if (stream[WRAP])
+        return;
+    const original = stream.write.bind(stream);
+    stream.write = ((chunk, encoding, cb) => {
+        if (typeof chunk === "string")
+            return original(toAscii(chunk), encoding, cb);
+        return original(chunk, encoding, cb);
+    });
+    stream[WRAP] = true;
+}
+/**
+ * Wrap console stdout and stderr on Windows when the code page is not UTF-8.
+ * Returns false when no wrap was installed.
+ */
+export function installWindowsConsoleEncoding(deps = {}) {
+    if ((deps.platform ?? process.platform) !== "win32")
+        return false;
+    const stdout = (deps.stdout ?? process.stdout);
+    const stderr = (deps.stderr ?? process.stderr);
+    if (!stdout.isTTY && !stderr.isTTY)
+        return false;
+    const codePage = deps.codePage !== undefined ? deps.codePage : (deps.readCodePage ?? readConsoleCodePage)();
+    if (codePage === 65001)
+        return false;
+    if (stdout.isTTY)
+        wrapStream(stdout);
+    if (stderr.isTTY)
+        wrapStream(stderr);
+    return true;
+}
+//# sourceMappingURL=console-encoding.js.map

package/dist/lib/windows/install-followup.d.ts

@@ -0,0 +1,35 @@
+export declare function isInstallFollowupSkipped(argv: readonly string[], env: NodeJS.ProcessEnv): boolean;
+export declare function isInstalledPackageEntry(entry: string | undefined): boolean;
+/**
+ * `version`: the CLI version whose mesh daemon install succeeded.
+ * `path`: the shim folder and CLI version whose PATH step already ran, so a
+ * refused or locked HKCU is not retried on every command.
+ * `meshFailedAt`: when a daemon install for `meshFailedVersion` last failed.
+ * A failure is retried after MESH_RETRY_MS rather than on every command.
+ */
+export interface InstallFollowupMarker {
+    version?: string;
+    path?: {
+        dir: string;
+        version: string;
+    };
+    meshFailedVersion?: string;
+    meshFailedAt?: number;
+}
+/** A failed daemon install blocks for up to 30 s, so it is retried at most hourly. */
+export declare const MESH_RETRY_MS: number;
+export interface InstallFollowupDeps {
+    argv: readonly string[];
+    env?: NodeJS.ProcessEnv;
+    /** The npm shim folder for this entry, or null when hq is not an npm global install. */
+    shimDir?: () => string | null;
+    ensurePath?: () => void;
+    /** True when the daemon install succeeded. */
+    spawnMesh?: () => boolean;
+    version?: string;
+    readMarker?: () => InstallFollowupMarker;
+    writeMarker?: (marker: InstallFollowupMarker) => void;
+    now?: () => number;
+}
+export declare function runWindowsInstallFollowup(deps: InstallFollowupDeps): void;
+//# sourceMappingURL=install-followup.d.ts.map