@vess-id/vess 0.0.0-dev-20260902121045

package/dist/core/execution-engine.js

@@ -0,0 +1,1931 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutionEngine = void 0;
+/**
+ * Execution Control Runtime — the core of agentd.
+ *
+ * All execution control logic lives here:
+ * - Action normalization
+ * - Resource canonicalization
+ * - Policy evaluation (local + org)
+ * - VC acquisition (4-step flow, spec §6.1)
+ * - VP creation + Gateway verification (spec §7.4)
+ * - Execution routing (local vs gateway)
+ * - Offline fallback (spec §7.6)
+ * - Audit logging
+ *
+ * This module is adapter-independent. MCP, IDE plugins, or SDK clients
+ * all call ExecutionEngine.execute() through their respective thin adapters.
+ */
+const ai_identity_1 = require("@vess-id/ai-identity");
+const os_1 = require("os");
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const wallet_1 = require("../wallet/wallet");
+const gateway_client_1 = require("../gateway/gateway-client");
+const resource_canonicalizer_1 = require("../utils/resource-canonicalizer");
+const vc_utils_1 = require("../utils/vc-utils");
+const credential_errors_1 = require("../utils/credential-errors");
+const executor_registry_1 = require("../executor/executor-registry");
+const env_resolver_1 = require("../env/env-resolver");
+/** Policy cache staleness TTL (spec §7.6: 30 minutes) */
+const POLICY_SYNC_TTL_MS = 30 * 60 * 1000;
+/** Fallback OOB approval expiration (seconds) when the API doesn't return a value.
+ *  Kept short (5 min) so the agent doesn't wait on a possibly-expired request. */
+const OOB_APPROVAL_DEFAULT_EXPIRES_IN_SECONDS = 300;
+/** Default TTL for OOB-approved credentials (10 minutes) */
+const OOB_CREDENTIAL_DEFAULT_TTL_MS = 10 * 60 * 1000;
+class ExecutionEngine {
+    policyEvaluator;
+    wallet;
+    vpBuilder;
+    auditLogger;
+    gatewayClient;
+    context;
+    tokenService;
+    secretBackend;
+    lastPolicySyncTime = null;
+    clientInfo;
+    agentRegistered = false;
+    /**
+     * Wall-clock timestamp (ms) of the most recent registerAgent attempt, used
+     * to throttle retries during a sustained outage so we don't hammer the API
+     * with one POST per tool call. See REGISTRATION_RETRY_COOLDOWN_MS.
+     */
+    lastRegistrationAttemptAt = 0;
+    /**
+     * In-flight registerAgent promise, exposed via `registrationInFlight` for
+     * deterministic test waits. `null` when no fetch is pending. Tests await
+     * this to flush the fire-and-forget catch handler without resorting to
+     * arbitrary setTimeout sleeps that race the microtask queue.
+     */
+    inFlightRegistration = null;
+    recentOOBRequests = new Map();
+    static OOB_COOLDOWN_MS = 60_000;
+    static OOB_MAP_MAX_SIZE = 1000;
+    /**
+     * Minimum interval between registerAgent attempts when the flag is unset
+     * (i.e., the previous attempt failed non-409). 5s is large enough to avoid
+     * a request storm against `POST /v1/agents/create` during a sustained
+     * outage (ALB rolling, DB connection storm), and small enough that a
+     * recovered API picks the agent back up within a couple of tool calls.
+     */
+    static REGISTRATION_RETRY_COOLDOWN_MS = 5_000;
+    constructor(policyEvaluator, wallet, vpBuilder, auditLogger, gatewayClient, context, tokenService, secretBackend) {
+        this.policyEvaluator = policyEvaluator;
+        this.wallet = wallet;
+        this.vpBuilder = vpBuilder;
+        this.auditLogger = auditLogger;
+        this.gatewayClient = gatewayClient;
+        this.context = context;
+        this.tokenService = tokenService;
+        this.secretBackend = secretBackend;
+    }
+    /**
+     * Record a successful policy sync timestamp (called by SyncScheduler).
+     */
+    setLastPolicySyncTime(time) {
+        this.lastPolicySyncTime = time;
+    }
+    /**
+     * Set MCP client info (from oninitialized callback).
+     * Used to derive a meaningful agent name for deferred registration.
+     */
+    setClientInfo(info) {
+        this.clientInfo = info;
+    }
+    /**
+     * Ensure the agent is registered in the API.
+     * Called lazily on first tool execution (fire-and-forget).
+     * Uses clientInfo from MCP initialize handshake if available.
+     *
+     * Retry semantics (audit fix for audit_events vs /agents divergence):
+     *   - Optimistic flag: mark `agentRegistered = true` BEFORE the fetch so
+     *     concurrent `execute()` calls don't all fire duplicate registrations.
+     *   - On 409 (GatewayHttpError with status 409): leave the flag true — the
+     *     agent row already exists in the DB. We type-check via the typed
+     *     `GatewayHttpError.status` field rather than substring-matching the
+     *     message, so a future change to the error wording can't accidentally
+     *     reclassify "already exists" 409s as 5xx-style retries (or vice versa).
+     *     A string-match fallback (`'409' / 'already exists' / 'duplicate'`)
+     *     remains for older/non-typed Error instances thrown from other layers
+     *     (e.g. middleware / network helpers that haven't been converted).
+     *   - On any other failure (5xx, network, etc.): reset the flag to false so
+     *     the next `execute()` retries — subject to the retry cool-down below.
+     *   - Cool-down: at most one POST every REGISTRATION_RETRY_COOLDOWN_MS while
+     *     the flag stays false. Without this, a sustained 5xx (e.g. ALB rolling,
+     *     DB connection storm) would result in one POST per tool call.
+     *   - Retry horizon: there is intentionally NO upper bound on the number of
+     *     cool-down cycles. agentd is a long-lived daemon, so for a sustained
+     *     outage we want it to keep retrying (once per cool-down) and self-heal
+     *     the moment the gateway recovers — a hard cap would permanently brick
+     *     registration after N failures, which is strictly worse. Tool execution
+     *     itself does not block on registration (it is fire-and-forget), so an
+     *     unregistered agent degrades gracefully rather than deadlocking.
+     *   - No stuck-flag deadlock: `inFlightRegistration` is reset to `null` in
+     *     the `.finally()` below on EVERY settle (success, 409, or 5xx), so the
+     *     `agentRegistered=false` + in-flight-guard combination can never wedge
+     *     permanently — the next post-cool-down `execute()` always re-attempts.
+     */
+    ensureAgentRegistered() {
+        // IMPORTANT: This method MUST remain synchronous from entry through the
+        // optimistic `this.agentRegistered = true` assignment below. Inserting an
+        // `await` between the flag check and the optimistic set would re-introduce
+        // the race that the optimistic pattern is specifically designed to prevent
+        // (two concurrent `execute()` calls both observing the flag as false and
+        // both firing duplicate POST /v1/agents/create). Node's single-threaded
+        // event loop guarantees that synchronous code in this critical section
+        // runs atomically with respect to other JS execution — but only while
+        // there is no `await` to yield the microtask queue. The fetch itself is
+        // launched without await (fire-and-forget via `.then()/.catch()`), which
+        // preserves this invariant.
+        if (this.agentRegistered)
+            return;
+        // Defense-in-depth dedup: if a prior call already kicked off a
+        // registerAgent fetch that is still in flight, don't fire another one
+        // even if `agentRegistered` was momentarily cleared by the catch handler
+        // (e.g. transient 5xx) and the cool-down has since elapsed. The
+        // optimistic-flag-before-fetch pattern above already covers the common
+        // case, but this guard makes the intent explicit and protects against
+        // future refactors that change the ordering.
+        if (this.inFlightRegistration)
+            return;
+        const publicKey = this.context.agentPublicKey;
+        if (!publicKey || !this.context.projectId)
+            return; // Pre-conditions not met; do NOT mark registered
+        // Retry cool-down: skip if we just attempted and failed. The next tool
+        // call after the cool-down window elapses will trigger another attempt.
+        const now = Date.now();
+        if (this.lastRegistrationAttemptAt > 0 &&
+            now - this.lastRegistrationAttemptAt < ExecutionEngine.REGISTRATION_RETRY_COOLDOWN_MS) {
+            return;
+        }
+        this.lastRegistrationAttemptAt = now;
+        const agentName = this.clientInfo
+            ? `${this.clientInfo.name}-agent`
+            : 'vess-agentd';
+        // OPTIMISTIC: mark registered BEFORE the fetch to dedupe concurrent
+        // execute() calls. If registerAgent fails, the catch handler clears
+        // the flag so the next tool execution retries.
+        this.agentRegistered = true;
+        this.inFlightRegistration = this.gatewayClient.registerAgent({
+            agentDid: this.context.agentDid,
+            name: agentName,
+            type: 'assistant',
+            publicKey,
+            projectId: this.context.projectId,
+            deviceInfo: {
+                platform: process.platform,
+                hostname: (0, os_1.hostname)(),
+                runtime: this.clientInfo?.name || 'unknown',
+            },
+        })
+            .then(() => { })
+            .catch((err) => {
+            // Prefer typed status check; fall back to string match for non-typed
+            // errors so legacy throw sites (or middleware) don't silently
+            // misclassify 409s as transient failures.
+            const status = err instanceof gateway_client_1.GatewayHttpError ? err.status : undefined;
+            const msg = err instanceof Error ? err.message : String(err);
+            const isConflict = status === 409 ||
+                (status === undefined && (/\b409\b/.test(msg) ||
+                    msg.includes('already exists') ||
+                    msg.includes('duplicate')));
+            if (isConflict) {
+                // 409 is idempotent success — agent already exists. Leave flag true.
+                return;
+            }
+            // Other failures: clear the flag so the next execute() retries.
+            // This unblocks transient failures (5xx, network) without burning
+            // a retry budget on every single tool call (the cool-down above
+            // bounds the actual retry rate).
+            this.agentRegistered = false;
+            process.stderr.write(`[vess] Agent registration failed (will retry on next tool call): ${msg}\n`);
+        })
+            .finally(() => {
+            // Always clear the in-flight handle, on every settle path (success,
+            // 409, or transient 5xx). This is what guarantees no permanent
+            // deadlock: even when the catch handler left agentRegistered=false,
+            // the in-flight guard (line ~167) is released here so the next
+            // execute() after the cool-down can retry. inFlightRegistration is
+            // `Promise | null` — never a stuck boolean.
+            this.inFlightRegistration = null;
+        });
+    }
+    /**
+     * Test-only accessor for the in-flight registerAgent promise.
+     *
+     * Awaiting this yields a deterministic wait for the fire-and-forget
+     * `.catch()` handler to finish updating internal state (the
+     * `agentRegistered` flag and the cool-down timestamp). Tests use this in
+     * place of arbitrary `setTimeout` sleeps, which would race the microtask
+     * queue and flake under load.
+     *
+     * Returns `null` when no registration is in flight.
+     */
+    get registrationInFlight() {
+        return this.inFlightRegistration;
+    }
+    /**
+     * Execute an action request.
+     * This is the single entry point for all adapters (MCP, future IDE, SDK).
+     */
+    async execute(request) {
+        // Deferred agent registration: fire-and-forget on first tool execution
+        this.ensureAgentRegistered();
+        // Mutual exclusion: pendingRequestId and approval are incompatible
+        if (request.pendingRequestId && request.approval) {
+            return { success: false, error: 'Cannot provide both pendingRequestId and approval in the same request' };
+        }
+        const { action, input } = request;
+        // Task 20 — validate parameter SHAPE against the registry input_schema
+        // BEFORE the approval / VC steps (parity with remote-mcp). A malformed
+        // call (e.g. inbox.respond invoked with { inboxId, accepted, selectedSlot }
+        // instead of { id, action }) must NOT mint an approval request: doing so
+        // consumes a human approval, shows an empty target prefill, and fails on
+        // invoke → re-approval loop. Failing fast here returns a self-correcting
+        // diagnostic so the agent fixes the shape and only the CORRECT call
+        // reaches approval. Unknown actions / actions without an input_schema
+        // (incl. local os.* actions) pass through unchanged. Skipped on the
+        // approval-retry / pending-approval paths, which carry the already
+        // validated original input plus an approval token / request id.
+        if (!request.approval && !request.pendingRequestId) {
+            const inputCheck = (0, ai_identity_1.validateActionInput)(action, input ?? {});
+            if (!inputCheck.valid) {
+                return { success: false, error: inputCheck.errors.join(' ') };
+            }
+        }
+        // 1. Extract provider from action (e.g., 'os' from 'os.secret.read')
+        const provider = action.split('.')[0];
+        // 2. Resource canonicalization
+        const requestedResource = input.file_path || (action === 'os.process.run' ? input.command?.join(' ') : undefined);
+        let normalizedResource;
+        let resourceFingerprint;
+        if ((0, executor_registry_1.isLocalAction)(action) && input.file_path) {
+            normalizedResource = (0, resource_canonicalizer_1.canonicalizePath)(input.file_path);
+            resourceFingerprint = (0, resource_canonicalizer_1.computeFingerprint)(normalizedResource, this.context.rootDid);
+        }
+        // 3. Policy evaluation (local + org deny check)
+        const policyResult = this.policyEvaluator.evaluate(provider, action.replace(`${provider}.`, ''), {
+            type: this.getResourceType(action),
+            pattern: normalizedResource || input.file_path,
+        });
+        if (!policyResult.allowed) {
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'local',
+                decisionSource: 'local_policy',
+                decisionReason: policyResult.reason,
+                requestedResource,
+                normalizedResource,
+                resourceFingerprint,
+                executionType: (0, executor_registry_1.isLocalAction)(action) ? 'local' : 'gateway',
+            });
+            return { success: false, error: `Action denied by policy: ${policyResult.reason}` };
+        }
+        // Handle OOB approval polling (pendingRequestId)
+        if (request.pendingRequestId) {
+            return this.handlePendingApproval(request);
+        }
+        // Handle 2nd call with approval decision
+        if (request.approval) {
+            // Security guard: block in-band approval for high/critical risk actions
+            const riskLevel = this.getActionRiskLevel(request.action);
+            if (riskLevel === 'high' || riskLevel === 'critical') {
+                return {
+                    success: false,
+                    error: `High-risk action "${request.action}" requires browser approval (Out-of-Band). In-band approval tokens are not accepted.`,
+                };
+            }
+            return this.handleApprovalResponse(request, provider, normalizedResource, resourceFingerprint, requestedResource);
+        }
+        // 4. Determine execution routing
+        const routing = (0, executor_registry_1.determineRouting)(provider, action);
+        // 5. Execute based on routing
+        if (routing.executor === 'local') {
+            return this.executeLocal(action, input, provider, normalizedResource, resourceFingerprint, requestedResource);
+        }
+        else {
+            return this.executeViaGateway(provider, action, input);
+        }
+    }
+    // ===========================================================================
+    // 4-step VC acquisition (spec §6.1)
+    // ===========================================================================
+    /**
+     * Ensure a valid VC exists for the requested action.
+     * Follows the 4-step acquisition flow from spec §6.1:
+     *
+     * Step 1: Check wallet for valid VC (verify revocation via Gateway using VC jti)
+     * Step 2: Check Gateway for approved requests
+     * Step 3: Try auto-issue via Gateway
+     * Step 4: Terminal approval prompt -> quick-approve via Gateway
+     *
+     * @param approvalContext — Cedar 一元化 Step 3.5 retry path. When the agent
+     *   re-invokes ensureVC after the user clicked 承認 in the approval UI, the
+     *   caller threads the ledger token + approval outcome ids here so Step 3's
+     *   `autoIssueVC` call carries them to the API. The API consumes the
+     *   single-use token and injects `context.approval.granted = true` into
+     *   Cedar evaluation, flipping the prior `auth_required` to `permit`.
+     */
+    async ensureVC(action, provider, resourceInfo, input = {}, canonicalResourceId, approvalContext) {
+        let approvedRequests = null;
+        // Step 1: Check wallet for existing valid VC
+        if (canonicalResourceId) {
+            // Step 1a: Exact resource match
+            const scopedVC = this.wallet.findCredential(this.context.agentDid, action, this.context.projectId, canonicalResourceId);
+            if (scopedVC) {
+                const verified = await this.verifyWalletVC(scopedVC);
+                if (verified)
+                    return { credential: verified, decisionSource: 'cached_vc' };
+            }
+            // Step 1b: Legacy VC without resource scope (Gateway will validate)
+            const unscopedVC = this.wallet.findUnscopedCredential(this.context.agentDid, action, this.context.projectId);
+            if (unscopedVC) {
+                const verified = await this.verifyWalletVC(unscopedVC);
+                if (verified)
+                    return { credential: verified, decisionSource: 'cached_vc' };
+            }
+            // No matching VC — fall through to Step 2-4
+        }
+        else {
+            // No resource context — use original findCredential
+            const walletVC = this.wallet.findCredential(this.context.agentDid, action, this.context.projectId);
+            if (walletVC) {
+                const verified = await this.verifyWalletVC(walletVC);
+                if (verified)
+                    return { credential: verified, decisionSource: 'cached_vc' };
+            }
+        }
+        // Step 2: Check Gateway for approved requests, then claim VC
+        try {
+            approvedRequests = await this.gatewayClient.findApprovedRequests(this.context.agentDid);
+            const matching = approvedRequests.find(r => r.actions?.includes(action));
+            if (matching) {
+                try {
+                    const claimed = await this.gatewayClient.claimVC(matching.id, this.context.agentDid);
+                    const stored = this.wallet.storeCredential({
+                        holderDid: this.context.agentDid,
+                        projectId: this.context.projectId,
+                        credentialJwt: claimed.credential.jwt,
+                        actions: claimed.actions,
+                        provider,
+                        expiresAt: claimed.credential.expiresAt,
+                        normalizedResourceKey: resourceInfo?.normalizedResource,
+                        resourceFingerprint: resourceInfo?.fingerprint,
+                        resources: (0, wallet_1.validateResources)(claimed.resources),
+                    });
+                    return { credential: stored, decisionSource: 'claimed_from_approval' };
+                }
+                catch (claimErr) {
+                    const msg = claimErr instanceof Error ? claimErr.message : String(claimErr);
+                    if (msg === 'CLAIM_CONSUMED') {
+                        process.stderr.write('[vess] claimVC: request already consumed, falling through to step 3\n');
+                    }
+                    else if (msg === 'CLAIM_EXPIRED') {
+                        process.stderr.write('[vess] claimVC: request expired, falling through to step 3\n');
+                    }
+                    else {
+                        process.stderr.write(`[vess] claimVC failed: ${msg}, falling through to step 3\n`);
+                    }
+                    // Fall through to Step 3
+                }
+            }
+        }
+        catch {
+            // Gateway unreachable for step 2 — continue to step 3
+        }
+        // Step 3: Try auto-issue via Gateway. On the Cedar 一元化 Step 3.5 retry
+        // path, thread `approval_context` through so the API can consume the
+        // single-use approval token against the ledger and flip Cedar's prior
+        // `auth_required` to `permit` (spec §6 / §11.1).
+        //
+        // 動作確認 fix-forward (spec rev 5) — also thread the raw tool input
+        // through `parameters` so the API can bind `context.recipient.address`
+        // for templates like `recipient.address like "*@vess.id"`.
+        try {
+            const autoResult = await this.gatewayClient.autoIssueVC({
+                subjectDid: this.context.agentDid,
+                projectId: this.context.projectId,
+                actions: [action],
+                ...(approvalContext ? { approval_context: approvalContext } : {}),
+                ...(input && Object.keys(input).length > 0 ? { parameters: input } : {}),
+            });
+            if (autoResult?.autoIssued && autoResult.credential) {
+                const stored = this.wallet.storeCredential({
+                    holderDid: this.context.agentDid,
+                    projectId: this.context.projectId,
+                    credentialJwt: autoResult.credential.jwt,
+                    actions: autoResult.actions || [action],
+                    provider,
+                    expiresAt: autoResult.credential.expiresAt,
+                    normalizedResourceKey: resourceInfo?.normalizedResource,
+                    resourceFingerprint: resourceInfo?.fingerprint,
+                    resources: (0, wallet_1.validateResources)(autoResult.resources),
+                    metadata: autoResult.metadata,
+                });
+                return { credential: stored, decisionSource: 'cached_vc' };
+            }
+        }
+        catch (err) {
+            // A Cedar forbid (403 policy_forbidden) is terminal — approval cannot
+            // lift it. Do NOT fall through to Step 4's risk-based approval routing
+            // (that would mint an un-redeemable OOB/in-band approval). Return a
+            // terminal denial so executeLocal/executeViaGateway surface
+            // `Permission denied: ...` with no approval prompt.
+            if (this.isPolicyForbiddenError(err)) {
+                const reason = this.policyForbiddenReason(err);
+                console.warn(`ensureVC: auto-issue forbidden by policy (terminal): ${reason}`);
+                return { denied: true, reason };
+            }
+            // Gateway unreachable for step 3 — continue to step 4
+        }
+        // Step 4: Risk-based approval routing
+        const riskLevel = this.getActionRiskLevel(action);
+        if (riskLevel === 'high' || riskLevel === 'critical') {
+            try {
+                return await this.createOOBApprovalRequest(action, provider, riskLevel, resourceInfo, input);
+            }
+            catch (err) {
+                return {
+                    denied: true,
+                    reason: `Failed to create out-of-band approval request: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        }
+        else {
+            return this.createInBandApprovalResponse(action, provider, riskLevel, approvedRequests, resourceInfo, input);
+        }
+    }
+    /**
+     * True when an error is a Cedar forbid 403 (policy_forbidden) from the gateway.
+     *
+     * Primary path: `gatewayClient.autoIssueVC` throws `GatewayHttpError` on any
+     * non-ok, carrying the 403 status + body — that's the branch that fires today.
+     * The plain-`Error` message fallback is intentionally retained (not dead): it
+     * is cheap defensive coverage for a future caller that surfaces the forbid as
+     * a wrapped/plain Error, and keeps parity with remote-mcp's message-only
+     * `isPolicyForbiddenError`. The `policy_forbidden` token is snake_case and
+     * unlikely to collide with unrelated error prose.
+     */
+    isPolicyForbiddenError(err) {
+        if (err instanceof gateway_client_1.GatewayHttpError) {
+            return err.status === 403 && (err.body?.includes('policy_forbidden') ?? false);
+        }
+        return err instanceof Error && err.message.includes('policy_forbidden');
+    }
+    policyForbiddenReason(err) {
+        const fallback = 'This action is forbidden by policy and cannot be approved ' +
+            '(e.g. outside the allowed time window). Adjust the policy if it should be allowed.';
+        if (err instanceof gateway_client_1.GatewayHttpError && err.body) {
+            try {
+                const parsed = JSON.parse(err.body);
+                if (parsed.message)
+                    return parsed.message;
+            }
+            catch { /* body not JSON — use fallback */ }
+        }
+        return fallback;
+    }
+    // ===========================================================================
+    // Local execution with VP verification (spec §7.4)
+    // ===========================================================================
+    async executeLocal(action, params, provider, normalizedResource, resourceFingerprint, requestedResource) {
+        const resourceInfo = normalizedResource && resourceFingerprint
+            ? { normalizedResource, fingerprint: resourceFingerprint }
+            : undefined;
+        // 1. Ensure VC (4-step acquisition)
+        const vcResult = await this.ensureVC(action, provider, resourceInfo, params);
+        if ('approvalRequired' in vcResult) {
+            return { success: false, approvalRequired: vcResult.approvalRequired };
+        }
+        if ('waitingForApproval' in vcResult) {
+            return { success: false, waitingForApproval: vcResult.waitingForApproval };
+        }
+        if ('denied' in vcResult) {
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'local',
+                decisionSource: 'local_policy',
+                decisionReason: vcResult.reason,
+                requestedResource,
+                normalizedResource,
+                resourceFingerprint,
+                executionType: 'local',
+            });
+            return { success: false, error: `Permission denied: ${vcResult.reason}` };
+        }
+        // 2. Execute with the acquired VC
+        return this.executeLocalWithVC(action, params, provider, vcResult, normalizedResource, resourceFingerprint, requestedResource);
+    }
+    /**
+     * Execute locally with an already-acquired VC (skips ensureVC).
+     * Used by both the normal path (after ensureVC) and handleApprovalResponse (after quickApprove).
+     */
+    async executeLocalWithVC(action, params, provider, vcResult, normalizedResource, resourceFingerprint, requestedResource, retryCount = 0) {
+        const executor = (0, executor_registry_1.getLocalExecutor)(action);
+        if (!executor) {
+            return { success: false, error: `No local executor for action: ${action}` };
+        }
+        // Try Gateway VP verification (online path)
+        let gatewayReachable = true;
+        try {
+            const { nonce } = await this.gatewayClient.issueNonce(this.context.agentDid);
+            let vpJwt;
+            let authResult;
+            try {
+                vpJwt = await this.vpBuilder.buildVP({
+                    credentialJwt: vcResult.credential.credentialJwt,
+                    signerDid: this.context.agentDid,
+                    signerPrivateKeyJwk: this.context.agentPrivateKeyJwk,
+                    nonce,
+                    domain: this.context.gatewayUrl,
+                });
+                authResult = await this.gatewayClient.verifyAndAuthorize(vpJwt, nonce, this.context.gatewayUrl, action, this.context.agentDid);
+            }
+            catch (buildErr) {
+                // VPBuilder.buildVP fails fast on an expired parent VC
+                // ("VC has expired") instead of producing a malformed presentation.
+                // Treat that as equivalent to the gateway returning a
+                // credential-invalid verdict, so the same retry / OOB fallback path
+                // below handles it. Without this, the throw would escape the outer
+                // try/catch (which only swallows GatewayNetworkError) and surface as
+                // a raw stack trace to the user.
+                if (buildErr instanceof gateway_client_1.GatewayNetworkError)
+                    throw buildErr;
+                const buildErrMsg = buildErr instanceof Error ? buildErr.message : String(buildErr);
+                if (!(0, credential_errors_1.isCredentialInvalidError)(buildErrMsg))
+                    throw buildErr;
+                authResult = { authorized: false, reason: buildErrMsg };
+            }
+            if (!authResult.authorized) {
+                // Check if the failure is due to credential expiration — attempt reissuance (max 1 retry)
+                if ((0, credential_errors_1.isCredentialInvalidError)(authResult.reason) && retryCount < 1) {
+                    this.wallet.revokeCredential(vcResult.credential.id);
+                    const resourceInfo = normalizedResource && resourceFingerprint
+                        ? { normalizedResource, fingerprint: resourceFingerprint }
+                        : undefined;
+                    const newVCResult = await this.ensureVC(action, provider, resourceInfo, params);
+                    if ('credential' in newVCResult) {
+                        return this.executeLocalWithVC(action, params, provider, newVCResult, normalizedResource, resourceFingerprint, requestedResource, retryCount + 1);
+                    }
+                    // ensureVC returned approval flow — pass through to caller
+                    if ('waitingForApproval' in newVCResult) {
+                        return { success: false, waitingForApproval: newVCResult.waitingForApproval };
+                    }
+                    if ('approvalRequired' in newVCResult) {
+                        return { success: false, approvalRequired: newVCResult.approvalRequired };
+                    }
+                    // ensureVC denied — return denial reason instead of original auth error
+                    if ('denied' in newVCResult) {
+                        return { success: false, error: `VC reissuance denied: ${newVCResult.reason}` };
+                    }
+                }
+                // After retry exhaustion, if still credential-invalid, fall back to OOB approval
+                // so the user gets an actionable re-authorization URL instead of a raw error.
+                if ((0, credential_errors_1.isCredentialInvalidError)(authResult.reason) && retryCount >= 1) {
+                    const resourceInfoForOOB = normalizedResource && resourceFingerprint
+                        ? { normalizedResource, fingerprint: resourceFingerprint }
+                        : undefined;
+                    const oobFallback = await this.tryOOBFallbackAfterRetryExhaustion(action, provider, vcResult.credential.id, params, resourceInfoForOOB, 'local');
+                    if (oobFallback)
+                        return oobFallback;
+                }
+                this.logAudit({
+                    action, provider,
+                    decision: 'deny',
+                    enforcementType: 'gateway_verified_local',
+                    decisionSource: vcResult.decisionSource,
+                    decisionReason: authResult.reason,
+                    requestedResource,
+                    normalizedResource,
+                    resourceFingerprint,
+                    executionType: 'local',
+                    grantId: authResult.grantId,
+                });
+                return { success: false, error: `Authorization denied: ${authResult.reason}` };
+            }
+            // Consume one-time grant BEFORE execution
+            const effectiveGrantId = authResult.grantId || vcResult.grantId;
+            if (effectiveGrantId && authResult.approvalMode === 'one_time') {
+                const consumeResult = await this.gatewayClient.consumeGrant(effectiveGrantId);
+                if (!consumeResult.consumed) {
+                    this.logAudit({
+                        action, provider,
+                        decision: 'deny',
+                        enforcementType: 'gateway_verified_local',
+                        decisionSource: vcResult.decisionSource,
+                        decisionReason: `Grant consumption failed: ${consumeResult.reason}`,
+                        requestedResource,
+                        normalizedResource,
+                        resourceFingerprint,
+                        executionType: 'local',
+                        grantId: effectiveGrantId,
+                    });
+                    return { success: false, error: `Grant consumption failed: ${consumeResult.reason}` };
+                }
+            }
+            // Execute locally — build context based on action type
+            let result;
+            if (action === 'os.process.run') {
+                const resolvedEnv = await this.resolveProcessEnv(params);
+                result = executor(params, { resolvedEnv });
+            }
+            else {
+                result = executor(params, {
+                    rootDid: this.context.rootDid,
+                    approvedResource: vcResult.credential.normalizedResourceKey,
+                    approvedFingerprint: vcResult.credential.resourceFingerprint,
+                });
+            }
+            this.logAudit({
+                action, provider,
+                decision: result.success ? 'allow' : 'deny',
+                enforcementType: 'gateway_verified_local',
+                decisionSource: vcResult.decisionSource,
+                requestedResource,
+                normalizedResource,
+                resourceFingerprint: result.resourceFingerprint || resourceFingerprint,
+                executionType: 'local',
+                grantId: effectiveGrantId || authResult.grantId,
+                credentialId: vcResult.credential.id,
+                approvalMode: vcResult.approvalMode,
+                approvalNonce: vcResult.approvalNonce,
+            });
+            return { success: result.success, data: result.data, error: result.error };
+        }
+        catch (err) {
+            if (!(err instanceof gateway_client_1.GatewayNetworkError))
+                throw err;
+            gatewayReachable = false;
+        }
+        if (!gatewayReachable) {
+            return this.executeLocalOffline(action, params, provider, vcResult, normalizedResource, resourceFingerprint, requestedResource);
+        }
+        return { success: false, error: `Unexpected execution state for ${action}` };
+    }
+    // ===========================================================================
+    // Offline fallback (spec §7.6)
+    // ===========================================================================
+    /**
+     * Execute locally when Gateway is unreachable.
+     * All 4 conditions from spec §7.6 must be true:
+     * 1. Valid cached VC exists
+     * 2. VC not expired
+     * 3. Synced org policy not stale (30 min TTL)
+     * 4. Local policy does not deny
+     */
+    async executeLocalOffline(action, params, provider, vcResult, normalizedResource, resourceFingerprint, requestedResource) {
+        // Condition 1: Valid cached VC exists (already guaranteed by ensureVC)
+        if (!vcResult.credential) {
+            return { success: false, error: 'Cannot execute offline: no cached VC' };
+        }
+        // Condition 2: VC not expired
+        if (vcResult.credential.expiresAt && vcResult.credential.expiresAt < Date.now()) {
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'cached_verified_local',
+                decisionSource: 'cached_vc',
+                decisionReason: 'VC expired during offline execution',
+                requestedResource,
+                normalizedResource,
+                resourceFingerprint,
+                executionType: 'local',
+            });
+            return { success: false, error: 'Cannot execute offline: cached VC expired' };
+        }
+        // Condition 3: Synced org policy not stale (30 min TTL)
+        if (!this.lastPolicySyncTime || (Date.now() - this.lastPolicySyncTime) > POLICY_SYNC_TTL_MS) {
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'cached_verified_local',
+                decisionSource: 'org_policy',
+                decisionReason: 'Org policy cache is stale or missing for offline execution',
+                requestedResource,
+                normalizedResource,
+                resourceFingerprint,
+                executionType: 'local',
+            });
+            return { success: false, error: 'Cannot execute offline: org policy cache is stale or has never been synced' };
+        }
+        // Condition 4: Local policy does not deny
+        const offlinePolicyCheck = this.policyEvaluator.evaluate(provider, action.replace(`${provider}.`, ''), {
+            type: this.getResourceType(action),
+            pattern: normalizedResource,
+        });
+        if (!offlinePolicyCheck.allowed) {
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'cached_verified_local',
+                decisionSource: 'local_policy',
+                decisionReason: offlinePolicyCheck.reason,
+                requestedResource,
+                normalizedResource,
+                resourceFingerprint,
+                executionType: 'local',
+            });
+            return { success: false, error: `Cannot execute offline: local policy denies: ${offlinePolicyCheck.reason}` };
+        }
+        // All conditions met — execute with cached_verified_local enforcement
+        const executor = (0, executor_registry_1.getLocalExecutor)(action);
+        if (!executor) {
+            return { success: false, error: `No local executor for action: ${action}` };
+        }
+        let result;
+        if (action === 'os.process.run') {
+            const resolvedEnv = await this.resolveProcessEnv(params);
+            result = executor(params, { resolvedEnv });
+        }
+        else {
+            result = executor(params, {
+                rootDid: this.context.rootDid,
+                approvedResource: vcResult.credential.normalizedResourceKey,
+                approvedFingerprint: vcResult.credential.resourceFingerprint,
+            });
+        }
+        this.logAudit({
+            action, provider,
+            decision: result.success ? 'allow' : 'deny',
+            enforcementType: 'cached_verified_local',
+            decisionSource: 'cached_vc',
+            requestedResource,
+            normalizedResource,
+            resourceFingerprint: result.resourceFingerprint || resourceFingerprint,
+            executionType: 'local',
+            credentialId: vcResult.credential.id,
+        });
+        return { success: result.success, data: result.data, error: result.error };
+    }
+    // ===========================================================================
+    // SaaS execution via Gateway (spec §7.4)
+    // ===========================================================================
+    async executeViaGateway(provider, action, params) {
+        // NEW: Resolve resource identifier to canonical ID
+        const extractedId = this.extractResourceIdFromInput(action, params);
+        let canonicalResourceId = extractedId;
+        if (extractedId) {
+            try {
+                const resolved = await this.gatewayClient.resolveResource({
+                    provider,
+                    resourceType: this.getResourceType(action),
+                    input: extractedId,
+                    projectId: this.context.projectId,
+                });
+                if (resolved.resolved) {
+                    canonicalResourceId = resolved.canonicalId;
+                }
+            }
+            catch {
+                // Resolution failed — continue with original input (best-effort)
+            }
+        }
+        // 1. Ensure VC (4-step acquisition) with resource context
+        const vcResult = await this.ensureVC(action, provider, undefined, params, canonicalResourceId);
+        if ('approvalRequired' in vcResult) {
+            return { success: false, approvalRequired: vcResult.approvalRequired };
+        }
+        if ('waitingForApproval' in vcResult) {
+            return { success: false, waitingForApproval: vcResult.waitingForApproval };
+        }
+        if ('denied' in vcResult) {
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'gateway',
+                decisionSource: 'local_policy',
+                decisionReason: vcResult.reason,
+                executionType: 'gateway',
+            });
+            return { success: false, error: `Permission denied: ${vcResult.reason}` };
+        }
+        // 2. Execute with the acquired VC
+        return this.executeViaGatewayWithVC(provider, action, params, vcResult, 0, canonicalResourceId);
+    }
+    async executeViaGatewayWithVC(provider, action, params, vcResult, retryCount = 0, canonicalResourceId) {
+        try {
+            const { nonce } = await this.gatewayClient.issueNonce(this.context.agentDid);
+            let result;
+            try {
+                const vpJwt = await this.vpBuilder.buildVP({
+                    credentialJwt: vcResult.credential.credentialJwt,
+                    signerDid: this.context.agentDid,
+                    signerPrivateKeyJwk: this.context.agentPrivateKeyJwk,
+                    nonce,
+                    domain: this.context.gatewayUrl,
+                });
+                result = await this.gatewayClient.invokeTool({
+                    action,
+                    parameters: params,
+                    holderDid: this.context.agentDid,
+                    vpJwt,
+                    vpChallenge: nonce,
+                    vpDomain: this.context.gatewayUrl,
+                });
+            }
+            catch (buildErr) {
+                // VPBuilder.buildVP fails fast on an expired parent VC
+                // ("VC has expired") instead of producing a malformed presentation.
+                // Synthesize a CREDENTIAL_INVALID InvokeToolResult so the existing
+                // retry / OOB fallback below handles it identically — without this,
+                // the throw would escape into the outer catch (which classifies any
+                // throw as "Gateway unreachable") and surface a misleading error.
+                if (buildErr instanceof gateway_client_1.GatewayNetworkError)
+                    throw buildErr;
+                const buildErrMsg = buildErr instanceof Error ? buildErr.message : String(buildErr);
+                if (!(0, credential_errors_1.isCredentialInvalidError)(buildErrMsg))
+                    throw buildErr;
+                result = {
+                    success: false,
+                    error: buildErrMsg,
+                    errorCode: ai_identity_1.GATEWAY_ERROR_CODE.CREDENTIAL_INVALID,
+                };
+            }
+            // Phase 2c-B — the api signaled a revoked/expired OAuth token. Do not
+            // retry: the VC is still valid locally but the upstream SaaS token is
+            // gone and won't return until the user clicks the authUrl. Surface the
+            // reauth payload so the CLI can render it.
+            //
+            // Scope note: reauth only originates here (the gateway path) because
+            // local actions (`os.*`) don't touch SaaS OAuth tokens. If a future
+            // local executor ever starts proxying SaaS calls, mirror this branch
+            // in `executeLocalWithVC` with `enforcementType: 'local'`.
+            if (!result.success && result.errorCode === ai_identity_1.GATEWAY_ERROR_CODE.REAUTH_REQUIRED && result.reauthRequired) {
+                this.logAudit({
+                    action, provider,
+                    decision: 'deny',
+                    enforcementType: 'gateway',
+                    decisionSource: 'gateway_execution',
+                    decisionReason: 'oauth_token_revoked',
+                    executionType: 'gateway',
+                    credentialId: vcResult.credential.id,
+                    grantId: vcResult.grantId,
+                    approvalMode: vcResult.approvalMode,
+                });
+                return {
+                    success: false,
+                    error: result.error,
+                    reauthRequired: {
+                        provider: result.reauthRequired.provider,
+                        reason: result.reauthRequired.reason,
+                        message: result.reauthRequired.message,
+                        authUrl: result.reauthRequired.authUrl,
+                        projectId: result.reauthRequired.projectId,
+                    },
+                };
+            }
+            // Cedar forbid — terminal. No re-approval, no retry (unlike
+            // CREDENTIAL_INVALID / RESOURCE_MISMATCH). Mirrors the api 403.
+            //
+            // TODO(audit-parity): this runtime path logs the structured
+            // `decisionReason: 'cedar_policy_forbidden'`, but a forbid surfaced via
+            // the Step-3 autoIssue path flows through the shared `{ denied: true }`
+            // sink in executeLocal/executeViaGateway, which logs the raw `reason`
+            // string instead. A log query keyed on `cedar_policy_forbidden` won't
+            // match Step-3 forbids. Unifying requires threading a structured source
+            // through the shared denied sink (used by ALL denials, not just forbid),
+            // so it's deferred rather than churned here.
+            if (!result.success && result.errorCode === ai_identity_1.GATEWAY_ERROR_CODE.POLICY_FORBIDDEN) {
+                this.logAudit({
+                    action, provider,
+                    decision: 'deny',
+                    enforcementType: 'gateway',
+                    decisionSource: 'gateway_execution',
+                    decisionReason: 'cedar_policy_forbidden',
+                    executionType: 'gateway',
+                    credentialId: vcResult.credential.id,
+                    grantId: vcResult.grantId,
+                    approvalMode: vcResult.approvalMode,
+                });
+                return {
+                    success: false,
+                    error: result.error ||
+                        'This action is forbidden by policy and cannot be approved. Adjust the policy if it should be allowed.',
+                };
+            }
+            // Invoke-time Cedar RequireApproval (HTTP 202 auth_required). The VC was
+            // already issued (so ensureVC's Step-4 approval routing was skipped), but
+            // the per-request evaluation still needs approval — e.g. a new recipient
+            // that fails the internal-domain fold. Unlike POLICY_FORBIDDEN this is
+            // lift-able: mint an OOB approval URL so the user can approve and retry.
+            // Reuses createOOBApprovalRequest (the same helper ensureVC Step-4 uses);
+            // resourceInfo is omitted because gateway resource resolution is
+            // server-side (mirrors tryOOBFallbackAfterRetryExhaustion). The api's 202
+            // carries no approvalUrl, which is why we create the request here rather
+            // than forwarding one.
+            // Structure mirrors handleResourceMismatch (the other OOB-minting branch):
+            // throttle guard first, audit BEFORE the try (so the denial is recorded
+            // whether or not OOB creation succeeds), then mint → track.
+            if (!result.success && result.errorCode === ai_identity_1.GATEWAY_ERROR_CODE.APPROVAL_REQUIRED) {
+                const extractedId = this.extractResourceIdFromInput(action, params);
+                // Dedup: a buggy server that returns 202 on every call would otherwise
+                // mint a fresh approval request each time. Same guard as the
+                // resource-mismatch reapproval path.
+                if (this.isRecentOOBRequest(action, extractedId)) {
+                    return {
+                        success: false,
+                        error: 'An approval request was recently created. Please approve it or wait before retrying.',
+                    };
+                }
+                this.logAudit({
+                    action, provider,
+                    decision: 'deny',
+                    enforcementType: 'gateway',
+                    decisionSource: 'gateway_execution',
+                    decisionReason: 'cedar_auth_required',
+                    executionType: 'gateway',
+                    credentialId: vcResult.credential.id,
+                    grantId: vcResult.grantId,
+                    approvalMode: vcResult.approvalMode,
+                });
+                const riskLevel = this.getActionRiskLevel(action);
+                try {
+                    const oob = await this.createOOBApprovalRequest(action, provider, riskLevel, undefined, params);
+                    this.trackOOBRequest(action, extractedId);
+                    return { success: false, waitingForApproval: oob.waitingForApproval };
+                }
+                catch (oobErr) {
+                    // OOB creation failed — surface the auth_required without a URL
+                    // rather than crashing (mirrors the callTool fall-through in
+                    // remote-mcp). Prepend the failure context instead of `||`-ing it:
+                    // the api always supplies `result.error` ("Approval required …"),
+                    // which would otherwise mask WHY no clickable URL appeared.
+                    const base = result.error || `Approval required for ${action}`;
+                    return {
+                        success: false,
+                        error: `${base} — creating the approval request failed: ` +
+                            `${oobErr instanceof Error ? oobErr.message : String(oobErr)}`,
+                    };
+                }
+            }
+            // Detect resource mismatch from structured error code
+            if (!result.success && result.errorCode === ai_identity_1.GATEWAY_ERROR_CODE.RESOURCE_MISMATCH) {
+                return this.handleResourceMismatch(action, provider, params, vcResult);
+            }
+            // Detect credential-invalid errors and attempt VC reissuance (max 1 retry)
+            if (!result.success && result.errorCode === ai_identity_1.GATEWAY_ERROR_CODE.CREDENTIAL_INVALID && retryCount < 1) {
+                this.wallet.revokeCredential(vcResult.credential.id);
+                const newVCResult = await this.ensureVC(action, provider, undefined, params, canonicalResourceId);
+                if ('credential' in newVCResult) {
+                    return this.executeViaGatewayWithVC(provider, action, params, newVCResult, retryCount + 1, canonicalResourceId);
+                }
+                // ensureVC returned approval flow — pass through to caller
+                if ('waitingForApproval' in newVCResult) {
+                    return { success: false, waitingForApproval: newVCResult.waitingForApproval };
+                }
+                if ('approvalRequired' in newVCResult) {
+                    return { success: false, approvalRequired: newVCResult.approvalRequired };
+                }
+                // ensureVC denied — return denial reason
+                if ('denied' in newVCResult) {
+                    return { success: false, error: `VC reissuance denied: ${newVCResult.reason}` };
+                }
+                // Could not re-acquire VC — return the original error
+                return { success: false, error: result.error };
+            }
+            // After retry exhaustion, if still CREDENTIAL_INVALID, fall back to OOB approval
+            // so the user gets an actionable re-authorization URL instead of a raw error.
+            if (!result.success && result.errorCode === ai_identity_1.GATEWAY_ERROR_CODE.CREDENTIAL_INVALID && retryCount >= 1) {
+                // Gateway path does not have normalizedResource/resourceFingerprint in scope
+                // (resource resolution happens server-side), so resourceInfo is omitted.
+                const oobFallback = await this.tryOOBFallbackAfterRetryExhaustion(action, provider, vcResult.credential.id, params);
+                if (oobFallback)
+                    return oobFallback;
+            }
+            this.logAudit({
+                action, provider,
+                decision: result.success ? 'allow' : 'deny',
+                enforcementType: 'gateway',
+                decisionSource: vcResult.decisionSource,
+                decisionReason: result.error,
+                executionType: 'gateway',
+                credentialId: vcResult.credential.id,
+                grantId: vcResult.grantId,
+                approvalMode: vcResult.approvalMode,
+                approvalNonce: vcResult.approvalNonce,
+            });
+            return { success: result.success, data: result.data, error: result.error };
+        }
+        catch (err) {
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'gateway',
+                decisionSource: 'gateway_execution',
+                decisionReason: `Gateway unreachable: ${err instanceof Error ? err.message : String(err)}`,
+                executionType: 'gateway',
+            });
+            return {
+                success: false,
+                error: `Gateway required for SaaS operations but unreachable: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    // ===========================================================================
+    // OOB approval methods
+    // ===========================================================================
+    /**
+     * Handle a re-invocation with pendingRequestId (OOB approval polling).
+     */
+    async handlePendingApproval(request) {
+        const { action, pendingRequestId } = request;
+        if (!pendingRequestId) {
+            return { success: false, error: 'No pendingRequestId provided' };
+        }
+        let statusResult;
+        try {
+            statusResult = await this.gatewayClient.getApprovalStatus(pendingRequestId);
+        }
+        catch (err) {
+            return { success: false, error: `Failed to check approval status: ${err instanceof Error ? err.message : String(err)}` };
+        }
+        // Security: verify that the re-invoked action matches what was originally approved
+        if (statusResult.actions && !statusResult.actions.includes(action)) {
+            return {
+                success: false,
+                error: `Action mismatch: approval was for [${statusResult.actions.join(', ')}], but re-invoked with "${action}"`,
+            };
+        }
+        // Security: verify that the re-invoked resource matches what was originally approved
+        if (statusResult.resources?.length) {
+            const extractedId = this.extractResourceIdFromInput(action, request.input);
+            if (extractedId) {
+                // For local actions, the approval stores canonicalized paths — canonicalize the input too
+                const normalizedId = (0, executor_registry_1.isLocalAction)(action) && request.input.file_path
+                    ? (0, resource_canonicalizer_1.canonicalizePath)(request.input.file_path)
+                    : extractedId;
+                const approvedResources = statusResult.resources;
+                // 🪤 The SAME predicate exists at the post-claim re-validation below
+                // (~:1310). Both must agree: this one runs on `request.input`, that one
+                // on the stored `actionParams`, and the live 2026-07-30 calendar bug
+                // reached BOTH. Keep them in lock-step via `approvedResourceMatches`.
+                const resourceMatch = this.approvedResourceMatches(approvedResources, extractedId, normalizedId);
+                if (!resourceMatch) {
+                    return {
+                        success: false,
+                        error: `Resource mismatch: approval was for [${approvedResources.map((r) => r.id || r.pattern).join(', ')}], but re-invoked with "${extractedId}"`,
+                    };
+                }
+            }
+        }
+        if (statusResult.status === 'denied') {
+            const provider = action.split('.')[0];
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'gateway',
+                decisionSource: 'org_policy',
+                decisionReason: 'User denied the OOB approval request',
+                executionType: (0, executor_registry_1.isLocalAction)(action) ? 'local' : 'gateway',
+            });
+            return { success: false, error: 'Approval request was denied by the user' };
+        }
+        if (statusResult.status === 'expired') {
+            return { success: false, error: 'Approval request has expired. Please try again.' };
+        }
+        if (statusResult.status === 'consumed') {
+            return { success: false, error: 'Approval was already claimed by another session. Please request a new approval.' };
+        }
+        if (statusResult.status === 'pending') {
+            const rawExpiry = statusResult.requestExpiresAt
+                ? Math.floor((new Date(statusResult.requestExpiresAt).getTime() - Date.now()) / 1000)
+                : NaN;
+            const expiresIn = Number.isNaN(rawExpiry) ? OOB_APPROVAL_DEFAULT_EXPIRES_IN_SECONDS : Math.max(0, rawExpiry);
+            return {
+                success: false,
+                waitingForApproval: {
+                    status: 'waiting_for_approval',
+                    approvalUrl: statusResult.approvalUrl || 'Use the URL from your initial request',
+                    requestId: pendingRequestId,
+                    action,
+                    riskLevel: this.getActionRiskLevel(action),
+                    expiresIn,
+                    message: 'Still waiting for approval. Please approve in your browser.',
+                },
+            };
+        }
+        // approved — claim VC, store, and execute directly
+        if (statusResult.status === 'approved') {
+            const provider = action.split('.')[0];
+            let claimed;
+            try {
+                claimed = await this.gatewayClient.claimVC(pendingRequestId, this.context.agentDid);
+            }
+            catch (claimErr) {
+                const msg = claimErr instanceof Error ? claimErr.message : String(claimErr);
+                if (msg === 'CLAIM_CONSUMED') {
+                    return { success: false, error: 'Approval was already claimed by another session' };
+                }
+                if (msg === 'CLAIM_EXPIRED') {
+                    return { success: false, error: 'Approval request has expired. Please try again.' };
+                }
+                return { success: false, error: `Failed to claim VC: ${msg}` };
+            }
+            // Use stored actionParams from approval request (approved for these exact params).
+            // Fall back to request.input only for legacy requests where actionParams is unavailable.
+            const rawStoredParams = claimed.actionParams;
+            const storedParams = rawStoredParams && Object.keys(rawStoredParams).length > 0
+                ? rawStoredParams
+                : undefined;
+            const effectiveInput = storedParams
+                ?? (Object.keys(request.input).length > 0 ? request.input : null);
+            if (!effectiveInput) {
+                return { success: false, error: 'Action parameters could not be restored. Please retry with explicit parameters.' };
+            }
+            // Security: re-validate resource constraint using effectiveInput (defense-in-depth)
+            // The pre-claim check (line 838) may have been skipped when request.input was empty.
+            if (statusResult.resources?.length) {
+                const extractedId = this.extractResourceIdFromInput(action, effectiveInput);
+                if (extractedId) {
+                    const normalizedId = (0, executor_registry_1.isLocalAction)(action) && effectiveInput.file_path
+                        ? (0, resource_canonicalizer_1.canonicalizePath)(effectiveInput.file_path)
+                        : extractedId;
+                    const approvedResources = statusResult.resources;
+                    // Same predicate as the pre-claim check (~:1213) — see the note there.
+                    const resourceMatch = this.approvedResourceMatches(approvedResources, extractedId, normalizedId);
+                    if (!resourceMatch) {
+                        return {
+                            success: false,
+                            error: `Resource mismatch: approval was for [${approvedResources.map((r) => r.id || r.pattern).join(', ')}], but effective input resolves to "${extractedId}"`,
+                        };
+                    }
+                }
+            }
+            const stored = this.wallet.storeCredential({
+                holderDid: this.context.agentDid,
+                projectId: this.context.projectId,
+                credentialJwt: claimed.credential.jwt,
+                actions: claimed.actions.length ? claimed.actions : [action],
+                provider,
+                expiresAt: claimed.credential.expiresAt,
+                resources: (0, wallet_1.validateResources)(claimed.resources),
+            });
+            // Build VCAcquired and execute directly (skip re-enter via this.execute)
+            const vcAcquired = {
+                credential: stored,
+                approvalMode: 'one_time',
+                decisionSource: 'claimed_from_approval',
+            };
+            const routing = (0, executor_registry_1.determineRouting)(provider, action);
+            let executeResult;
+            const normalizedResource = (0, executor_registry_1.isLocalAction)(action) && effectiveInput.file_path
+                ? (0, resource_canonicalizer_1.canonicalizePath)(effectiveInput.file_path)
+                : undefined;
+            const resourceFingerprint = normalizedResource
+                ? (0, resource_canonicalizer_1.computeFingerprint)(normalizedResource, this.context.rootDid)
+                : undefined;
+            try {
+                if (routing.executor === 'local') {
+                    executeResult = await this.executeLocalWithVC(action, effectiveInput, provider, vcAcquired, normalizedResource, resourceFingerprint, effectiveInput.file_path);
+                }
+                else {
+                    executeResult = await this.executeViaGatewayWithVC(provider, action, effectiveInput, vcAcquired);
+                }
+            }
+            finally {
+                // Wallet cleanup for OOB one-time credentials
+                if (stored?.id) {
+                    this.wallet.revokeCredential(stored.id);
+                }
+            }
+            return executeResult;
+        }
+        return { success: false, error: `Unexpected approval status: ${statusResult.status}` };
+    }
+    /**
+     * Create an OOB (out-of-band) approval request.
+     * Returns a URL for the user to approve in their browser.
+     *
+     * Called in two contexts:
+     * - ensureVC Step 4: for high/critical risk actions that require browser approval.
+     * - tryOOBFallbackAfterRetryExhaustion: for ANY risk level when a VC expires
+     *   mid-execution and retry is exhausted. In this case OOB is used as a fallback
+     *   because the normal in-band flow cannot recover an expired credential — the
+     *   user must re-authorize via browser regardless of risk level.
+     */
+    async createOOBApprovalRequest(action, provider, riskLevel, resourceInfo, input) {
+        const resourceType = this.getResourceType(action);
+        const extractedId = this.extractResourceIdFromInput(action, input);
+        const resources = resourceInfo
+            ? [{ provider, type: resourceType, pattern: resourceInfo.normalizedResource }]
+            : extractedId
+                ? [{ provider, type: resourceType, id: extractedId }]
+                : [{ provider, type: resourceType }];
+        try {
+            const result = await this.gatewayClient.createApprovalRequest({
+                subjectDid: this.context.agentDid,
+                projectId: this.context.projectId,
+                actions: [action],
+                resources,
+                actionParams: input,
+            });
+            const rawExpiry = result.expiresAt
+                ? Math.floor((new Date(result.expiresAt).getTime() - Date.now()) / 1000)
+                : NaN;
+            const expiresIn = Number.isNaN(rawExpiry) ? OOB_APPROVAL_DEFAULT_EXPIRES_IN_SECONDS : Math.max(0, rawExpiry);
+            return {
+                waitingForApproval: {
+                    status: 'waiting_for_approval',
+                    approvalUrl: result.approvalUrl,
+                    requestId: result.requestId,
+                    action,
+                    resource: resourceInfo?.normalizedResource ?? extractedId,
+                    riskLevel,
+                    expiresIn,
+                    message: `This ${riskLevel}-risk action requires browser approval (login required). Open the URL to approve.`,
+                },
+            };
+        }
+        catch (err) {
+            throw new Error(`Failed to create OOB approval request: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Revoke the stale credential and attempt to create an OOB approval request
+     * as a fallback after retry exhaustion. Returns an ExecuteResult with
+     * waitingForApproval on success, or null if OOB creation fails (caller falls
+     * through to the original error).
+     */
+    async tryOOBFallbackAfterRetryExhaustion(action, provider, credentialId, params, resourceInfo, executionType = 'gateway') {
+        const enforcementType = executionType === 'local' ? 'gateway_verified_local' : 'gateway';
+        this.wallet.revokeCredential(credentialId);
+        try {
+            const riskLevel = this.getActionRiskLevel(action);
+            const oobResult = await this.createOOBApprovalRequest(action, provider, riskLevel, resourceInfo, params);
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType,
+                decisionSource: 'gateway_execution',
+                decisionReason: `Credential expired after retry — OOB approval requested (requestId=${oobResult.waitingForApproval.requestId})`,
+                executionType,
+                credentialId,
+            });
+            return { success: false, waitingForApproval: oobResult.waitingForApproval };
+        }
+        catch (err) {
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType,
+                decisionSource: 'gateway_execution',
+                decisionReason: `OOB approval fallback failed after retry exhaustion: ${err instanceof Error ? err.message : String(err)}`,
+                executionType,
+                credentialId,
+            });
+            return null;
+        }
+    }
+    /**
+     * Create an in-band approval response for low/medium risk actions.
+     * Generates an approval token for the MCP client to present back.
+     */
+    createInBandApprovalResponse(action, _provider, riskLevel, approvedRequests, resourceInfo, input = {}) {
+        const defaultTTL = this.getDefaultVCTTL(riskLevel);
+        // Determine context using cached result from Step 2
+        let approvalContext = 'new_approval';
+        if (approvedRequests && approvedRequests.some(r => r.actions?.includes(action))) {
+            approvalContext = 'reconfirmation';
+        }
+        // Narrow resource: use normalized path for local actions, or extract resource ID for SaaS actions
+        const extractedResource = this.extractResourceIdFromInput(action, input);
+        const tokenResource = resourceInfo?.normalizedResource ?? extractedResource;
+        const approvalToken = this.tokenService.generate({
+            action,
+            scope: action,
+            resource: tokenResource,
+            context: approvalContext,
+        });
+        return {
+            approvalRequired: {
+                status: 'approval_required',
+                action,
+                description: `Execute ${action}`,
+                scope: action,
+                resource: tokenResource,
+                riskLevel,
+                options: ['one_time', 'persistent', 'deny_once', 'deny_persistent'],
+                suggestedTTL: defaultTTL,
+                maxTTL: { minutes: 1440, label: '24 hours' },
+                approvalToken,
+                context: approvalContext,
+            },
+        };
+    }
+    // ===========================================================================
+    // Utility methods
+    // ===========================================================================
+    /**
+     * Pre-request permissions for multiple actions (batch).
+     * Triggers VC acquisition for each action without executing.
+     * This allows the user to approve multiple actions at once.
+     */
+    async requestPermissions(actions) {
+        const approved = [];
+        const denied = [];
+        const pending = [];
+        for (const action of actions) {
+            const provider = action.split('.')[0];
+            // Policy check
+            const policyResult = this.policyEvaluator.evaluate(provider, action.replace(`${provider}.`, ''), { type: this.getResourceType(action) });
+            if (!policyResult.allowed) {
+                denied.push(action);
+                continue;
+            }
+            // Try VC acquisition (steps 1-3 only, no terminal prompt for batch)
+            try {
+                const walletVC = this.wallet.findCredential(this.context.agentDid, action, this.context.projectId);
+                if (walletVC) {
+                    approved.push(action);
+                    continue;
+                }
+                // Try auto-issue
+                const autoResult = await this.gatewayClient.autoIssueVC({
+                    subjectDid: this.context.agentDid,
+                    projectId: this.context.projectId,
+                    actions: [action],
+                });
+                if (autoResult?.autoIssued && autoResult.credential) {
+                    this.wallet.storeCredential({
+                        holderDid: this.context.agentDid,
+                        projectId: this.context.projectId,
+                        credentialJwt: autoResult.credential.jwt,
+                        actions: autoResult.actions || [action],
+                        provider,
+                        expiresAt: autoResult.credential.expiresAt,
+                        resources: (0, wallet_1.validateResources)(autoResult.resources),
+                        metadata: autoResult.metadata,
+                    });
+                    approved.push(action);
+                    continue;
+                }
+                pending.push(action);
+            }
+            catch {
+                pending.push(action);
+            }
+        }
+        const allApproved = denied.length === 0 && pending.length === 0;
+        // Create approval URL for pending actions (matches remote-mcp behavior)
+        if (pending.length > 0) {
+            try {
+                const approvalResult = await this.gatewayClient.createApprovalRequest({
+                    subjectDid: this.context.agentDid,
+                    projectId: this.context.projectId,
+                    actions: pending,
+                });
+                if (!approvalResult.approvalUrl) {
+                    throw new Error('Gateway returned empty approval URL');
+                }
+                return {
+                    success: true,
+                    data: {
+                        approved,
+                        denied,
+                        pending,
+                        requestId: approvalResult.requestId,
+                        approvalUrl: approvalResult.approvalUrl,
+                        expiresAt: approvalResult.expiresAt,
+                        status: 'pending',
+                        message: approved.length > 0
+                            ? `Approved: [${approved.join(', ')}]. Approval required for: [${pending.join(', ')}]. See approvalUrl field.`
+                            : `Permission required for: [${pending.join(', ')}]. See approvalUrl field.`,
+                    },
+                };
+            }
+            catch (err) {
+                // Fallback: return pending without URL if approval request creation fails
+                return {
+                    success: true,
+                    data: {
+                        approved,
+                        denied,
+                        pending,
+                        status: 'partial',
+                        message: `Approved: [${approved.join(', ')}]. Pending: [${pending.join(', ')}]. Denied: [${denied.join(', ')}]. Failed to create approval URL: ${err instanceof Error ? err.message : String(err)}. Use aidentity_call_tool for pending actions — you will be prompted to approve.`,
+                    },
+                };
+            }
+        }
+        return {
+            success: true,
+            data: {
+                approved,
+                denied,
+                pending,
+                status: allApproved ? 'approved' : 'partial',
+                message: allApproved
+                    ? 'All requested permissions have been granted. You can now use aidentity_call_tool.'
+                    : `Approved: [${approved.join(', ')}]. Denied: [${denied.join(', ')}].`,
+            },
+        };
+    }
+    async listAvailableTools() {
+        const tools = ai_identity_1.ACTION_REGISTRY.actions.map(a => ({
+            action: a.action,
+            resource_type: a.resource_type,
+            risk: a.risk,
+            input_schema: a.input_schema,
+        }));
+        return { success: true, data: { tools, count: tools.length } };
+    }
+    /**
+     * Resolve env vars for os.process.run from .env file.
+     * Returns empty record if no env_profile specified or .env not found.
+     */
+    async resolveProcessEnv(params) {
+        if (!this.secretBackend || !params.env_profile) {
+            return {};
+        }
+        const envPath = path.join(params.working_directory || process.cwd(), '.env');
+        try {
+            const content = fs.readFileSync(envPath, 'utf-8');
+            const envResolver = new env_resolver_1.EnvResolver(this.secretBackend);
+            const { env, warnings } = await envResolver.resolveEnvContentWithWarnings(content);
+            for (const w of warnings) {
+                process.stderr.write(`[vess] Warning: ${w}\n`);
+            }
+            return env;
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT') {
+                process.stderr.write(`[vess] Warning: env_profile "${params.env_profile}" requested but .env not found at ${envPath}\n`);
+                return {};
+            }
+            // Resolution errors (keychain failures, etc.) should propagate
+            throw err;
+        }
+    }
+    getActionRiskLevel(action) {
+        const actionDef = ai_identity_1.ACTION_REGISTRY.actions.find(a => a.action === action);
+        if (!actionDef) {
+            process.stderr.write(`[vess] WARNING: action "${action}" not found in ACTION_REGISTRY, defaulting to high risk\n`);
+            return 'high';
+        }
+        return actionDef.risk || 'high';
+    }
+    getDefaultVCTTL(riskLevel) {
+        const defaults = {
+            low: { minutes: 60, label: '1 hour (low risk default)' },
+            medium: { minutes: 30, label: '30 minutes (medium risk default)' },
+            high: { minutes: 10, label: '10 minutes (high risk default)' },
+            critical: { minutes: 5, label: '5 minutes (critical risk default)' },
+        };
+        return defaults[riskLevel];
+    }
+    async handleApprovalResponse(request, provider, normalizedResource, resourceFingerprint, requestedResource) {
+        const { action, approval } = request;
+        if (!approval)
+            return { success: false, error: 'No approval provided' };
+        // Verify token (with resource binding for both local and SaaS actions)
+        const extractedResource = this.extractResourceIdFromInput(action, request.input);
+        const expectedResource = normalizedResource ?? extractedResource;
+        const tokenResult = this.tokenService.verify(approval.token, action, expectedResource);
+        if (!tokenResult.valid) {
+            return { success: false, error: `Invalid approval token: ${tokenResult.error}` };
+        }
+        // Validate choice
+        const validChoices = ['one_time', 'persistent', 'deny_once', 'deny_persistent'];
+        if (!validChoices.includes(approval.choice)) {
+            return { success: false, error: `Invalid approval choice: ${approval.choice}` };
+        }
+        // Handle deny choices
+        if (approval.choice === 'deny_once') {
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'local',
+                decisionSource: 'local_policy',
+                decisionReason: 'User denied the action (deny_once)',
+                requestedResource, normalizedResource, resourceFingerprint,
+                executionType: (0, executor_registry_1.isLocalAction)(action) ? 'local' : 'gateway',
+                approvalNonce: tokenResult.nonce,
+            });
+            return { success: false, error: 'User denied the action (this time only)' };
+        }
+        if (approval.choice === 'deny_persistent') {
+            this.policyEvaluator.addDenyRule({
+                actions: [action],
+                effect: 'deny',
+                source: 'user',
+            });
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType: 'local',
+                decisionSource: 'local_policy',
+                decisionReason: 'User denied the action (deny_persistent)',
+                requestedResource, normalizedResource, resourceFingerprint,
+                executionType: (0, executor_registry_1.isLocalAction)(action) ? 'local' : 'gateway',
+                approvalNonce: tokenResult.nonce,
+            });
+            return { success: false, error: 'User denied the action (persistent deny rule added)' };
+        }
+        // Approved (one_time or persistent) — call quickApprove
+        const approvalMode = approval.choice === 'one_time' ? 'one_time' : 'persistent';
+        const resourceInfo = normalizedResource && resourceFingerprint
+            ? { normalizedResource, fingerprint: resourceFingerprint }
+            : undefined;
+        // Cedar 一元化 Step 3.5 retry path (client side): if the approval payload
+        // carries the full set of `ApprovalContext` fields (request_id +
+        // outcome_id + granted_at + granted_by), re-invoke `ensureVC` with the
+        // context threaded so `autoIssueVC` consumes the ledger token and Cedar
+        // flips `auth_required` → `permit`. If `autoIssueVC` returns a
+        // credential, we execute directly with it; otherwise we fall back to the
+        // legacy `quickApprove` path below so non-Cedar grants continue to work.
+        if (approval.request_id &&
+            approval.outcome_id &&
+            approval.granted_at &&
+            approval.granted_by) {
+            try {
+                const approvalContext = {
+                    token: approval.token,
+                    request_id: approval.request_id,
+                    outcome_id: approval.outcome_id,
+                    granted: true,
+                    granted_at: approval.granted_at,
+                    granted_by: approval.granted_by,
+                };
+                const cedarResult = await this.ensureVC(action, provider, resourceInfo, request.input, 
+                // Cedar retry path assumes no usable wallet VC (user just approved
+                // an auth_required action); skip the scoped wallet lookup (Step 1a)
+                // by passing canonicalResourceId=undefined and let ensureVC fall
+                // through to the autoIssueVC path with approval_context injected.
+                undefined, approvalContext);
+                if ('credential' in cedarResult) {
+                    const routing = (0, executor_registry_1.determineRouting)(provider, action);
+                    try {
+                        if (routing.executor === 'local') {
+                            return await this.executeLocalWithVC(action, request.input, provider, cedarResult, normalizedResource, resourceFingerprint, requestedResource);
+                        }
+                        return await this.executeViaGatewayWithVC(provider, action, request.input, cedarResult);
+                    }
+                    finally {
+                        if (approvalMode === 'one_time' && cedarResult.credential.id) {
+                            this.wallet.revokeCredential(cedarResult.credential.id);
+                        }
+                    }
+                }
+                // ensureVC did not produce a credential (e.g. legacy grant without
+                // Cedar policy_ref) — fall through to the quickApprove path.
+            }
+            catch (err) {
+                // Cedar retry path failed (network error etc.) — log and fall through
+                // to the legacy quickApprove fallback so the user still gets a usable
+                // VC path. The retry-with-approval_context is best-effort; the legacy
+                // quickApprove is the resilient fallback that does not require Cedar
+                // policy_ref. This keeps UX intact when the gateway has a transient
+                // failure between approval and VC issuance.
+                console.warn(`[ExecutionEngine] Cedar retry failed, falling back to quickApprove: ${err instanceof Error ? err.message : String(err)}`);
+                // fall through to quickApprove
+            }
+        }
+        // Determine VC TTL
+        const riskLevel = this.getActionRiskLevel(action);
+        const defaultTTL = this.getDefaultVCTTL(riskLevel);
+        const vcTTLMinutes = approval.vcTTLMinutes
+            ? Math.max(5, Math.min(1440, approval.vcTTLMinutes))
+            : defaultTTL.minutes;
+        const expiresInHours = vcTTLMinutes / 60;
+        // Build resources: for local actions use pattern, for gateway actions extract resource ID from parameters
+        const resourceType = this.getResourceType(action);
+        let resources;
+        if (resourceInfo) {
+            resources = [{ type: resourceType, pattern: resourceInfo.normalizedResource }];
+        }
+        else {
+            const extractedId = this.extractResourceIdFromInput(action, request.input);
+            // 'critical' refuses wildcard like 'high' (PR #931 review — same tier
+            // handling as the checks at lines ~350/~515 above; a critical action
+            // slipping through here would bake an unbound delegate that the api's
+            // Gate-2 strict arm then deterministically denies).
+            const wildcardRefuseRisk = this.getActionRiskLevel(action);
+            if (!extractedId && (wildcardRefuseRisk === 'high' || wildcardRefuseRisk === 'critical')) {
+                const actionDef = ai_identity_1.ACTION_REGISTRY.actions.find(a => a.action === action);
+                const paramName = actionDef?.target_bindings?.resource_id?.param || 'resource ID';
+                return {
+                    success: false,
+                    error: `High-risk action "${action}" requires a specific ${paramName}. Cannot approve with wildcard resource scope.`,
+                };
+            }
+            resources = extractedId
+                ? [{ type: resourceType, id: extractedId }]
+                : [{ type: resourceType }];
+        }
+        try {
+            const quickResult = await this.gatewayClient.quickApprove({
+                actions: [action],
+                resources,
+                normalizedResource: resourceInfo?.normalizedResource,
+                resourceFingerprint: resourceInfo?.fingerprint,
+                subjectDid: this.context.agentDid,
+                projectId: this.context.projectId,
+                issueVC: true,
+                approvalMode,
+                approvalNonce: tokenResult.nonce,
+                expiresInHours,
+            });
+            const stored = this.wallet.storeCredential({
+                holderDid: this.context.agentDid,
+                projectId: this.context.projectId,
+                credentialJwt: quickResult.credential,
+                actions: quickResult.grant.actions,
+                provider,
+                expiresAt: new Date(quickResult.expiresAt).getTime(),
+                normalizedResourceKey: resourceInfo?.normalizedResource,
+                resourceFingerprint: resourceInfo?.fingerprint,
+                resources: (0, wallet_1.validateResources)(quickResult.resources),
+            });
+            // Build VCAcquired from quickApprove result
+            const vcAcquired = {
+                credential: stored,
+                grantId: quickResult.grant.id,
+                approvalMode: approvalMode,
+                approvalNonce: tokenResult.nonce,
+                decisionSource: 'new_vc_from_quick_approve',
+            };
+            // Now execute with the freshly acquired VC (skips double ensureVC)
+            const routing = (0, executor_registry_1.determineRouting)(provider, action);
+            let executeResult;
+            try {
+                if (routing.executor === 'local') {
+                    executeResult = await this.executeLocalWithVC(action, request.input, provider, vcAcquired, normalizedResource, resourceFingerprint, requestedResource);
+                }
+                else {
+                    executeResult = await this.executeViaGatewayWithVC(provider, action, request.input, vcAcquired);
+                }
+            }
+            finally {
+                // Wallet cleanup for one-time grants (regardless of execution success — spec requirement)
+                if (approvalMode === 'one_time' && stored.id) {
+                    this.wallet.revokeCredential(stored.id);
+                }
+            }
+            return executeResult;
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `Quick-approve failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    getResourceType(action) {
+        const actionDef = ai_identity_1.ACTION_REGISTRY.actions.find(a => a.action === action);
+        if (actionDef) {
+            const parts = actionDef.resource_type.split(':');
+            return parts.length > 1 ? parts[1] : parts[0];
+        }
+        return '*';
+    }
+    /**
+     * Extract specific resource ID from action input using ACTION_REGISTRY target_bindings.
+     * For gateway (SaaS) actions, the resource ID (e.g., channel ID) is in the input parameters.
+     * Returns undefined for actions without param-sourced bindings or when the param is absent
+     * (e.g., target_bindings with required: false).
+     */
+    extractResourceIdFromInput(action, input) {
+        // #884 Task 4b — single canonical normalizer so agentd-issued VCs carry the
+        // SAME resource id the gateway Gate-2 enforces (github → owner/repo, not bare
+        // repo; jira → RAW issue key, downstream resolvers own derivation).
+        const value = (0, ai_identity_1.canonicalResourceId)(action, input);
+        if (value == null)
+            return undefined;
+        // Defense-in-depth: reject control characters and excessively long values.
+        const MAX_RESOURCE_ID_LENGTH = 500;
+        if (value.length > MAX_RESOURCE_ID_LENGTH || /[\x00-\x1f]/.test(value))
+            return undefined;
+        return value;
+    }
+    /**
+     * #1009 — this OOB re-invocation check is agentd's own defense-in-depth
+     * resource re-validation, separate from Gate-2's Cedar resolver in
+     * packages/api. #893 taught Gate-2's JiraResourceResolver that a
+     * project-scoped grant (e.g. "AIDENTITY") legitimately covers an
+     * issue-scoped request (e.g. "AIDENTITY-127"), but that fix never touched
+     * this agentd-side check, which stayed a plain string comparison. A grant
+     * that Gate-2 correctly approved would then be rejected here on re-invoke,
+     * permanently: the approval never resolves. Mirror the same hierarchy
+     * check so both enforcement paths agree.
+     *
+     * TODO(provider-generic): this is Jira-only by construction —
+     * `extractProjectKey` parses the Jira `KEY-123` shape, and the sole caller
+     * gates on `r.provider === 'jira'` (~:1216). packages/api expresses the same
+     * idea through `ResourceResolverRegistry` + `supportsHierarchicalMatch()`,
+     * so a second provider that needs hierarchy (e.g. GitHub org → repo) would
+     * have to be added in BOTH places, in two different shapes.
+     *
+     * Deliberately not abstracted yet: agentd is a local daemon that does not
+     * share the API's DI container or resolver registry, so mirroring that
+     * abstraction here means either duplicating the registry or extracting it
+     * into the SDK — real work that one provider does not justify. Jira is
+     * currently the only registered hierarchical resolver.
+     *
+     * When a second one appears, extract the resolver interface into the SDK
+     * (alongside `extractProjectKey`, which already lives there) and have both
+     * enforcement paths consume it, rather than adding a second `provider ===`
+     * branch here. 🪤 The hazard this guards against is silent divergence: if
+     * the two paths disagree about what a grant covers, Gate-2 approves and
+     * agentd rejects on re-invoke, and the approval never resolves — exactly
+     * the #1009 bug this method was written to fix.
+     */
+    resourceIdHierarchicallyMatches(approvedId, candidateId) {
+        // exact-or-hierarchical, mirrors JiraResourceResolver.matches() (see #1014)
+        if (approvedId === candidateId)
+            return true;
+        const projectKey = (0, ai_identity_1.extractProjectKey)(candidateId);
+        return projectKey !== null && projectKey === approvedId;
+    }
+    /**
+     * The single predicate deciding "does this approval cover this resource?".
+     *
+     * 🔴 Extracted because the check exists at TWO call sites — the pre-claim
+     * check (~:1213, over `request.input`) and the post-claim re-validation
+     * (~:1310, over the stored `actionParams`). They were byte-identical copies,
+     * and the live 2026-07-30 calendar bug hit BOTH: fixing only one produced a
+     * test that still failed, from the other site's near-identical message.
+     * Two independent copies of one security decision is how they silently drift
+     * (#1232 is the same lesson for terminal-status sets living in 3 places).
+     */
+    approvedResourceMatches(approvedResources, extractedId, normalizedId) {
+        return approvedResources.some(r => r.id === extractedId || r.id === normalizedId ||
+            r.pattern === extractedId || r.pattern === normalizedId ||
+            (r.id !== undefined && r.provider === 'jira' && this.resourceIdHierarchicallyMatches(r.id, extractedId)) ||
+            (r.id !== undefined && this.calendarPrimaryAliasMatches(r.id, extractedId)));
+    }
+    /**
+     * `primary` is Google Calendar's alias for the token owner's OWN calendar,
+     * so `primary` and that owner's calendar address name one resource. The
+     * approval surfaces deliberately substitute the address for the alias —
+     * `public/js/pages/approve.js:514-521` and
+     * `slack-approve.service.ts:224-238` both do it, because asking a human to
+     * approve a write to "primary" tells them nothing about which calendar.
+     *
+     * But nothing rewrites the request's stored actionParams to match, and
+     * `canonicalResourceId` has no notion of the alias (resolving it needs the
+     * Google OAuth token, i.e. a DB read that agentd and remote-mcp cannot do —
+     * INV-1). So re-invocation compares `"owner@gmail.com"` against `"primary"`,
+     * they differ byte-wise, and the approval can NEVER be satisfied. Reported
+     * live 2026-07-30: the user approved, retried, and was rejected forever.
+     *
+     * 🔴 THIS IS NOT A WILDCARD. The alias only matches an id that looks like a
+     * calendar ADDRESS, and only in the alias→address direction. A named shared
+     * calendar (`team@group.calendar.google.com`) is a different resource and
+     * still fails, which is what the third case in
+     * `oob-approval-calendar-primary-alias.test.ts` pins — without that bound
+     * this check would degrade into "any calendar approval covers any calendar".
+     *
+     * 🪤 Same failure SHAPE as #1009/#893 (Jira): Gate-2 approves, agentd's plain
+     * `===` rejects on re-invoke, and the approval never resolves. That one got
+     * `resourceIdHierarchicallyMatches`; this is the alias-equivalence sibling.
+     * When a third case appears, extract a resolver interface into the SDK so
+     * both enforcement paths consume one definition (see the TODO above) rather
+     * than growing a third branch here.
+     */
+    calendarPrimaryAliasMatches(approvedId, candidateId) {
+        // Only the alias needs reconciling; anything else is handled by `===`.
+        if (candidateId !== 'primary')
+            return false;
+        // A Google calendar address, but NOT a named/shared calendar — those are
+        // genuinely different resources and must keep failing.
+        if (approvedId.endsWith('.calendar.google.com'))
+            return false;
+        return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(approvedId);
+    }
+    isRecentOOBRequest(action, resourceId) {
+        const key = `${action}:${resourceId || '*'}`;
+        const lastTime = this.recentOOBRequests.get(key);
+        return !!lastTime && (Date.now() - lastTime) < ExecutionEngine.OOB_COOLDOWN_MS;
+    }
+    trackOOBRequest(action, resourceId) {
+        const key = `${action}:${resourceId || '*'}`;
+        this.recentOOBRequests.set(key, Date.now());
+        if (this.recentOOBRequests.size > ExecutionEngine.OOB_MAP_MAX_SIZE) {
+            const now = Date.now();
+            for (const [k, t] of this.recentOOBRequests) {
+                if (now - t > ExecutionEngine.OOB_COOLDOWN_MS) {
+                    this.recentOOBRequests.delete(k);
+                }
+            }
+        }
+    }
+    /** Verify a wallet VC: check revocation via Gateway, handle expiry. Returns the VC if valid, null if invalid. */
+    async verifyWalletVC(vc) {
+        // Check local expiration first — avoids sending expired VCs to the API
+        // Check both wallet expiresAt and JWT exp claim (JWT exp is in seconds, convert to ms)
+        const jwtExp = (0, vc_utils_1.extractExpFromVC)(vc.credentialJwt);
+        const effectiveExpiresAt = vc.expiresAt ?? (jwtExp !== null ? jwtExp * 1000 : null);
+        if (effectiveExpiresAt && effectiveExpiresAt <= Date.now()) {
+            this.wallet.revokeCredential(vc.id);
+            return null;
+        }
+        const jti = (0, vc_utils_1.extractJtiFromVC)(vc.credentialJwt);
+        if (jti) {
+            try {
+                const status = await this.gatewayClient.checkVCStatus(jti);
+                if (!status.valid) {
+                    this.wallet.revokeCredential(vc.id);
+                    return null;
+                }
+                return vc;
+            }
+            catch {
+                // Gateway unreachable — use cached VC if not expired (already checked above)
+                return vc;
+            }
+        }
+        // No jti extractable — backward compat
+        return vc;
+    }
+    async handleResourceMismatch(action, provider, params, vcResult) {
+        const extractedId = this.extractResourceIdFromInput(action, params);
+        if (this.isRecentOOBRequest(action, extractedId)) {
+            return {
+                success: false,
+                error: 'Resource access denied. An approval request was recently created. Please approve it or wait before retrying.',
+            };
+        }
+        this.logAudit({
+            action, provider,
+            decision: 'deny',
+            enforcementType: 'gateway',
+            decisionSource: 'gateway_execution',
+            decisionReason: 'Resource mismatch — VC scope does not cover target resource',
+            executionType: 'gateway',
+            credentialId: vcResult.credential.id,
+        });
+        try {
+            const riskLevel = this.getActionRiskLevel(action);
+            const oobResult = await this.createOOBApprovalRequest(action, provider, riskLevel, undefined, params);
+            this.trackOOBRequest(action, extractedId);
+            return { success: false, waitingForApproval: oobResult.waitingForApproval };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `Resource mismatch detected but failed to create approval request: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    logAudit(params) {
+        this.auditLogger?.logEvent({
+            action: params.action,
+            provider: params.provider,
+            executionType: params.executionType,
+            decision: params.decision,
+            enforcementType: params.enforcementType,
+            decisionSource: params.decisionSource,
+            decisionReason: params.decisionReason,
+            rootDid: this.context.rootDid,
+            agentDid: this.context.agentDid,
+            presenterDid: this.context.agentDid,
+            projectId: this.context.projectId,
+            requestedResource: params.requestedResource,
+            normalizedResource: params.normalizedResource,
+            resourceFingerprint: params.resourceFingerprint,
+            grantId: params.grantId,
+            credentialId: params.credentialId,
+            approvalMode: params.approvalMode,
+            approvalNonce: params.approvalNonce,
+        });
+    }
+}
+exports.ExecutionEngine = ExecutionEngine;
+//# sourceMappingURL=execution-engine.js.map