@indigoai-us/hq-cli 5.345.55 → 5.345.57

package/dist/lib/lanes/hooks-install.d.ts

@@ -6,15 +6,18 @@
  * registers nothing:
  *
  * - grok reads every `*.json` under `$GROK_HOME/hooks/`, so the registration
- *   file in that directory is the registration.
+ *   file in that directory is the registration. Grok passive events cannot
+ *   inject model-facing context or block, so its drain stays on PreToolUse.
  * - claude reads `$CLAUDE_CONFIG_DIR/settings.json` and nothing under
- *   `hooks/`. The registration is merged into the `hooks.PreToolUse` array of
- *   that file.
- * - codex reads `$CODEX_HOME/config.toml` (`[[hooks.PreToolUse]]`, gated by
- *   `[features] hooks = true`). The registration is appended to that file.
+ *   `hooks/`. The registration is merged into PreToolUse, PostToolUse, and
+ *   Stop arrays in that file.
+ * - codex reads `$CODEX_HOME/config.toml` (`[[hooks.<Event>]]`, gated by
+ *   `[features] hooks = true`). The registration is appended for all three
+ *   delivery events.
  *
- * Every registration merge keeps what the operator already has and is a
- * no-op when the entry is present, because this runs on every spawn.
+ * Claude and Codex register all three delivery events. Grok registers only
+ * PreToolUse because its PostToolUse and Stop output cannot reach the model.
+ * Registration merges keep existing operator hooks and are idempotent.
  * Never merges into hq-hq-bridge.json / hq-hq-bridge.sh.
  */
 import type { LaneProvider } from "./types.js";
@@ -40,9 +43,9 @@ export interface DrainHookInstallResult {
     files: string[];
     registration: DrainHookRegistration;
 }
-export declare function drainHookCommand(_shPath?: string): string;
+export declare function drainHookCommand(_shPath?: string, provider?: LaneProvider): string;
 export declare function drainHookShPath(providerHome: string): string;
