fix(permission): bind ask to its denial, expire open, consume once

Ask names its denial via grant_request_id; unnamed keeps
first-pending. Expiry yields a fresh gate round that mints a fresh
envelope. Precheck-to-consume serializes per fingerprint.

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -103,7 +103,7 @@ The interactive TUI may offer an explicit alternate-provider/model selector only
 
 ### Worker permission grants
 
-A worker deny-on-ask registers a harness-owned denied-call envelope (`src/permission/worker-grant.ts`): the exact denied ToolCall plus a stable path-aware fingerprint, keyed by worker session with a single-parent-turn expiry. The deny reason names only the envelope's requestId; the worker's `ask_director` prose carries no authority and plain `send_input` text can never mint, consume, or extend an envelope. The parent observes the envelope on the ask record, replays the exact call through its own gate operator path, and retries the retained worker via the existing `resume_agent` with exact args plus the questionId ref. The first covering-grant retry consumes the envelope; replays, tampered args/cwd/tool/session, expiry, decline, or interrupt fail closed with a truthful blocker. There is no dedicated grant verb — single-use and exactness are enforced by the envelope sidecar, not by tool plumbing.
+A worker deny-on-ask registers a harness-owned denied-call envelope (`src/permission/worker-grant.ts`): the exact denied ToolCall plus a stable path-aware fingerprint, keyed by worker session with a ten-minute wall-clock TTL. The `turnId` on the envelope is metadata only — no turn enforcement exists, so expiry is purely `expiresAt`-driven. The deny reason names only the envelope's requestId; the worker's `ask_director` prose carries no authority and plain `send_input` text can never mint, consume, or extend an envelope. The worker quotes that requestId back as `grant_request_id`, binding the ask to its own denial at register time; an unnamed ask keeps the legacy first-pending bind. The parent observes the envelope on the ask record via the session-store subscription, replays the exact call through its own gate operator path, and retries the retained worker via the existing `resume_agent` with exact args plus the questionId ref. The first covering-grant retry consumes the envelope; replays, tampered args/cwd/tool/session, decline, or interrupt fail closed with a truthful blocker. Expiry deliberately does not fail closed: the lapsed envelope is marked, skipped, and the retry falls through to a fresh gate round that denies fresh with a new grant id, so a lapsed window can never strand the worker. Expiry is lazy — every pendency read sweeps overdue envelopes, and no periodic scheduler exists by decision, not omission. Concurrent identical retries serialize on a per-fingerprint mutex across the precheck-to-consume gap, so one envelope allows exactly once. There is no dedicated grant verb — single-use and exactness are enforced by the envelope sidecar, not by tool plumbing. Phase 2 (by design, not here): a broad parent session grant can cover more than the exact denied subject; binding the grant to the envelope args needs the atomic grant-and-retry verb.
 
 ### TUI Runner (`src/tui/runner/`)
 

src/permission/reactor-authorize.ts

@@ -23,6 +23,7 @@ import type { AuthorizeVerdict, GateVerdict, PermissionGate } from "./gate.js";
 import type { PermissionRequest } from "./types.js";
 import {
   createDeniedCallEnvelope,
+  fingerprintDeniedCall,
   formatWorkerDenyWithGrantId,
   getProcessWorkerGrantStore,
   type WorkerDeniedCallEnvelope,
@@ -171,6 +172,17 @@ function denyWorkerCallWithEnvelope(
   };
 }
 
