@mnemonik/shared 7.153.0 → 7.154.0

package/dist/hookTimeouts.js

@@ -1,3 +1,4 @@
+import diagnosticsChannel from 'node:diagnostics_channel';
 /**
  * Hook dispatcher HTTP timeout budgets + AbortSignal helper.
  *
@@ -96,47 +97,59 @@ export function withHookTimeout(ms) {
     return { signal: ac.signal, cleanup: () => clearTimeout(timer) };
 }
 /**
- * One second attempt on the main hook call (POST /api/v1/hooks/injections).
+ * The main hook call (POST /api/v1/hooks/injections) is hedged: when the first
+ * request has not answered by HOOK_HEDGE_SHARE of the budget, a second request
+ * starts beside it on a fresh connection, and whichever answers first is used.
  *
- * Why it exists: on 24 October 2026 about a third of one machine's hook calls
- * were lost for 50 minutes to a stall between Cloudflare and one load-balancer
- * node. The server had accepted those requests and was waiting for a body that
- * never finished arriving. A second request opens a new connection and
- * normally lands on a healthy path. The call is idempotent by design (the
- * injection bus dedups on the server), so repeating it is safe.
+ * Why a second request at all: on 24 October 2026 about a third of one
+ * machine's hook calls were lost for 50 minutes to a stall between Cloudflare
+ * and one load-balancer node. The server had accepted those requests and was
+ * waiting for a body that never finished arriving. A second request opens a new
+ * connection and normally lands on a healthy path.
  *
- * Shape: the whole call, both attempts included, still ends inside `budgetMs`,
- * so the budget every hook event is checked against (tests/HookEventBudgets
- * .test.ts) and the host's kill limit do not move. The first attempt gets
- * HOOK_FIRST_ATTEMPT_SHARE of the budget; the second gets whatever is left.
- * A first attempt that fails fast leaves the second nearly the whole budget.
+ * Why it is a hedge and not a retry: v7.149.0 abandoned the first request at
+ * 65% of the budget and then retried. Every hook process opens its own
+ * connection (DNS, TCP and TLS from the user's machine to Cloudflare), and the
+ * credential is read before the request leaves, so on 25 October that first
+ * request had often been on the wire for only a few hundred milliseconds when
+ * it was abandoned. Answers that were merely slow were thrown away, half the
+ * calls on the owner's machine needed two requests, about 8% lost both, and the
+ * load balancer counted each abandoned request as a client close (ELB 460). A
+ * hedge never abandons an answer that is on its way: the first request keeps
+ * running to the end of the budget.
  *
- * What is retried: a timeout, a connection error, and the gateway statuses
- * that mean the request never reached the application (408, 502, 503, 504 and
- * Cloudflare's 52x). Nothing else is: a 4xx or a 500 repeats exactly, and a
- * response that arrives is final.
+ * Both requests share one deadline, `budgetMs` from the call, so the budget
+ * every hook event is checked against (tests/HookEventBudgets.test.ts) and the
+ * host's kill limit do not move. A first request that fails fast (a connection
+ * error or a gateway status) starts the second at once instead of at the hedge
+ * point.
  *
- * Nothing is queued or stored on the client. A call that fails twice is dropped,
- * as before. The server keeps an answer for 15 s so the second attempt can have
- * it when the first attempt gave up on an answer that was already decided.
+ * What counts as an answer: any response other than a gateway status (408, 502,
+ * 503, 504, Cloudflare's 52x) and other than the server's "the first request is
+ * still working" reply (HOOK_REPLAY_HEADER: pending). A 4xx or a 500 is an
+ * answer (null to the caller): repeating it would repeat the failure.
+ *
+ * The server de-duplicates the two requests by HOOK_REQUEST_ID_HEADER
+ * (src/server/hookReplay.ts): the second request is handed the first one's
+ * answer, or waits for it, and nothing is counted twice. Nothing is queued or
+ * stored on the client; a call with no answer by the deadline is dropped.
  */
-export const HOOK_FIRST_ATTEMPT_SHARE = 0.65;
-/** Below this much budget left, a second attempt cannot complete a round trip. */
+export const HOOK_HEDGE_SHARE = 0.65;
+/** Below this much budget left, a second request cannot complete a round trip. */
 export const HOOK_SECOND_ATTEMPT_MIN_MS = 300;