-export declare function renderDrainHookJson(shPath: string): string;
+export declare function renderDrainHookJson(shPath: string, provider?: LaneProvider): string;
 export interface MergeResult {
     text: string;
     changed: boolean;
@@ -56,9 +59,9 @@ export interface MergeResult {
 export declare function mergeClaudeSettingsHook(existingText: string | null, command: string, settingsPath: string, legacyCommand?: string): MergeResult;
 /**
  * Codex: hooks come from `config.toml` in the codex home. The drain is
- * appended as one `[[hooks.PreToolUse]]` table and `[features] hooks = true`
+ * appended to PreToolUse, PostToolUse, and Stop, and `[features] hooks = true`
  * is ensured. Edits are textual so comments and unrelated tables are kept
- * byte for byte; the result is re-parsed and must contain the registration,
+ * byte for byte; the result is re-parsed and must contain every registration,
  * otherwise nothing is written.
  */
 export declare function mergeCodexConfigHook(existingText: string | null, command: string, configPath: string, legacyCommand?: string): MergeResult;

package/dist/lib/lanes/hooks-install.js

@@ -6,15 +6,18 @@
  * registers nothing:
  *
  * - grok reads every `*.json` under `$GROK_HOME/hooks/`, so the registration
- *   file in that directory is the registration.
+ *   file in that directory is the registration. Grok passive events cannot
+ *   inject model-facing context or block, so its drain stays on PreToolUse.
  * - claude reads `$CLAUDE_CONFIG_DIR/settings.json` and nothing under
- *   `hooks/`. The registration is merged into the `hooks.PreToolUse` array of
- *   that file.
- * - codex reads `$CODEX_HOME/config.toml` (`[[hooks.PreToolUse]]`, gated by
- *   `[features] hooks = true`). The registration is appended to that file.
+ *   `hooks/`. The registration is merged into PreToolUse, PostToolUse, and
+ *   Stop arrays in that file.
+ * - codex reads `$CODEX_HOME/config.toml` (`[[hooks.<Event>]]`, gated by
+ *   `[features] hooks = true`). The registration is appended for all three
+ *   delivery events.
  *
- * Every registration merge keeps what the operator already has and is a
- * no-op when the entry is present, because this runs on every spawn.
+ * Claude and Codex register all three delivery events. Grok registers only
+ * PreToolUse because its PostToolUse and Stop output cannot reach the model.
+ * Registration merges keep existing operator hooks and are idempotent.
  * Never merges into hq-hq-bridge.json / hq-hq-bridge.sh.
  */
 import * as fs from "node:fs";
@@ -44,8 +47,9 @@ export const PROVIDER_REGISTRATION_KIND = {
     codex: "config_toml",
     grok: "hooks_dir",
 };
-export function drainHookCommand(_shPath) {
-    return `${shellQuote(process.execPath)} ${shellQuote(drainHookEntryPath())}`;
+export function drainHookCommand(_shPath, provider) {
+    const providerEnv = provider === "grok" ? "HQ_LANE_PROVIDER=grok " : "";
+    return `${providerEnv}${shellQuote(process.execPath)} ${shellQuote(drainHookEntryPath())}`;
 }
 function legacyDrainHookCommand(shPath) {
     return `bash ${shPath}`;
@@ -148,7 +152,10 @@ function isInstalledDrainEntry(entryPath) {
 function drainCommandsMatch(candidate, expected) {
     if (candidate === expected)
         return true;
-    const argv = parseShellQuotedArguments(candidate);
+    const withoutProviderEnv = candidate.startsWith("HQ_LANE_PROVIDER=grok ")
+        ? candidate.slice("HQ_LANE_PROVIDER=grok ".length)
+        : candidate;
+    const argv = parseShellQuotedArguments(withoutProviderEnv);
     if (argv === null || argv.length !== 2)
         return false;
     if (path.parse(argv[0]).name.toLowerCase() !== "node")
@@ -170,7 +177,9 @@ function groupsContainDrainCommand(groups, expected) {
     });
 }
 function tomlHasDrainCommand(parsed, expected) {
-    return isPlainObject(parsed.hooks) && groupsContainDrainCommand(parsed.hooks.PreToolUse, expected);
+    const hooks = isPlainObject(parsed.hooks) ? parsed.hooks : null;
+    return hooks !== null &&
+        ["PreToolUse", "PostToolUse", "Stop"].every((event) => groupsContainDrainCommand(hooks[event], expected));
 }
 function removeCommandFromGroups(groups, command) {
     let changed = false;
@@ -187,22 +196,14 @@ function removeCommandFromGroups(groups, command) {
     });
     return { groups: next, changed };
 }
-export function renderDrainHookJson(shPath) {
-    return `${JSON.stringify({
-        hooks: {
-            PreToolUse: [
-                {
-                    hooks: [
-                        {
-                            type: "command",
-                            command: drainHookCommand(shPath),
-                            timeout: DRAIN_HOOK_TIMEOUT_SECONDS,
-                        },
-                    ],
-                },
-            ],
-        },
-    }, null, 2)}\n`;
+export function renderDrainHookJson(shPath, provider = "grok") {
+    const command = drainHookCommand(shPath, provider);
+    const registration = {
+        hooks: Object.fromEntries(["PreToolUse"].map((event) => [event, [
+                { hooks: [{ type: "command", command, timeout: DRAIN_HOOK_TIMEOUT_SECONDS }] },
+            ]])),
+    };
+    return `${JSON.stringify(registration, null, 2)}\n`;
 }
 /**
  * Claude Code: `settings.json` is the one file it reads hooks from. Merge the
@@ -227,27 +228,35 @@ export function mergeClaudeSettingsHook(existingText, command, settingsPath, leg
     if (!isPlainObject(hooks)) {
         throw new LanesError("settings_unparseable", `${settingsPath} has a non-object "hooks" key; refusing to rewrite it`, { path: settingsPath });
     }
-    const pre = hooks.PreToolUse === undefined ? [] : hooks.PreToolUse;
+    const events = ["PreToolUse", "PostToolUse", "Stop"];
+    const eventGroups = new Map();
+    for (const event of events) {
+        const groups = hooks[event] === undefined ? [] : hooks[event];
+        if (!Array.isArray(groups)) {
+            throw new LanesError("settings_unparseable", `${settingsPath} has a non-array "hooks.${event}"; refusing to rewrite it`, { path: settingsPath });
+        }
+        eventGroups.set(event, groups);
+    }
+    const pre = eventGroups.get("PreToolUse");
     if (!Array.isArray(pre)) {
         throw new LanesError("settings_unparseable", `${settingsPath} has a non-array "hooks.PreToolUse"; refusing to rewrite it`, { path: settingsPath });
     }
     const migration = legacyCommand && legacyCommand !== command
         ? removeCommandFromGroups(pre, legacyCommand)
         : { groups: pre, changed: false };
-    if (groupsContainCommand(migration.groups, command) && !migration.changed) {
+    const allRegistered = events.every((event) => groupsContainCommand(eventGroups.get(event), command));
+    if (allRegistered && !migration.changed) {
         return { text: existingText ?? "", changed: false };
     }
-    const nextPre = groupsContainCommand(migration.groups, command)
-        ? migration.groups
-        : [
-            ...migration.groups,
-            {
-                hooks: [
-                    { type: "command", command, timeout: DRAIN_HOOK_TIMEOUT_SECONDS },
-                ],
-            },
+    const nextHooks = { ...hooks };
+    for (const event of events) {
+        const groups = event === "PreToolUse" ? migration.groups : eventGroups.get(event);
+        nextHooks[event] = groupsContainCommand(groups, command) ? groups : [
+            ...groups,
+            { hooks: [{ type: "command", command, timeout: DRAIN_HOOK_TIMEOUT_SECONDS }] },
         ];
-    const nextRoot = { ...root, hooks: { ...hooks, PreToolUse: nextPre } };
+    }
+    const nextRoot = { ...root, hooks: nextHooks };
     return { text: `${JSON.stringify(nextRoot, null, 2)}\n`, changed: true };
 }
 function tomlBasicString(value) {
@@ -424,9 +433,9 @@ function enableTomlHooksFeature(text) {
 }
 /**
  * Codex: hooks come from `config.toml` in the codex home. The drain is
- * appended as one `[[hooks.PreToolUse]]` table and `[features] hooks = true`
+ * appended to PreToolUse, PostToolUse, and Stop, and `[features] hooks = true`
  * is ensured. Edits are textual so comments and unrelated tables are kept
- * byte for byte; the result is re-parsed and must contain the registration,
+ * byte for byte; the result is re-parsed and must contain every registration,
  * otherwise nothing is written.
  */
 export function mergeCodexConfigHook(existingText, command, configPath, legacyCommand) {
@@ -435,7 +444,8 @@ export function mergeCodexConfigHook(existingText, command, configPath, legacyCo
     const migration = removeLegacyCodexHook(original, parsed, legacyCommand, configPath);
     const textAfterMigration = migration.text;
     const current = parseTomlOrThrow(textAfterMigration, configPath, "after legacy hook removal");
-    const hasCommand = tomlHasCommand(current, command);
+    const hasPreToolCommand = tomlHasCommand(current, command);
+    const hasCommand = tomlHasDrainCommand(current, command);
     const featureOn = tomlHooksFeatureEnabled(current);
     if (hasCommand && featureOn && !migration.changed) {
         return { text: original, changed: false };
@@ -443,7 +453,7 @@ export function mergeCodexConfigHook(existingText, command, configPath, legacyCo
     let text = textAfterMigration;
     if (!featureOn)
         text = enableTomlHooksFeature(text);
-    if (!hasCommand) {
+    if (!hasPreToolCommand) {
         const sep = text === "" || text.endsWith("\n") ? "" : "\n";
         text =
             `${text}${sep}\n` +
@@ -455,8 +465,18 @@ export function mergeCodexConfigHook(existingText, command, configPath, legacyCo
                 `command = ${tomlBasicString(command)}\n` +
                 `timeout = ${DRAIN_HOOK_TIMEOUT_SECONDS}\n`;
     }
+    for (const event of ["PostToolUse", "Stop"]) {
+        if (isPlainObject(current.hooks) && groupsContainCommand(current.hooks[event], command))
+            continue;
+        const sep = text === "" || text.endsWith("\n") ? "" : "\n";
+        text += `${sep}\n# hq lanes: drop-box delivery\n[[hooks.${event}]]\nmatcher = ".*"\n\n[[hooks.${event}.hooks]]\ntype = "command"\ncommand = ${tomlBasicString(command)}\ntimeout = ${DRAIN_HOOK_TIMEOUT_SECONDS}\n`;
+    }
     const check = parseTomlOrThrow(text, configPath, "after merge");
-    if (!tomlHasCommand(check, command) || !tomlHooksFeatureEnabled(check)) {
+    if (!tomlHasCommand(check, command) ||
+        !isPlainObject(check.hooks) ||
+        !groupsContainCommand(check.hooks.PostToolUse, command) ||
+        !groupsContainCommand(check.hooks.Stop, command) ||
+        !tomlHooksFeatureEnabled(check)) {
         throw new LanesError("config_toml_merge_failed", `Merged ${configPath} does not carry the drain registration; refusing to write it`, { path: configPath, command });
     }
     return { text, changed: true };
@@ -479,7 +499,7 @@ export function probeDrainHookRegistration(provider, providerHome) {
     const parsed = parseLaneProvider(provider);
     const kind = PROVIDER_REGISTRATION_KIND[parsed];
     const regPath = drainHookRegistrationPath(parsed, providerHome);
-    const command = drainHookCommand(drainHookShPath(providerHome));
+    const command = drainHookCommand(drainHookShPath(providerHome), parsed);
     const text = readTextIfExists(regPath);
     const base = { kind, path: regPath, command, file_present: text !== null };
     if (text === null)
@@ -493,11 +513,11 @@ export function probeDrainHookRegistration(provider, providerHome) {
             };
         }
         const json = JSON.parse(text);
+        const hooks = isPlainObject(json) && isPlainObject(json.hooks) ? json.hooks : null;
         return {
             ...base,
-            registered: isPlainObject(json) &&
-                isPlainObject(json.hooks) &&
-                groupsContainDrainCommand(json.hooks.PreToolUse, command),
+            registered: hooks !== null &&
+                (parsed === "grok" ? ["PreToolUse"] : ["PreToolUse", "PostToolUse", "Stop"]).every((event) => groupsContainDrainCommand(hooks[event], command)),
         };
     }
     catch (err) {
@@ -508,9 +528,9 @@ export function probeDrainHookRegistration(provider, providerHome) {
 function registerDrainHook(provider, providerHome, shPath) {
     const kind = PROVIDER_REGISTRATION_KIND[provider];
     const regPath = drainHookRegistrationPath(provider, providerHome);
-    const command = drainHookCommand(shPath);
+    const command = drainHookCommand(shPath, provider);
     if (kind === "hooks_dir") {
-        const changed = writeIfChanged(regPath, renderDrainHookJson(shPath), 0o644);
+        const changed = writeIfChanged(regPath, renderDrainHookJson(shPath, provider), 0o644);
         return { kind, path: regPath, command, changed };
     }
     const existing = readTextIfExists(regPath);

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

@@ -0,0 +1,158 @@
+import type { LaneRecord, LaneProvider } from "./types.js";
+export declare const LOOP_SCHEMA: "hq-lane-loop.v1";
+export declare const PHASE_ENVELOPE_SCHEMA: "hq-phase-envelope/v1";
+export declare const PHASE_HANDOFF_SCHEMA: "hq-phase-handoff/v1";
+export declare const LOOP_ENVELOPE_LIMIT: number;
+export type GenericPhaseEnvelope = {
+    schema_version?: string;
+    id?: string;
+    kind: "phase" | "stop";
+    story_id?: string;
+    phase?: string;
+    engine?: LaneProvider;
+    prompt?: string;
+    result_path?: string;
+    deadline_seconds?: number;
+    deadline?: string;
+    fresh?: boolean;
+    [key: string]: unknown;
+};
+export type Section8PhaseEnvelope = {
+    schema: typeof PHASE_ENVELOPE_SCHEMA;
+    id?: string;
+    story_id: string;
+    phase: string;
+    engine?: LaneProvider;
+    worktree: string;
+    fresh_call?: boolean;
+    result_path?: string;
+    deadline_seconds?: number;
+    deadline?: string;
+    [key: string]: unknown;
+};
+export type LoopEnvelope = GenericPhaseEnvelope | Section8PhaseEnvelope;
+export interface LoopQueuePosition {
+    lane_id: string;
+    envelope_id: string;
+    position: number;
+    queue_depth: number;
+    queued_at: string;
+}
+export interface LoopStatus {
+    mode: "loop";
+    lane_id: string;
+    state: "waiting" | "running" | "parked" | "stopped" | "failed";
+    queue_depth: number;
+    active_envelope_id: string | null;
+    active_phase: string | null;
+    stall_counts: Record<string, number>;
+    pid?: number;
+    updated_at: string;
+}
+export interface LoopResult {
+    schema_version: typeof LOOP_SCHEMA;
+    envelope_id: string;
+    status: "done" | "failed" | "stalled" | "stopped";
+    started_at: string;
+    finished_at: string;
+    output?: string;
+    error?: string;
+    session_id?: string;
+    resumed?: boolean;
+    fresh_fallback?: boolean;
+}
+export interface Section8Handoff {
+    schema: typeof PHASE_HANDOFF_SCHEMA;
+    story_id: string;
+    phase: string;
+    worker_id: string;
+    status: "passed" | "failed" | "blocked";
+    summary: string;
+    files_changed: string[];
+    commits: string[];
+    back_pressure: {
+        tests: "pass" | "fail" | "skip";
+        lint: "pass" | "fail" | "skip";
+        typecheck: "pass" | "fail" | "skip";
+        build: "pass" | "fail" | "skip";
+    };
+    context_for_next: string;
+    engine?: string;
+    notes?: string;
+    [key: string]: unknown;
+}
+export interface LoopExecutionContext {
+    lane: LaneRecord;
+    envelope: LoopEnvelope;
+    envelopeId: string;
+    signal: AbortSignal;
+    sessionId?: string;
+    fresh: boolean;
+}
+export interface LoopExecutionResult {
+    output: string;
+    sessionId?: string;
+}
+export interface LoopRunnerOptions {
+    lane: LaneRecord;
+    runDir: string;
+    execute(context: LoopExecutionContext): Promise<LoopExecutionResult>;
+    canResume?(provider: LaneProvider): boolean;
+    raiseQuestion?(input: {
+        envelope: LoopEnvelope;
+        envelopeId: string;
+        attempt: number;
+        error: string;
+    }): Promise<void> | void;
+    defaultDeadlineSeconds?: number;
+    now?: () => Date;
+    idlePollMs?: number;
+    signal?: AbortSignal;
+}
+export interface LoopRunSummary {
+    state: "stopped" | "parked" | "aborted";
+    completed: number;
+}
+export type LoopAdmissionPath = "initial" | "deferred" | "resume";
+export declare function loopAdmissionPath(state: string, hasPendingResume: boolean, initialAdmission: boolean): LoopAdmissionPath;
+interface StoredEnvelope {
+    schema_version: typeof LOOP_SCHEMA;
+    envelope_id: string;
+    queued_at: string;
+    deadline_budget_seconds?: number;
+    deadline_at_ms?: number;
+    envelope: LoopEnvelope;
+}
+/** Validate both hq-cli phase envelopes and the conduct protocol §8 shape. */
+export declare function validateLoopEnvelope(value: unknown): LoopEnvelope;
+export declare function validateSection8Handoff(value: unknown, envelope: Section8PhaseEnvelope): Section8Handoff;
+/** Queue depth and FIFO ordering are based on the timestamp-prefixed filename. */
+export declare function listLoopQueue(runDir: string): StoredEnvelope[];
+/**
+ * Copy and enqueue atomically. Unique timestamp/ULID-like names establish FIFO;
+ * temporary files are ignored by claimers until rename completes.
+ */
+export declare function enqueueLoopEnvelope(input: {
+    runDir: string;
+    laneId: string;
+    envelope: unknown;
+    now?: () => Date;
+}): LoopQueuePosition;
+/** Atomically claims exactly the FIFO head. The active rename is the claim. */
+export declare function claimNextLoopEnvelope(runDir: string): {
+    file: string;
+    record: StoredEnvelope;
+} | null;
+/** Withdraw all unclaimed envelopes; active work remains claimed by the worker. */
+export declare function interruptLoopQueue(runDir: string): {
+    withdrawn: string[];
+    already_picked_up: string[];
+};
+export declare function loopStatus(runDir: string, laneId: string): LoopStatus;
+export declare function setLoopControllerPid(runDir: string, laneId: string, pid: number | undefined): void;
+export declare function clearLoopControllerPid(runDir: string, laneId: string, pid: number): void;
+export declare function loopControllerIsAlive(runDir: string): boolean;
+/** Run queued phases serially. Sessions are isolated by story and provider. */
+export declare function runLoopLane(options: LoopRunnerOptions): Promise<LoopRunSummary>;
+export {};
+//# sourceMappingURL=loop.d.ts.map