+/** Mutex key covering the envelope match: concurrent identical worker calls
+ * serialize through precheck-to-consume so one envelope allows exactly once. */
+function workerGrantKey(
+  sessionId: string,
+  call: ToolCallType,
+  cwd: string,
+): string {
+  const identity = workerCallIdentity(sessionId, call, cwd);
+  return `${sessionId}\n${fingerprintDeniedCall(identity.canonicalTool, identity.args, identity.cwd)}`;
+}
+
 async function authorizeWorkerCall(
   gate: PermissionGate,
   call: ToolCallType,
@@ -180,18 +192,36 @@ async function authorizeWorkerCall(
   if (isWorkerControlPlaneTool(call.name)) return { effect: "allow" };
   const workerCwd = resolveWorkerCwd(cwd);
   const sessionId = resolveWorkerSessionId(grantOptions?.sessionId);
-  if (sessionId !== undefined) {
-    const store = grantOptions?.store ?? getProcessWorkerGrantStore();
-    const precheck = store.precheck(
-      workerCallIdentity(sessionId, call, workerCwd),
+  if (sessionId === undefined)
+    return authorizeWorkerCallInner(gate, call, grantOptions, workerCwd);
+  const store = grantOptions?.store ?? getProcessWorkerGrantStore();
+  return store.runExclusive(workerGrantKey(sessionId, call, workerCwd), () =>
+    authorizeWorkerCallInner(gate, call, grantOptions, workerCwd, {
+      sessionId,
+      store,
+    }),
+  );
+}
+
+async function authorizeWorkerCallInner(
+  gate: PermissionGate,
+  call: ToolCallType,
+  grantOptions: WorkerGrantOptions | undefined,
+  workerCwd: string,
+  grant?: { sessionId: string; store: WorkerGrantStore },
+): Promise<{ effect: "allow" } | { effect: "deny"; reason: string }> {
+  if (grant !== undefined) {
+    const precheck = grant.store.precheck(
+      workerCallIdentity(grant.sessionId, call, workerCwd),
     );
     if (!precheck.ok) return { effect: "deny", reason: precheck.blocker };
   }
   const verdict = await gate.authorizeCall(call);
   if (verdict.effect === "allow") {
-    if (sessionId !== undefined) {
-      const store = grantOptions?.store ?? getProcessWorkerGrantStore();
-      store.consumeOnAllow(workerCallIdentity(sessionId, call, workerCwd));
+    if (grant !== undefined) {
+      grant.store.consumeOnAllow(
+        workerCallIdentity(grant.sessionId, call, workerCwd),
+      );
     }
     return verdict;
   }
@@ -224,18 +254,36 @@ async function executionVerdictWorkerCall(
   if (isWorkerControlPlaneTool(call.name)) return { effect: "allow" };
   const workerCwd = resolveWorkerCwd(cwd);
   const sessionId = resolveWorkerSessionId(grantOptions?.sessionId);
-  if (sessionId !== undefined) {
-    const store = grantOptions?.store ?? getProcessWorkerGrantStore();
-    const precheck = store.precheck(
-      workerCallIdentity(sessionId, call, workerCwd),
+  if (sessionId === undefined)
+    return executionVerdictWorkerCallInner(gate, call, grantOptions, workerCwd);
+  const store = grantOptions?.store ?? getProcessWorkerGrantStore();
+  return store.runExclusive(workerGrantKey(sessionId, call, workerCwd), () =>
+    executionVerdictWorkerCallInner(gate, call, grantOptions, workerCwd, {
+      sessionId,
+      store,
+    }),
+  );
+}
+
+async function executionVerdictWorkerCallInner(
+  gate: PermissionGate,
+  call: ToolCallType,
+  grantOptions: WorkerGrantOptions | undefined,
+  workerCwd: string,
+  grant?: { sessionId: string; store: WorkerGrantStore },
+): Promise<AuthorizeVerdict> {
+  if (grant !== undefined) {
+    const precheck = grant.store.precheck(
+      workerCallIdentity(grant.sessionId, call, workerCwd),
     );
     if (!precheck.ok) return { effect: "deny", reason: precheck.blocker };
   }
   const verdict = await gate.executionVerdict(call);
   if (verdict.effect === "allow") {
-    if (sessionId !== undefined) {
-      const store = grantOptions?.store ?? getProcessWorkerGrantStore();
-      store.consumeOnAllow(workerCallIdentity(sessionId, call, workerCwd));
+    if (grant !== undefined) {
+      grant.store.consumeOnAllow(
+        workerCallIdentity(grant.sessionId, call, workerCwd),
+      );
     }
     return verdict;
   }

src/permission/worker-grant-flow.test.ts

@@ -6,6 +6,7 @@ import type { ToolCall } from "@intx/types/runtime";
 import { createPermissionGate } from "./gate.js";
 import { workerPermissionGate } from "./reactor-authorize.js";
 import {
+  WORKER_GRANT_TTL_MS,
   WorkerGrantStore,
   createDeniedCallEnvelope,
   getProcessWorkerGrantStore,
@@ -206,4 +207,70 @@ describe("worker grant-request flow: deny → parent replay grant → one retry"
     expect(store.peek(envelope.requestId)?.status).toBe("pending");
     store.expireSession(session.id, "test teardown");
   });
+
+  test("concurrent identical retries allow exactly once", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "worker-grant-race-"));
+    const parentGate = makeParentGate(cwd, true);
+    const store = new WorkerGrantStore();
+    const workerGate = workerPermissionGate(parentGate, {
+      sessionId: "worker-race",
+      store,
+    });
+
+    const denied = await workerGate.authorizeCall(shellCall("c1", COMMAND));
+    if (denied.effect !== "deny") throw new Error("expected worker deny");
+    const requestId = extractRequestId(denied.reason);
+    expect(await parentGate.evaluate(shellCall("parent-1", COMMAND))).toEqual({
+      allowed: true,
+    });
+
+    // Two in-flight copies of the exact call (fresh call ids, same args):
+    // without serialization both pass precheck before either consumes and
+    // the envelope allows twice.
+    const [retryA, retryB] = await Promise.all([
+      workerGate.authorizeCall(shellCall("c2", COMMAND)),
+      workerGate.authorizeCall(shellCall("c3", COMMAND)),
+    ]);
+    const effects = [retryA.effect, retryB.effect].sort();
+    expect(effects).toEqual(["allow", "deny"]);
+    const loser = retryA.effect === "deny" ? retryA : retryB;
+    if (loser.effect !== "deny") throw new Error("expected replay deny");
+    expect(loser.reason).toContain("already consumed");
+    expect(loser.reason).toContain(requestId);
+    expect(store.peek(requestId)?.status).toBe("consumed");
+  });
+
+  test("post-expiry retry round mints a fresh envelope, then succeeds", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "worker-grant-reissue-"));
+    const parentGate = makeParentGate(cwd, true);
+    const store = new WorkerGrantStore();
+    const workerGate = workerPermissionGate(parentGate, {
+      sessionId: "worker-reissue",
+      store,
+    });
+
+    const denied = await workerGate.authorizeCall(shellCall("c1", COMMAND));
+    if (denied.effect !== "deny") throw new Error("expected worker deny");
+    const lapsedId = extractRequestId(denied.reason);
+    expect(store.sweepExpired(Date.now() + WORKER_GRANT_TTL_MS + 1)).toBe(1);
+    expect(store.peek(lapsedId)?.status).toBe("expired");
+
+    // The lapsed window is not a blackhole: the retry falls through to the
+    // gate, which denies fresh with a NEW grant id the worker can ask out of.
+    const reissue = await workerGate.authorizeCall(shellCall("c2", COMMAND));
+    expect(reissue.effect).toBe("deny");
+    if (reissue.effect !== "deny") throw new Error("expected re-issue deny");
+    const freshId = extractRequestId(reissue.reason);
+    expect(freshId).not.toBe(lapsedId);
+    expect(store.peek(freshId)?.status).toBe("pending");
+    expect(store.peek(lapsedId)?.status).toBe("expired");
+
+    expect(await parentGate.evaluate(shellCall("parent-1", COMMAND))).toEqual({
+      allowed: true,
+    });
+    expect(await workerGate.authorizeCall(shellCall("c3", COMMAND))).toEqual({
+      effect: "allow",
+    });
+    expect(store.peek(freshId)?.status).toBe("consumed");
+  });
 });

src/permission/worker-grant.test.ts

@@ -196,21 +196,27 @@ describe("WorkerGrantStore lifecycle", () => {
     expect(result.blocker).toContain("worker-1");
   });
 
-  test("expiry fails closed, lazily and via sweep", () => {
+  test("expiry yields a fresh gate round, never a blackhole", () => {
     const store = new WorkerGrantStore();
     const envelope = store.register(createDeniedCallEnvelope(descriptor()));
     const after = envelope.expiresAt + 1;
-    const result = store.precheck({
-      sessionId: "worker-1",
-      canonicalTool: "run_shell",
-      args: { ...ARGS },
-      cwd: CWD,
-      now: after,
-    });
-    expect(result.ok).toBe(false);
-    if (result.ok) throw new Error("expected blocker");
-    expect(result.blocker).toContain("expired");
+    // The lapsed window passes through instead of denying: the retry falls to
+    // the gate, which denies fresh and mints a fresh envelope the worker can
+    // ask out of.
+    expect(
+      store.precheck({
+        sessionId: "worker-1",
+        canonicalTool: "run_shell",
+        args: { ...ARGS },
+        cwd: CWD,
+        now: after,
+      }),
+    ).toEqual({ ok: true });
     expect(envelope.status).toBe("expired");
+    expect(envelope.audit.map((event) => event.event)).toEqual([
+      "denied",
+      "expired",
+    ]);
 
     const second = store.register(
       createDeniedCallEnvelope(descriptor({ callId: "call-2" })),
@@ -219,6 +225,53 @@ describe("WorkerGrantStore lifecycle", () => {
     expect(second.status).toBe("expired");
   });
 
+  test("post-expiry re-issue mints a fresh envelope for the same exact call", () => {
+    const store = new WorkerGrantStore();
+    const first = store.register(createDeniedCallEnvelope(descriptor()));
+    const after = first.expiresAt + 1;
+    expect(store.sweepExpired(after)).toBe(1);
+    expect(first.status).toBe("expired");
+    // The retry round denies fresh: a new envelope with a new grant id.
+    const reissue = store.register(
+      createDeniedCallEnvelope(
+        descriptor({ callId: "call-2", now: after + 1_000 }),
+      ),
+    );
+    expect(reissue.requestId).not.toBe(first.requestId);
+    expect(reissue.status).toBe("pending");
+    const identity = {
+      sessionId: "worker-1",
+      canonicalTool: "run_shell",
+      args: { ...ARGS },
+      cwd: CWD,
+      now: after + 1_001,
+    };
+    expect(store.precheck(identity)).toEqual({ ok: true });
+    expect(store.consumeOnAllow(identity)?.requestId).toBe(reissue.requestId);
+    expect(reissue.status).toBe("consumed");
+    expect(first.status).toBe("expired");
+  });
+
+  test("read sites never surface an expired denial without an explicit sweep", () => {
+    const store = new WorkerGrantStore();
+    const envelope = store.register(createDeniedCallEnvelope(descriptor()));
+    const after = envelope.expiresAt + 1;
+    // No sweepExpired call here: each read enforces the TTL itself.
+    expect(
+      store.pendingMatch("worker-1", "run_shell", { ...ARGS }, CWD, after),
+    ).toBeUndefined();
+    expect(
+      store.attachToAsk("worker-1", "ask-late", undefined, after),
+    ).toBeUndefined();
+    expect(store.pendingForSession("worker-1", after)).toBeUndefined();
+    expect(envelope.status).toBe("expired");
+    expect(envelope.audit.map((event) => event.event)).toEqual([
+      "denied",
+      "expired",
+    ]);
+    expect(envelope.questionId).toBeUndefined();
+  });
+
   test("decline fails closed; headless declineAllForSession covers the session", () => {
     const store = new WorkerGrantStore();
     const envelope = store.register(createDeniedCallEnvelope(descriptor()));
@@ -258,11 +311,17 @@ describe("WorkerGrantStore lifecycle", () => {
   test("attachToAsk stamps the questionId and keeps pending", () => {
     const store = new WorkerGrantStore();
     const envelope = store.register(createDeniedCallEnvelope(descriptor()));
-    expect(store.attachToAsk("worker-1", "ask-7")).toBe(envelope);
+    // Reads pin the envelope's clock: the fixture now (1_000_000) predates
+    // wall time, so an unpinned read would sweep it as expired.
+    expect(store.attachToAsk("worker-1", "ask-7", undefined, 1_000_001)).toBe(
+      envelope,
+    );
     expect(envelope.questionId).toBe("ask-7");
     expect(envelope.status).toBe("pending");
     expect(store.byQuestion("ask-7")).toBe(envelope);
-    expect(store.attachToAsk("worker-9", "ask-8")).toBeUndefined();
+    expect(
+      store.attachToAsk("worker-9", "ask-8", undefined, 1_000_001),
+    ).toBeUndefined();
     expect(envelope.audit.map((event) => event.event)).toEqual([
       "denied",
       "asked",
@@ -272,7 +331,7 @@ describe("WorkerGrantStore lifecycle", () => {
   test("audit trail orders deny → ask → consume", () => {
     const store = new WorkerGrantStore();
     const envelope = store.register(createDeniedCallEnvelope(descriptor()));
-    store.attachToAsk("worker-1", "ask-1");
+    store.attachToAsk("worker-1", "ask-1", undefined, 1_000_001);
     store.consumeOnAllow({
       sessionId: "worker-1",
       canonicalTool: "run_shell",
@@ -315,10 +374,68 @@ describe("buildRetryMessage", () => {
   test("carries exact args + questionId ref from the envelope", () => {
     const store = new WorkerGrantStore();
     const envelope = store.register(createDeniedCallEnvelope(descriptor()));
-    store.attachToAsk("worker-1", "ask-3");
+    store.attachToAsk("worker-1", "ask-3", undefined, 1_000_001);
     const message = buildRetryMessage(envelope);
     expect(message).toContain(envelope.requestId);
     expect(message).toContain("ask-3");
     expect(message).toContain(JSON.stringify(ARGS));
   });
 });
+
+describe("WorkerGrantStore.runExclusive", () => {
+  test("serializes same-key holders: no overlap, FIFO, error still releases", async () => {
+    const store = new WorkerGrantStore();
+    const events: string[] = [];
+    let releaseFirst!: () => void;
+    const firstGate = new Promise<void>((resolve) => {
+      releaseFirst = resolve;
+    });
+    const first = store.runExclusive("k", async () => {
+      events.push("first-start");
+      await firstGate;
+      events.push("first-end");
+      return "first";
+    });
+    const second = store.runExclusive("k", async () => {
+      events.push("second-start");
+      events.push("second-end");
+      return "second";
+    });
+    // Let both register; the second holder must not start while the first
+    // holds the turn across the awaited gate.
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    expect(events).toEqual(["first-start"]);
+    releaseFirst();
+    await expect(first).resolves.toBe("first");
+    await expect(second).resolves.toBe("second");
+    expect(events).toEqual([
+      "first-start",
+      "first-end",
+      "second-start",
+      "second-end",
+    ]);
+
+    // A throwing holder still releases: the next waiter proceeds.
+    const failing = store.runExclusive("k", async () => {
+      throw new Error("boom");
+    });
+    const after = store.runExclusive("k", async () => "after");
+    await expect(failing).rejects.toThrow("boom");
+    await expect(after).resolves.toBe("after");
+  });
+
+  test("different keys do not block each other", async () => {
+    const store = new WorkerGrantStore();
+    const order: string[] = [];
+    await Promise.all([
+      store.runExclusive("a", async () => {
+        await new Promise((resolve) => setTimeout(resolve, 5));
+        order.push("a");
+      }),
+      store.runExclusive("b", async () => {
+        order.push("b");
+      }),
+    ]);
+    expect(order).toEqual(["b", "a"]);
+  });
+});