-/** Sent on every attempt so the server can count how many calls needed a second one. */
+/** Sent on every request: 1 for the first, 2 for the hedge. */
 export const HOOK_ATTEMPT_HEADER = 'x-mnemonik-hook-attempt';
 /**
- * Sent on both attempts with the same value. The server keeps the first
- * attempt's answer for a few seconds under this id and hands it to the second
- * attempt, so an answer decided after the first attempt gave up is delivered
- * rather than lost, and nothing is counted twice (src/server/hookReplay.ts).
+ * Sent on both requests with the same value. The server keeps the first
+ * request's answer for a few seconds under this id and hands it to the second,
+ * so an answer decided by one request is delivered through either, and nothing
+ * is counted twice (src/server/hookReplay.ts).
  */
 export const HOOK_REQUEST_ID_HEADER = 'x-mnemonik-hook-request-id';
 /**
- * Sent on every attempt: how many milliseconds this attempt may still take.
- * The server never waits for a first attempt's answer longer than this less a
- * margin for the return trip, so it does not hold a request for a client that
- * has already given up.
+ * Sent on every request: how many milliseconds the caller will still wait. The
+ * server fits its own work inside this less the return trip, so it never
+ * decides an answer the client will not be there to receive.
  */
 export const HOOK_BUDGET_HEADER = 'x-mnemonik-hook-budget-ms';
 /**
@@ -149,10 +162,61 @@ export const HOOK_BUDGET_HEADER = 'x-mnemonik-hook-budget-ms';
 export const HOOK_VERSION_HEADER = 'x-mnemonik-hook-version';
 /** `init` with the hook-version header added; the caller's headers are kept. */
 export function withHookVersion(init, runtime, version) {
-    const headers = new Headers(init.headers);
+    const raw = init.headers;
+    if (raw && typeof raw === 'object' && !(raw instanceof Headers) && !Array.isArray(raw)) {
+        // A plain record is copied with its property descriptors, not its values:
+        // the hedged hook client's budget header is a getter read when the
+        // request is sent, after the credential is read (hedgedHookRequest).
+        const headers = Object.defineProperties({}, Object.getOwnPropertyDescriptors(raw));
+        for (const name of Object.keys(headers)) {
+            if (name.toLowerCase() === HOOK_VERSION_HEADER)
+                delete headers[name];
+        }
+        headers[HOOK_VERSION_HEADER] = `${runtime}/${version}`;
+        return { ...init, headers };
+    }
+    const headers = new Headers(raw);
     headers.set(HOOK_VERSION_HEADER, `${runtime}/${version}`);
     return { ...init, headers: Object.fromEntries(headers.entries()) };
 }
