@cleocode/contracts 2026.6.19 → 2026.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.6.19",
+  "version": "2026.7.2",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",
@@ -194,7 +194,7 @@
   "dependencies": {
     "zod": "^4.3.6",
     "zod-to-json-schema": "^3.25.2",
-    "@cleocode/lafs": "2026.6.19"
+    "@cleocode/lafs": "2026.7.2"
   },
   "scripts": {
     "build": "tsc -b --force && node scripts/copy-assets.mjs && node scripts/emit-schemas.mjs",

package/src/index.ts

@@ -777,6 +777,11 @@ export type {
   QueuePriorityClass,
   RateCheckRequest,
   RateResultResponse,
+  ResourceAdmitDisposition,
+  ResourceAdmitRequest,
+  ResourceAdmitResultResponse,
+  ResourceReleaseRequest,
+  ResourceReleaseResultResponse,
   ToolGrantedResponse,
   ToolGrantRequest,
 } from './lease-ipc/index.js';
@@ -808,6 +813,11 @@ export {
   QueuePriorityClassSchema,
   RateCheckRequestSchema,
   RateResultResponseSchema,
+  ResourceAdmitDispositionSchema,
+  ResourceAdmitRequestSchema,
+  ResourceAdmitResultResponseSchema,
+  ResourceReleaseRequestSchema,
+  ResourceReleaseResultResponseSchema,
   ToolGrantedResponseSchema,
   ToolGrantRequestSchema,
 } from './lease-ipc/index.js';
@@ -2057,6 +2067,21 @@ export type {
 } from './release/version-bump.js';
 // === Human Render Contract (Epic T10114, ADR-077) ===
 export * from './render/index.js';
+export type {
+  AdmissionResult,
+  GovernorMode,
+  ResourceClass,
+  ResourceDeferral,
+  ResourceGrant,
+} from './resource-governor.js';
+// === Resource Governor — Never-OOM admission layer (T11999 / Epic T11992) ===
+export {
+  DEFAULT_RESOURCE_RETRY_AFTER_MS,
+  isResourceGrant,
+  RESOURCE_BACKPRESSURE_CODE,
+  RESOURCE_CLASSES,
+  RESOURCE_DEFERRED_CODE,
+} from './resource-governor.js';
 // === Result Types (Dashboard, Stats, Log, Context, Sequence, Analysis, Deps) ===
 export type {
   BottleneckTask,

package/src/lease-ipc/__tests__/freeze.test.ts

@@ -26,14 +26,14 @@ import {
 
 describe('lease-ipc v1.1 freeze guard (T11627)', () => {
   it('pins the parallel protocol version', () => {
-    expect(LEASE_IPC_PROTOCOL_VERSION).toBe('1.1.0');
+    expect(LEASE_IPC_PROTOCOL_VERSION).toBe('1.2.0');
   });
 
   it('the version differs from the frozen supervisor-ipc v1.0 wire version', () => {
     // The two contracts are distinguished on the wire purely by this string;
     // it MUST NOT collide with '1.0.0'.
     expect(LEASE_IPC_PROTOCOL_VERSION).not.toBe('1.0.0');
-    expect(isFrozenLeaseIpcVersion('1.1.0')).toBe(true);
+    expect(isFrozenLeaseIpcVersion('1.2.0')).toBe(true);
     expect(isFrozenLeaseIpcVersion('1.0.0')).toBe(false);
   });
 
@@ -46,6 +46,8 @@ describe('lease-ipc v1.1 freeze guard (T11627)', () => {
       'tool_grant',
       'queue_admit',
       'worker_heartbeat',
+      'resource_admit',
+      'resource_release',
     ]);
   });
 
@@ -60,6 +62,8 @@ describe('lease-ipc v1.1 freeze guard (T11627)', () => {
       'child_killed_unresponsive',
       'queue_admit_result',
       'heartbeat_ack',
+      'resource_admit_result',
+      'resource_release_result',
       'error',
     ]);
   });
@@ -87,6 +91,8 @@ describe('lease-ipc v1.1 freeze guard (T11627)', () => {
       'tool_grant',
       'queue_admit',
       'worker_heartbeat',
+      'resource_admit',
+      'resource_release',
       'lease_granted',
       'lease_queued',
       'lease_denied',
@@ -96,6 +102,8 @@ describe('lease-ipc v1.1 freeze guard (T11627)', () => {
       'child_killed_unresponsive',
       'queue_admit_result',
       'heartbeat_ack',
+      'resource_admit_result',
+      'resource_release_result',
       'error',
     ]);
   });
@@ -106,7 +114,7 @@ describe('lease-ipc v1.1 wire-shape parity with Rust serde (T11627)', () => {
     // Literal JSON shape produced by
     // cleo_supervisor::lease_ipc::LeaseEnvelope::request(...).to_ndjson().
     const wire = {
-      protocol_version: '1.1.0',
+      protocol_version: '1.2.0',
       id: 'abc',
       direction: 'request',
       request: {
@@ -128,7 +136,7 @@ describe('lease-ipc v1.1 wire-shape parity with Rust serde (T11627)', () => {
 
   it('parses the exact JSON a Rust lease_granted response envelope serializes', () => {
     const wire = {
-      protocol_version: '1.1.0',
+      protocol_version: '1.2.0',
       id: 'abc',
       direction: 'response',
       response: {
@@ -146,7 +154,7 @@ describe('lease-ipc v1.1 wire-shape parity with Rust serde (T11627)', () => {
 
   it('parses a Rust child_killed_unresponsive event envelope', () => {
     const wire = {
-      protocol_version: '1.1.0',
+      protocol_version: '1.2.0',
       id: 'evt-1',
       direction: 'response',
       response: {
@@ -162,7 +170,7 @@ describe('lease-ipc v1.1 wire-shape parity with Rust serde (T11627)', () => {
 
   it('parses a reused v1.0 error response shape ({ kind, code, message })', () => {
     const wire = {
-      protocol_version: '1.1.0',
+      protocol_version: '1.2.0',
       id: 'e',
       direction: 'response',
       response: { kind: 'error', code: 'E_LEASE_UNIMPLEMENTED', message: 'deferred handler' },
@@ -172,7 +180,7 @@ describe('lease-ipc v1.1 wire-shape parity with Rust serde (T11627)', () => {
 
   it('parses the exact JSON a Rust queue_admit request envelope serializes (T11630)', () => {
     const wire = {
-      protocol_version: '1.1.0',
+      protocol_version: '1.2.0',
       id: 'qa-1',
       direction: 'request',
       request: {
@@ -192,7 +200,7 @@ describe('lease-ipc v1.1 wire-shape parity with Rust serde (T11627)', () => {
 
   it('parses the exact JSON a Rust queue_admit_result response envelope serializes (T11630)', () => {
     const wire = {
-      protocol_version: '1.1.0',
+      protocol_version: '1.2.0',
       id: 'qa-1',
       direction: 'response',
       response: {
@@ -208,7 +216,7 @@ describe('lease-ipc v1.1 wire-shape parity with Rust serde (T11627)', () => {
 
   it('parses the exact JSON a Rust worker_heartbeat request envelope serializes (T11628)', () => {
     const wire = {
-      protocol_version: '1.1.0',
+      protocol_version: '1.2.0',
       id: 'hb-1',
       direction: 'request',
       request: {
@@ -226,7 +234,7 @@ describe('lease-ipc v1.1 wire-shape parity with Rust serde (T11627)', () => {
 
   it('parses the exact JSON a Rust heartbeat_ack response envelope serializes (T11628)', () => {
     const wire = {
-      protocol_version: '1.1.0',
+      protocol_version: '1.2.0',
       id: 'hb-1',
       direction: 'response',
       response: { kind: 'heartbeat_ack' },
@@ -238,9 +246,61 @@ describe('lease-ipc v1.1 wire-shape parity with Rust serde (T11627)', () => {
     }
   });
 
+  it('parses the exact JSON a Rust resource_admit request envelope serializes (T12001)', () => {
+    const wire = {
+      protocol_version: '1.2.0',
+      id: 'ra-1',
+      direction: 'request',
+      request: {
+        kind: 'resource_admit',
+        class: 'db-heavy',
+        holder_id: 'pid-42:db-heavy',
+        budget: 1,
+      },
+    };
+    const parsed = LeaseIpcEnvelopeSchema.safeParse(wire);
+    expect(parsed.success).toBe(true);
+    if (parsed.success && parsed.data.direction === 'request') {
+      expect(parsed.data.request.kind).toBe('resource_admit');
+    }
+  });
+
+  it('parses the exact JSON a Rust resource_admit_result response envelope serializes (T12001)', () => {
+    const wire = {
+      protocol_version: '1.2.0',
+      id: 'ra-1',
+      direction: 'response',
+      response: {
+        kind: 'resource_admit_result',
+        disposition: 'deferred',
+        retry_after_ms: 2000,
+        slots_remaining: 0,
+      },
+    };
+    const parsed = LeaseIpcEnvelopeSchema.safeParse(wire);
+    expect(parsed.success).toBe(true);
+    if (parsed.success && parsed.data.direction === 'response') {
+      expect(parsed.data.response.kind).toBe('resource_admit_result');
+    }
+  });
+
+  it('parses the exact JSON a Rust resource_release_result response envelope serializes (T12001)', () => {
+    const wire = {
+      protocol_version: '1.2.0',
+      id: 'rr-1',
+      direction: 'response',
+      response: { kind: 'resource_release_result', released: true, slots_remaining: 1 },
+    };
+    const parsed = LeaseIpcEnvelopeSchema.safeParse(wire);
+    expect(parsed.success).toBe(true);
+    if (parsed.success && parsed.data.direction === 'response') {
+      expect(parsed.data.response.kind).toBe('resource_release_result');
+    }
+  });
+
   it('rejects an unknown message kind (proves the union is closed)', () => {
     const wire = {
-      protocol_version: '1.1.0',
+      protocol_version: '1.2.0',
       id: 'abc',
       direction: 'request',
       request: { kind: 'lease_teleport', scope: 'project', lane: 'tasks' },
@@ -250,7 +310,7 @@ describe('lease-ipc v1.1 wire-shape parity with Rust serde (T11627)', () => {
 
   it('rejects an unknown scope/lane enum value (snake_case enums are closed)', () => {
     const wire = {
-      protocol_version: '1.1.0',
+      protocol_version: '1.2.0',
       id: 'abc',
       direction: 'request',
       request: {
@@ -298,6 +358,10 @@ function sampleRequestFor(kind: (typeof LEASE_IPC_REQUEST_KINDS)[number]): unkno
       };
     case 'worker_heartbeat':
       return { kind, child_id: 'worker-1', in_flight_llm: true };
+    case 'resource_admit':
+      return { kind, class: 'db-heavy', holder_id: 'pid-42:db-heavy', budget: 1 };
+    case 'resource_release':
+      return { kind, class: 'db-heavy', holder_id: 'pid-42:db-heavy' };
   }
 }
 
@@ -336,6 +400,10 @@ function sampleResponseFor(kind: (typeof LEASE_IPC_RESPONSE_KINDS)[number]): unk
       };
     case 'heartbeat_ack':
       return { kind };
+    case 'resource_admit_result':
+      return { kind, disposition: 'deferred', retry_after_ms: 2000, slots_remaining: 0 };
+    case 'resource_release_result':
+      return { kind, released: true, slots_remaining: 1 };
     case 'error':
       return { kind, code: 'E_X', message: 'x' };
   }

package/src/lease-ipc/index.ts

@@ -36,6 +36,11 @@ export type {
   QueuePriorityClass,
   RateCheckRequest,
   RateResultResponse,
+  ResourceAdmitDisposition,
+  ResourceAdmitRequest,
+  ResourceAdmitResultResponse,
+  ResourceReleaseRequest,
+  ResourceReleaseResultResponse,
   ToolGrantedResponse,
   ToolGrantRequest,
   WorkerHeartbeatRequest,
@@ -68,6 +73,11 @@ export {
   QueuePriorityClassSchema,
   RateCheckRequestSchema,
   RateResultResponseSchema,
+  ResourceAdmitDispositionSchema,
+  ResourceAdmitRequestSchema,
+  ResourceAdmitResultResponseSchema,
+  ResourceReleaseRequestSchema,
+  ResourceReleaseResultResponseSchema,
   ToolGrantedResponseSchema,
   ToolGrantRequestSchema,
   WorkerHeartbeatRequestSchema,

package/src/lease-ipc/messages.ts

@@ -12,12 +12,12 @@
  *
  * ```jsonc
  * // request
- * { "protocol_version": "1.1.0", "id": "abc", "direction": "request",
+ * { "protocol_version": "1.2.0", "id": "abc", "direction": "request",
  *   "request": { "kind": "lease_acquire", "scope": "project", "lane": "tasks",
  *                "holder_id": "pid-42:tasks", "priority": 0, "ttl_ms": 30000,
  *                "reentrant": true } }
  * // response
- * { "protocol_version": "1.1.0", "id": "abc", "direction": "response",
+ * { "protocol_version": "1.2.0", "id": "abc", "direction": "response",
  *   "response": { "kind": "lease_granted", "scope": "project", "lane": "tasks",
  *                 "holder_id": "pid-42:tasks", "epoch": 7, "ttl_ms": 30000,
  *                 "expires_at_ms": 1000030000 } }
@@ -229,6 +229,50 @@ export const WorkerHeartbeatRequestSchema = z
 /** Worker-heartbeat request payload (inferred from {@link WorkerHeartbeatRequestSchema}). */
 export type WorkerHeartbeatRequest = z.infer<typeof WorkerHeartbeatRequestSchema>;
 
+/**
+ * Admit (or defer) a heavy resource-intensive operation through the central
+ * per-class concurrency arbiter (T12001 · Epic T11992). Mirrors
+ * `ResourceAdmitReq`. `[wired]`
+ *
+ * The client computes `budget` from its local memory-pressure sample; the
+ * supervisor enforces the per-class in-flight COUNT centrally across processes,
+ * so heavy ops (builds, tests, exodus) can never co-schedule past the budget.
+ */
+export const ResourceAdmitRequestSchema = z
+  .object({
+    /** Tag discriminating this request variant. */
+    kind: z.literal('resource_admit'),
+    /** The resource class (e.g. `"db-heavy"`, `"full-build"`, `"test-run"`). */
+    class: z.string().min(1),
+    /** The caller holding the slot — process/worktree-unique; the release key. */
+    holder_id: z.string().min(1),
+    /** The client-computed budget: the max concurrent holders for this class. */
+    budget: z.number().int().nonnegative(),
+  })
+  .strict();
+
+/** Resource-admit request payload (inferred from {@link ResourceAdmitRequestSchema}). */
+export type ResourceAdmitRequest = z.infer<typeof ResourceAdmitRequestSchema>;
+
+/**
+ * Release a previously-admitted resource slot (T12001). Mirrors
+ * `ResourceReleaseReq`. Idempotent — releasing an unknown holder is a no-op.
+ * `[wired]`
+ */
+export const ResourceReleaseRequestSchema = z
+  .object({
+    /** Tag discriminating this request variant. */
+    kind: z.literal('resource_release'),
+    /** The resource class the slot belongs to. */
+    class: z.string().min(1),
+    /** The holder that was admitted (matches the admit `holder_id`). */
+    holder_id: z.string().min(1),
+  })
+  .strict();
+
+/** Resource-release request payload (inferred from {@link ResourceReleaseRequestSchema}). */
+export type ResourceReleaseRequest = z.infer<typeof ResourceReleaseRequestSchema>;
+
 /**
  * The discriminated union of all client → arbiter lease requests. The `kind`
  * field selects the variant, matching the serde `#[serde(tag = "kind")]`
@@ -242,6 +286,8 @@ export const LeaseIpcRequestSchema = z.discriminatedUnion('kind', [
   ToolGrantRequestSchema,
   QueueAdmitRequestSchema,
   WorkerHeartbeatRequestSchema,
+  ResourceAdmitRequestSchema,
+  ResourceReleaseRequestSchema,
 ]);
 
 /** Any lease IPC request (inferred from {@link LeaseIpcRequestSchema}). */
@@ -445,6 +491,54 @@ export const HeartbeatAckResponseSchema = z
 /** Heartbeat-ack response payload (inferred from {@link HeartbeatAckResponseSchema}). */
 export type HeartbeatAckResponse = z.infer<typeof HeartbeatAckResponseSchema>;
 
+/**
+ * The disposition of a `resource_admit` request (T12001) — `admitted` (run the
+ * heavy op now) or `deferred` (back off `retry_after_ms` and re-request; never a
+ * silent drop). Mirrors `ResourceAdmitDisposition`.
+ */
+export const ResourceAdmitDispositionSchema = z.enum(['admitted', 'deferred']);
+
+/** A `resource_admit` disposition (inferred from {@link ResourceAdmitDispositionSchema}). */
+export type ResourceAdmitDisposition = z.infer<typeof ResourceAdmitDispositionSchema>;
+
+/**
+ * Reply to a `resource_admit`: the heavy op was admitted or deferred (T12001).
+ * Mirrors `ResourceAdmitResult`.
+ */
+export const ResourceAdmitResultResponseSchema = z
+  .object({
+    /** Tag discriminating this response variant. */
+    kind: z.literal('resource_admit_result'),
+    /** Whether the heavy op was admitted or deferred. */
+    disposition: ResourceAdmitDispositionSchema,
+    /** Back-off in ms before re-requesting (0 when admitted). */
+    retry_after_ms: z.number().int().nonnegative(),
+    /** Remaining slots for the class after this decision. */
+    slots_remaining: z.number().int().nonnegative(),
+  })
+  .strict();
+
+/** Resource-admit result payload (inferred from {@link ResourceAdmitResultResponseSchema}). */
+export type ResourceAdmitResultResponse = z.infer<typeof ResourceAdmitResultResponseSchema>;
+
+/**
+ * Reply to a `resource_release`: the slot was released (T12001). Mirrors
+ * `ResourceReleaseResult`.
+ */
+export const ResourceReleaseResultResponseSchema = z
+  .object({
+    /** Tag discriminating this response variant. */
+    kind: z.literal('resource_release_result'),
+    /** Whether a held slot was actually released (false = no such holder). */
+    released: z.boolean(),
+    /** Remaining in-flight holders for the class after the release. */
+    slots_remaining: z.number().int().nonnegative(),
+  })
+  .strict();
+
+/** Resource-release result payload (inferred from {@link ResourceReleaseResultResponseSchema}). */
+export type ResourceReleaseResultResponse = z.infer<typeof ResourceReleaseResultResponseSchema>;
+
 /**
  * An error response correlated to a request. Mirrors the v1.0
  * `crate::ipc::ErrorResult` shape reused by the Rust `LeaseResponse::Error`
@@ -479,6 +573,8 @@ export const LeaseIpcResponseSchema = z.discriminatedUnion('kind', [
   ChildKilledUnresponsiveResponseSchema,
   QueueAdmitResultResponseSchema,
   HeartbeatAckResponseSchema,
+  ResourceAdmitResultResponseSchema,
+  ResourceReleaseResultResponseSchema,
   LeaseErrorResponseSchema,
 ]);
 
@@ -559,10 +655,12 @@ export const LEASE_IPC_REQUEST_KINDS = [
   'tool_grant',
   'queue_admit',
   'worker_heartbeat',
+  'resource_admit',
+  'resource_release',
 ] as const;
 
 /**
- * The v1.1 response `kind` values, in declaration order. The schema-drift guard
+ * The v1.2 response `kind` values, in declaration order. The schema-drift guard
  * test pins this tuple.
  */
 export const LEASE_IPC_RESPONSE_KINDS = [
@@ -575,6 +673,8 @@ export const LEASE_IPC_RESPONSE_KINDS = [
   'child_killed_unresponsive',
   'queue_admit_result',
   'heartbeat_ack',
+  'resource_admit_result',
+  'resource_release_result',
   'error',
 ] as const;
 

package/src/lease-ipc/version.ts

@@ -5,7 +5,7 @@
  * TypeScript contract MUST agree on this value. It runs **in parallel** to the
  * byte-frozen `supervisor-ipc` v1.0 contract: the two are distinguished on the
  * wire purely by this version string, so a single accept loop can route
- * `'1.0.0'` → the v1.0 union and `'1.1.0'` → the lease union. Bump only via a
+ * `'1.0.0'` → the v1.0 union and `'1.2.0'` → the lease union. Bump only via a
  * coordinated dual (Rust + TS) edit, never edit this value in place.
  *
  * @see {@link LEASE_IPC_MESSAGE_KINDS} for the v1.1 message set.
@@ -14,13 +14,16 @@
  */
 
 /**
- * The `lease-ipc` v1.1 protocol version string.
+ * The `lease-ipc` v1.2 protocol version string.
  *
  * Mirrors `cleo_supervisor::lease_ipc::LEASE_IPC_PROTOCOL_VERSION` on the Rust
  * side. Both the Rust schema-drift guard (`lease_ipc::tests`) and the TS drift
  * test (`__tests__/freeze.test.ts`) pin this exact value.
+ *
+ * v1.2 (T12001 · Epic T11992) added the `resource_admit` / `resource_release`
+ * heavy-op admission verbs; v1.1 added `queue_admit` / `worker_heartbeat`.
  */
-export const LEASE_IPC_PROTOCOL_VERSION = '1.1.0' as const;
+export const LEASE_IPC_PROTOCOL_VERSION = '1.2.0' as const;
 
 /**
  * Whether the given version string is the frozen `lease-ipc` v1.1 wire version.

package/src/resource-governor.ts

@@ -0,0 +1,123 @@
+/**
+ * Resource Governor — shared types for the Never-OOM admission layer.
+ *
+ * The {@link ResourceGovernor} (in `@cleocode/core`) admits resource-intensive
+ * work through priority classes whose budgets are computed from host memory and
+ * memory-pressure (PSI). A denial returns a structured, retryable
+ * {@link ResourceDeferral} (code {@link RESOURCE_DEFERRED_CODE}) rather than a
+ * silent drop or a crash — orchestrators treat it like a lifecycle gate: wait
+ * and retry, never fail the task.
+ *
+ * Mirrors the llm-queue deferral contract (`retry_after_ms`, degrade-to-direct)
+ * so the two admission surfaces share one shape.
+ *
+ * @task T11999
+ * @epic T11992
+ * @adr resource-governor-never-oom-architecture §3.4
+ */
+
+/**
+ * Governor arbitration mode. Mirrors the writer-lease mode shape
+ * (`writer-lease.ts` {@link LeaseMode}).
+ *
+ * - `supervisor` — defer to the Rust `cleo-supervisor` `resource_admit` verb
+ *   (continuous PSI, priority wakeups). Demotes to `local` when the supervisor
+ *   IPC client is not wired/reachable (never deadlocks).
+ * - `local` — DEFAULT. Daemon-off arbitration through shared per-class slot
+ *   directories (proper-lockfile crash-stale auto-release) + a point-sample of
+ *   {@link ResourceSample} taken inside `acquire`. Genuinely cross-process
+ *   without a daemon, mirroring the tool-semaphore engine.
+ * - `off` — pure pass-through; every acquire is granted immediately.
+ */
+export type GovernorMode = 'supervisor' | 'local' | 'off';
+
+/**
+ * Priority classes (highest priority first). `interactive-cli` is NEVER gated;
+ * `full-build` is pinned to one machine-wide slot regardless of pressure.
+ *
+ * @adr resource-governor-never-oom-architecture §3.4 (classes)
+ */
+export type ResourceClass =
+  | 'interactive-cli'
+  | 'agent-session'
+  | 'llm-call'
+  | 'test-run'
+  | 'scoped-build'
+  | 'full-build'
+  | 'db-heavy'
+  | 'background-autonomous';
+
+/**
+ * All resource classes in descending priority order. Single source of truth for
+ * iteration + validation.
+ */
+export const RESOURCE_CLASSES: readonly ResourceClass[] = Object.freeze([
+  'interactive-cli',
+  'agent-session',
+  'llm-call',
+  'test-run',
+  'scoped-build',
+  'full-build',
+  'db-heavy',
+  'background-autonomous',
+]);
+
+/** Error code emitted when an acquire is denied because no slot is available. */
+export const RESOURCE_DEFERRED_CODE = 'E_RESOURCE_DEFERRED' as const;
+
+/**
+ * Soft-signal code raised on the next admit when the host enters `backoff` —
+ * asks granted work to checkpoint. Existing grants are NEVER revoked.
+ */
+export const RESOURCE_BACKPRESSURE_CODE = 'E_RESOURCE_BACKPRESSURE' as const;
+
+/**
+ * Structured, retryable deferral returned when admission is denied. Never a
+ * silent drop; callers back off `retryAfterMs` and re-request, or annotate the
+ * unit as deferred and let a pull-based retry pick it up.
+ */
+export interface ResourceDeferral {
+  /** Discriminant for narrowing against the success grant. */
+  readonly deferred: true;
+  /** The class whose budget was exhausted. */
+  readonly class: ResourceClass;
+  /** Suggested back-off before re-requesting, in milliseconds. */
+  readonly retryAfterMs: number;
+  /** Human-readable reason (pressure state, budget, held count). */
+  readonly reason: string;
+}
+
+/**
+ * A granted admission slot. Hold it for the lifetime of the work, then
+ * {@link ResourceGrant.release}. Releasing reaps the slot so the next acquirer
+ * can proceed; releasing twice is a no-op.
+ */
+export interface ResourceGrant {
+  /** Discriminant for narrowing against {@link ResourceDeferral}. */
+  readonly deferred: false;
+  /** The class this grant belongs to. */
+  readonly class: ResourceClass;
+  /**
+   * Slot index held (local mode), or `-1` for an ungated pass-through grant
+   * (`interactive-cli`, `off` mode, or an unbounded budget).
+   */
+  readonly slot: number;
+  /** Monotonic timestamp (ms) when the grant was acquired. */
+  readonly acquiredAtMs: number;
+  /** Release the slot. Idempotent. */
+  release(): Promise<void>;
+}
+
+/** Discriminated union returned by a non-blocking `tryAcquire`. */
+export type AdmissionResult = ResourceGrant | ResourceDeferral;
+
+/**
+ * Default back-off hint when a class is saturated, in milliseconds. Aligned
+ * with the llm-queue `DEFAULT_ADMIT_DEADLINE_MS` so the two surfaces agree.
+ */
+export const DEFAULT_RESOURCE_RETRY_AFTER_MS = 2_000;
+
+/** Type guard: did an admission attempt produce a usable grant? */
+export function isResourceGrant(r: AdmissionResult): r is ResourceGrant {
+  return r.deferred === false;
+}