+/**
+ * Sent on every request by a hedging client (hedgedHookRequest). Its budget
+ * header is what the whole call still has; clients v7.149 to v7.151 sent the
+ * first attempt's own 1.3 s cut-off instead, so a server that sees no marker
+ * assumes the whole-call 2 s budget rather than trusting that header.
+ */
+export const HOOK_HEDGED_HEADER = 'x-mnemonik-hook-hedged';
+/**
+ * Sent on the second request only: what had become of the first when the second
+ * left. `pending; sent=812` (still waiting, its body finished sending 812 ms
+ * earlier), `pending; sent=none` (it had not finished sending, so the client
+ * itself was slow), `gateway; sent=<ms>` (the edge answered 502/503/504/52x) or
+ * `transport; sent=<ms>` (the connection failed). The server uses it to count
+ * requests the network lost on the way in, which is what the edge alarm reads
+ * (src/server/hookReplay.ts, hookEdgeMetrics.ts).
+ */
+export const HOOK_FIRST_ATTEMPT_HEADER = 'x-mnemonik-hook-first-attempt';
+/**
+ * Set by the server on a reply that is not an answer: the request found the
+ * other request of the same call still working on it and could not wait any
+ * longer. The client keeps waiting for the other request.
+ */
+export const HOOK_REPLAY_HEADER = 'x-mnemonik-hook-replay';
+export const HOOK_REPLAY_PENDING = 'pending';
+export function formatHookFirstAttempt(first) {
+    return `${first.state}; sent=${first.sentAgoMs === null ? 'none' : Math.max(0, Math.round(first.sentAgoMs))}`;
+}
+export function parseHookFirstAttempt(value) {
+    if (typeof value !== 'string')
+        return null;
+    const match = /^(pending|gateway|transport); sent=(none|\d{1,6})$/.exec(value.trim());
+    if (!match)
+        return null;
+    return {
+        state: match[1],
+        sentAgoMs: match[2] === 'none' ? null : Number(match[2]),
+    };
+}
 /** Statuses that mean the request did not reach, or was not served by, the application. */
 export function isRetryableHookStatus(status) {
     return (status === 408 ||
@@ -174,36 +238,158 @@ export function isTransientHookFetchError(error) {
         (error.message === 'fetch failed' || error.message === 'terminated'));
 }
 /**
- * Run `attempt` and, when it ends in a transient failure, run it once more
- * inside the rest of `budgetMs`. Returns the value of the attempt that
- * finished, or null when neither did. `attempt` returns `{ done: false }` for
- * a retryable response and throws for a transport failure; anything else it
- * returns is final.
+ * When the first request finished sending its body, read from Node's fetch
+ * (undici) diagnostics channels. Matched by the request id header, so other
+ * requests the process makes at the same time are ignored. Reports null when
+ * the channels are unavailable or the body never finished sending; nothing
+ * depends on it except the HOOK_FIRST_ATTEMPT_HEADER the server counts.
  */
-export async function withSecondAttempt(budgetMs, attempt, clock = Date.now) {
-    const startedAt = clock();
-    const requestId = globalThis.crypto.randomUUID();
-    const run = async (attemptNumber, timeoutMs) => {
-        const { signal, cleanup } = withHookTimeout(timeoutMs);
-        try {
-            return await attempt(signal, attemptNumber, requestId, timeoutMs);
-        }
-        catch (error) {
-            if (!isTransientHookFetchError(error))
-                throw error;
-            return { done: false };
-        }
-        finally {
-            cleanup();
+function watchFirstRequestSent(requestId, clock) {
+    let sentAt = null;
+    let request = null;
+    const onCreate = (message) => {
+        const candidate = message?.request;
+        if (request || !candidate)
+            return;
+        if (String(candidate.headers ?? '').includes(requestId))
+            request = candidate;
+    };
+    const onBodySent = (message) => {
+        if (sentAt === null && request && message?.request === request) {
+            sentAt = clock();
         }
     };
-    const first = await run(1, Math.floor(budgetMs * HOOK_FIRST_ATTEMPT_SHARE));
-    if (first.done)
-        return first.value;
-    const remainingMs = budgetMs - (clock() - startedAt);
-    if (remainingMs < HOOK_SECOND_ATTEMPT_MIN_MS)
-        return null;
-    const second = await run(2, Math.floor(remainingMs));
-    return second.done ? second.value : null;
+    try {
+        diagnosticsChannel.subscribe('undici:request:create', onCreate);
+        diagnosticsChannel.subscribe('undici:request:bodySent', onBodySent);
+    }
+    catch {
+        return { sentAt: () => null, stop: () => undefined };
+    }
+    return {
+        sentAt: () => sentAt,
+        stop: () => {
+            try {
+                diagnosticsChannel.unsubscribe('undici:request:create', onCreate);
+                diagnosticsChannel.unsubscribe('undici:request:bodySent', onBodySent);
+            }
+            catch {
+                // Nothing to undo.
+            }
+        },
+    };
+}
+/**
+ * Send one hook call as up to two hedged requests inside `budgetMs` (see
+ * HOOK_HEDGE_SHARE). `send` performs one request with the headers and signal it
+ * is given; `parse` reads an answer. Returns the first answer, null when no
+ * request answered in time or the answer was an error status, and rejects only
+ * when `send` or `parse` fails in a way that is not a transport failure.
+ */
+export function hedgedHookRequest(budgetMs, send, parse, clock = Date.now) {
+    const startedAt = clock();
+    const deadline = startedAt + budgetMs;
+    const requestId = globalThis.crypto.randomUUID();
+    const sent = watchFirstRequestSent(requestId, clock);
+    const controllers = [];
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let running = 0;
+        let secondStarted = false;
+        let firstFailure = null;
+        let hedgeTimer;
+        const finish = (value, error, winner) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(deadlineTimer);
+            clearTimeout(hedgeTimer);
+            sent.stop();
+            // Cancel whatever is still in flight; the request that answered is done.
+            for (const controller of controllers)
+                if (controller !== winner)
+                    controller.abort();
+            if (error !== undefined)
+                reject(error);
+            else
+                resolve(value);
+        };
+        const deadlineTimer = setTimeout(() => finish(null), budgetMs);
+        const startSecond = () => {
+            if (settled || secondStarted)
+                return secondStarted;
+            if (deadline - clock() < HOOK_SECOND_ATTEMPT_MIN_MS)
+                return false;
+            secondStarted = true;
+            clearTimeout(hedgeTimer);
+            launch(2);
+            return true;
+        };
+        const launch = (attemptNumber) => {
+            const controller = new AbortController();
+            controllers.push(controller);
+            const now = clock();
+            const headers = {
+                [HOOK_ATTEMPT_HEADER]: String(attemptNumber),
+                [HOOK_REQUEST_ID_HEADER]: requestId,
+                [HOOK_HEDGED_HEADER]: '1',
+            };
+            // Read when the request is actually built (after the credential read or
+            // rotation and the conversation lock), not when the attempt starts, so
+            // the server's deadline does not include time already spent here.
+            Object.defineProperty(headers, HOOK_BUDGET_HEADER, {
+                enumerable: true,
+                get: () => String(Math.max(0, Math.floor(deadline - clock()))),
+            });
+            if (attemptNumber === 2) {
+                const sentAt = sent.sentAt();
+                headers[HOOK_FIRST_ATTEMPT_HEADER] = formatHookFirstAttempt({
+                    state: firstFailure ?? 'pending',
+                    sentAgoMs: sentAt === null ? null : now - sentAt,
+                });
+            }
+            running += 1;
+            void (async () => {
+                let outcome;
+                try {
+                    const response = await send(headers, controller.signal);
+                    if (isRetryableHookStatus(response.status))
+                        outcome = { final: false, kind: 'gateway' };
+                    else if (response.headers.get(HOOK_REPLAY_HEADER) === HOOK_REPLAY_PENDING)
+                        outcome = { final: false, kind: 'pending' };
+                    else if (!response.ok)
+                        outcome = { final: true, value: null };
+                    else
+                        outcome = { final: true, value: await parse(response) };
+                }
+                catch (error) {
+                    if (!settled && !isTransientHookFetchError(error)) {
+                        running -= 1;
+                        finish(null, error);
+                        return;
+                    }
+                    outcome = { final: false, kind: 'transport' };
+                }
+                running -= 1;
+                if (settled)
+                    return;
+                if (outcome.final) {
+                    finish(outcome.value, undefined, controller);
+                    return;
+                }
+                // Not an answer. The first request's failure starts the second at once;
+                // with no request left running there is no answer to wait for.
+                if (attemptNumber === 1) {
+                    if (outcome.kind !== 'pending')
+                        firstFailure = outcome.kind;
+                    startSecond();
+                }
+                if (running === 0)
+                    finish(null);
+            })();
+        };
+        launch(1);
+        hedgeTimer = setTimeout(startSecond, Math.floor(budgetMs * HOOK_HEDGE_SHARE));
+    });
 }
 //# sourceMappingURL=hookTimeouts.js.map

package/dist/hookTimeouts.js.map

@@ -1 +1 @@
-{"version":3,"file":"hookTimeouts.js","sourceRoot":"","sources":["../src/hookTimeouts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hookTimeouts.js","sourceRoot":"","sources":["../src/hookTimeouts.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemonik/shared",
-  "version": "7.153.0",
+  "version": "7.154.0",
   "description": "Shared constants and utilities for Mnemonik packages",
   "repository": {
     "type": "git",
@@ -45,7 +45,7 @@
     }
   },
   "scripts": {
-    "test": "tsx --test --test-concurrency=2 tests/repositoryFingerprint.test.ts tests/projectIdentity.test.ts tests/nearestProjectIdentity.test.ts tests/readiness.test.ts tests/scannerDisclosure.test.ts tests/hookRuntime.test.ts tests/grantHost.test.ts tests/hookTrace.test.ts",
+    "test": "tsx --test --test-concurrency=2 tests/repositoryFingerprint.test.ts tests/projectIdentity.test.ts tests/nearestProjectIdentity.test.ts tests/readiness.test.ts tests/scannerDisclosure.test.ts tests/hookRuntime.test.ts tests/grantHost.test.ts tests/hookTrace.test.ts tests/gateOutbox.test.ts",
     "build": "node ../../node_modules/@typescript/native/bin/tsc",
     "typecheck": "node ../../node_modules/@typescript/native/bin/tsc --noEmit -p tsconfig.test.json",
     "prepublishOnly": "npm run build"

package/src/gateOutbox.ts

@@ -0,0 +1,181 @@
+/**
+ * Gate telemetry rides the next injections request instead of its own.
+ *
+ * Why: every PreToolUse a hook gated used to end with an awaited POST
+ * /api/v1/hooks/gate-fired, a whole extra round trip (about 220 ms from New
+ * Zealand to us-east-1) after the decision was already made, because the host
+ * waits for the hook process to exit. Measured on 26 October 2026 it was about
+ * 30% of a PreToolUse hook's process time on an idle machine, and one in three
+ * hook requests the server received. The event is telemetry: who gated what,
+ * how, and the action observation for credit capture. Nothing on the agent's
+ * path waits for it.
+ *
+ * So the hook writes the event to a small per-session folder (synchronous, no
+ * network) and the next injections request of the same session claims the
+ * events and carries them as `gateEvents`; the server records them exactly as
+ * the gate-fired route does. A request that gets no answer puts its events
+ * back for the next one; each event carries an id the server records once, so
+ * a request that was recorded but whose answer was lost does not count twice.
+ * Events still queued when a session goes idle for GATE_OUTBOX_MAX_AGE_MS are
+ * dropped, and the folder holds at most GATE_OUTBOX_CAP events (the oldest
+ * go first), so a server that stays unreachable cannot grow it without
+ * bound. Temporary and claimed files a killed hook process left behind are
+ * swept after GATE_OUTBOX_STRAY_MS. Never throws.
+ *
+ * One file per event, written to a temporary name and renamed into the folder,
+ * and claimed by renaming it again: a reader never sees half an event, two
+ * hook processes never claim the same one, and a writer racing a reader never
+ * loses its event.
+ */
+
+import { randomUUID } from 'node:crypto';
+import {
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+/** The per-session folder name (pass it to the host's session state path helper). */
+export const GATE_OUTBOX_FILE = 'gate-outbox';
+
+/** The most events one request carries; the server accepts the same. */
+export const GATE_OUTBOX_MAX_EVENTS = 32;
+
+/** Events older than this are dropped rather than reported: the session went idle. */
+export const GATE_OUTBOX_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+/** The most events the folder holds; past it the oldest are dropped. */
+export const GATE_OUTBOX_CAP = 500;
+
+/**
+ * A temporary or claimed file older than this belongs to a hook process that
+ * was killed between two renames (a live one holds it for milliseconds).
+ */
+export const GATE_OUTBOX_STRAY_MS = 10 * 60 * 1000;
+
+export interface QueuedGateEvent {
+  /** Unique per event; the server records each id once. */
+  id: string;
+  tool: string;
+  mode: string;
+  outcome: string;
+  /** Epoch ms when the gate fired; the server stores it as the event's time. */
+  at: number;
+  host?: string;
+  cwd?: string;
+  projectId?: string;
+  projectRoot?: string;
+  actionObservation?: unknown;
+}
+
+function write(folder: string, event: QueuedGateEvent): void {
+  mkdirSync(folder, { recursive: true, mode: 0o700 });
+  const name = `${String(event.at).padStart(15, '0')}-${event.id}.json`;
+  const temporary = join(folder, `.${name}.tmp`);
+  writeFileSync(temporary, JSON.stringify(event), { mode: 0o600 });
+  renameSync(temporary, join(folder, name));
+}
+
+const unlinkQuietly = (path: string): void => {
+  try {
+    unlinkSync(path);
+  } catch {
+    // Already gone.
+  }
+};
+
+/** Event file names, oldest first (names start with the zero-padded time). */
+function queuedNames(folder: string): string[] {
+  return readdirSync(folder)
+    .filter((name) => name.endsWith('.json') && !name.startsWith('.'))
+    .sort();
+}
+
+/** Drop the oldest events past GATE_OUTBOX_CAP. */
+function enforceCap(folder: string): void {
+  try {
+    const names = queuedNames(folder);
+    for (const name of names.slice(0, Math.max(0, names.length - GATE_OUTBOX_CAP)))
+      unlinkQuietly(join(folder, name));
+  } catch {
+    // Telemetry.
+  }
+}
+
+export function queueGateEvent(folder: string, event: Omit<QueuedGateEvent, 'id'>): boolean {
+  try {
+    write(folder, { ...event, id: randomUUID() });
+    enforceCap(folder);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Claim every queued event of this session, oldest first, at most
+ * GATE_OUTBOX_MAX_EVENTS (the rest wait for the next request).
+ */
+export function takeGateEvents(folder: string, now: number = Date.now()): QueuedGateEvent[] {
+  let entries: string[];
+  try {
+    entries = readdirSync(folder);
+  } catch {
+    return [];
+  }
+  // Sweep what killed hook processes left between renames.
+  for (const name of entries) {
+    if (!name.startsWith('.') || !(name.endsWith('.tmp') || name.endsWith('.claimed'))) continue;
+    const path = join(folder, name);
+    try {
+      if (now - statSync(path).mtimeMs > GATE_OUTBOX_STRAY_MS) unlinkQuietly(path);
+    } catch {
+      // Gone meanwhile.
+    }
+  }
+  const names = entries.filter((name) => name.endsWith('.json') && !name.startsWith('.')).sort();
+  const events: QueuedGateEvent[] = [];
+  for (const name of names) {
+    if (events.length >= GATE_OUTBOX_MAX_EVENTS) break;
+    const claimed = join(folder, `.${name}.${process.pid}.claimed`);
+    try {
+      renameSync(join(folder, name), claimed);
+    } catch {
+      continue; // Another hook process of this session took it.
+    }
+    try {
+      const event = JSON.parse(readFileSync(claimed, 'utf8')) as QueuedGateEvent;
+      if (
+        typeof event?.id === 'string' &&
+        typeof event.tool === 'string' &&
+        typeof event.mode === 'string' &&
+        typeof event.outcome === 'string' &&
+        typeof event.at === 'number' &&
+        now - event.at <= GATE_OUTBOX_MAX_AGE_MS
+      )
+        events.push(event);
+    } catch {
+      // Unreadable; dropped.
+    } finally {
+      unlinkQuietly(claimed);
+    }
+  }
+  return events;
+}
+
+/** Put back events a request could not deliver, so the next request carries them. */
+export function returnGateEvents(folder: string, events: readonly QueuedGateEvent[]): void {
+  for (const event of events) {
+    try {
+      write(folder, event);
+    } catch {
+      // Lost; telemetry.
+    }
+  }
+  enforceCap(folder);
+}

package/src/hookConversation.ts

@@ -3,6 +3,7 @@ import { constants } from 'node:fs';
 import { lstat, mkdir, open, rename, rm, utimes } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { withFileLock } from './settingsIo.js';
+import { HOOK_REQUEST_ID_HEADER } from './hookTimeouts.js';
 import { ensureWindowsPrivateDirectorySync } from './runtimeSigners.js';
 
 type HookFetchInit = NonNullable<Parameters<typeof fetch>[1]>;
@@ -27,6 +28,15 @@ function boundedHandle(value: unknown): value is string {
 
 export class HookConversation {
   private conversationId?: string;
+  /**
+   * The hook call (x-mnemonik-hook-request-id) whose acquiring request holds
+   * the conversation lock in this process. Its hedged second request
+   * (hedgedHookRequest) is the same call: waiting for the lock would hold it
+   * until the first request finished, which is exactly what the hedge exists
+   * to route around. The server hands both requests the same answer, so the
+   * second may save the handle without the lock.
+   */
+  private lockHeldFor?: string;
   private readonly scope: string;
   constructor(private readonly input: HookConversationInput) {
     this.scope = createHash('sha256')
@@ -185,7 +195,20 @@ export class HookConversation {
       } else if (this.conversationId) await this.save(this.conversationId);
       return response;
     };
-    const response = acquisition ? await this.locked(send) : await send();
+    const callId = hookCallId(init.headers);
+    let response: Response;
+    if (!acquisition || (callId !== undefined && this.lockHeldFor === callId)) {
+      response = await send();
+    } else {
+      response = await this.locked(async () => {
+        this.lockHeldFor = callId;
+        try {
+          return await send();
+        } finally {
+          if (this.lockHeldFor === callId) this.lockHeldFor = undefined;
+        }
+      });
+    }
     // The server refused the cached handle (a signing-secret rotation, say).
     // Forget it so the next acquiring event mints a fresh one; this request
     // is never resent, and a handle another event acquired meanwhile stays.
@@ -263,6 +286,14 @@ export function conversationMarker(): string | undefined {
 export async function adoptHookConversation(result: unknown): Promise<void> {
   await active?.adopt(result);
 }
+function hookCallId(headers: HookFetchInit['headers']): string | undefined {
+  try {
+    return new Headers(headers).get(HOOK_REQUEST_ID_HEADER) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export function withHookConversation(
   url: string,
   init: HookFetchInit,

package/src/hookRuntime.ts

@@ -295,3 +295,4 @@ export * from './projectSetupHandoff.js';
 
 export * from './hookConversation.js';
 export * from './hookTrace.js';
+export * from './gateOutbox.js';