@armoriq/sdk-dev 0.6.1 → 0.6.3

package/dist/session.js

@@ -16,10 +16,92 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ArmorIQSession = void 0;
+exports.normalizeDefaultAction = normalizeDefaultAction;
+const crypto_1 = require("crypto");
+const config_1 = require("./config");
 const crypto_verify_1 = require("./crypto_verify");
 const exceptions_1 = require("./exceptions");
 const models_1 = require("./models");
 const plan_builder_1 = require("./plan_builder");
+const observability_1 = require("./observability");
+/**
+ * Normalize a policy-authoring default-enforcement-action value into the
+ * SDK-facing terminal enum. Mirrors the backend's enforce-boundary normalization
+ * (wire contract §"Canonical enforcement-action enum"):
+ *   allow | allow_log → allow ; hold → hold ; block | deny → block.
+ * Anything unknown fails closed to `block`.
+ */
+function normalizeDefaultAction(value) {
+    switch (value) {
+        case 'allow':
+        case 'allow_log':
+            return 'allow';
+        case 'hold':
+            return 'hold';
+        case 'block':
+        case 'deny':
+            return 'block';
+        default:
+            return 'block';
+    }
+}
+const TRUNCATE_BYTES = 4 * 1024;
+function truncateForSpan(value) {
+    if (value === undefined || value === null)
+        return value;
+    let json;
+    try {
+        json = typeof value === 'string' ? value : JSON.stringify(value);
+    }
+    catch {
+        json = String(value);
+    }
+    const bytes = Buffer.byteLength(json, 'utf8');
+    if (bytes <= TRUNCATE_BYTES)
+        return value;
+    const sliced = json.slice(0, TRUNCATE_BYTES);
+    return `${sliced}…(truncated, original ${bytes} bytes)`;
+}
+function safeObs(fn) {
+    try {
+        return fn();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`[armoriq] observability emit failed (continuing): ${msg}`);
+        return undefined;
+    }
+}
+function makeSpanRecord(ctx, name, attributes, status = 'ok', durationMs = null, parentSpanId) {
+    const now = new Date().toISOString();
+    return {
+        id: (0, crypto_1.randomUUID)(),
+        parentSpanId: parentSpanId ?? null,
+        sessionId: ctx.sessionId,
+        kind: 'span',
+        name,
+        startTime: now,
+        endTime: now,
+        durationMs,
+        status,
+        attributes,
+    };
+}
+function makeEventRecord(ctx, name, attributes, parentSpanId) {
+    const now = new Date().toISOString();
+    return {
+        id: (0, crypto_1.randomUUID)(),
+        parentSpanId: parentSpanId ?? null,
+        sessionId: ctx.sessionId,
+        kind: 'event',
+        name,
+        startTime: now,
+        endTime: now,
+        durationMs: 0,
+        status: 'ok',
+        attributes,
+    };
+}
 class ArmorIQSession {
     userEmail;
     client;
@@ -42,6 +124,34 @@ class ArmorIQSession {
     currentToken;
     mcpByAction = new Map();
     declaredTools = new Set();
+    obs = null;
+    /**
+     * This session's one stable observability session id — stamped onto every
+     * trace this session emits (via the recorder's `defaultSessionId`, see
+     * `ObservabilityConfig.sessionId`). Always a valid UUID; the backend's
+     * `obs_sessions.id` column is UUID-typed, so a non-UUID id (e.g. the
+     * legacy `contextId` default of the literal string `'default'`) can never
+     * form a session and traces stamped with it can never be grouped.
+     *
+     * Resolution order:
+     *   1. `opts.sessionId` if it's a valid UUID.
+     *   2. `opts.contextId` if it's a valid UUID.
+     *   3. A freshly minted `crypto.randomUUID()` (default — no arg needed).
+     */
+    sessionId;
+    /**
+     * Model A (trace-per-plan): the ONE active observability trace for the
+     * current plan. Every chokepoint (enforce/check/report/dispatch/...)
+     * records a container span under this trace via `ensurePlanTrace()`
+     * instead of opening its own trace — matching Langfuse/OTel's
+     * Session → Trace → Observation hierarchy (one IAP plan = one trace).
+     *
+     * Lifecycle: opened by `ensurePlanTrace()` (called from `startPlan()` or
+     * lazily by any chokepoint invoked before `startPlan()` — back-compat);
+     * ended by `endPlanTrace()`, called on the NEXT `startPlan()`, on
+     * `close()`/`dispose()`, and on `flushObservability()`.
+     */
+    activePlanTrace = null;
     constructor(client, opts) {
         this.client = client;
         const o = opts ?? {};
@@ -54,12 +164,298 @@ class ArmorIQSession {
         const granEnv = (typeof process !== 'undefined' && process.env?.ARMORIQ_REANCHOR_GRANULARITY) || '';
         this.reanchorGranularity =
             o.reanchorGranularity ?? (granEnv === 'deferred' ? 'deferred' : 'eager');
+        this.sessionId = (0, observability_1.isValidUuid)(o.sessionId)
+            ? o.sessionId
+            : (0, observability_1.isValidUuid)(o.contextId)
+                ? o.contextId
+                : (0, crypto_1.randomUUID)();
+        const obsCfg = o.observability;
+        if (obsCfg?.enabled === false) {
+            this.obs = null;
+        }
+        else {
+            const internals = this.client._sessionInternals();
+            const endpoint = obsCfg?.endpoint ?? internals.backendEndpoint;
+            const apiKey = obsCfg?.apiKey ?? internals.apiKey;
+            const product = obsCfg?.product ?? config_1.DEFAULT_OBSERVABILITY_PRODUCT;
+            // Reuse the session's configured httpClient (consumer interceptors,
+            // test mocks) unless the caller explicitly overrides it via
+            // `observability.httpClient`. Without this, the shipper falls back to
+            // its own bare `axios.create(...)` and silently bypasses whatever
+            // transport the rest of the SDK uses — including test mocks, which
+            // then fire real network POSTs from the shipper's flush interval.
+            const httpClient = obsCfg?.httpClient ?? internals.httpClient;
+            // `internals.userId`/`internals.agentId` default to `''` (see the
+            // `ArmorIQClient` constructor) when the caller configured neither an
+            // option nor the corresponding env var — normalize that to `null` so
+            // an unconfigured identity reads as genuinely absent on the trace,
+            // rather than shipping an empty string.
+            const nonEmpty = (v) => (v ? v : null);
+            // `internals.userId` is `client.userEmailOverride || client.userId`
+            // (client.ts) — an arbitrary identity string (often an email address,
+            // or the multi-user placeholder `'__sdk_multiuser__'`), NOT guaranteed
+            // to be a UUID. The observability trace's `userId` column/wire schema
+            // IS UUID-typed (`z.uuid()` on the backend) — forwarding a non-UUID
+            // value 400s the entire ingest batch at the shipper. Validate before
+            // forwarding; a non-UUID userId is dropped to `null` rather than
+            // breaking ingestion (`agentId` has no such constraint — see below).
+            const validUserId = (v) => (0, observability_1.isValidUuid)(v) ? v : null;
+            const merged = {
+                ...(0, config_1.defaultObservabilityConfig)(),
+                ...(obsCfg ?? {}),
+                enabled: true,
+                endpoint,
+                apiKey,
+                product,
+                httpClient,
+                // The session's one stable UUID — applied to every trace this
+                // recorder starts unless a chokepoint explicitly overrides it (none
+                // do; see the `startTrace(...)` call sites below, all of which now
+                // pass `this.sessionId` directly for clarity/back-compat).
+                sessionId: obsCfg?.sessionId ?? this.sessionId,
+                // Denormalize the client's configured user/agent identity onto every
+                // trace this recorder starts, unless the caller explicitly overrides
+                // via `observability.userId`/`observability.agentId`. `internals`
+                // already carries both (see `ArmorIQClient._sessionInternals()`);
+                // previously neither was forwarded here, so every SDK-emitted trace
+                // shipped with `agentId: null` even when the client was constructed
+                // with a real agent id. `agentId` is a free-form string on the wire
+                // (backend column is `text`, not a UUID FK) — no UUID validation
+                // required, unlike `sessionId`/`userId`.
+                userId: obsCfg?.userId ?? validUserId(internals.userId),
+                agentId: obsCfg?.agentId ?? nonEmpty(internals.agentId),
+            };
+            this.obs = new observability_1.ObservabilityRecorder(merged);
+        }
+    }
+    /**
+     * The session's `ObservabilityRecorder`, or `null` when observability is
+     * disabled for this session. Pass this explicitly to
+     * `summarizeTranscriptUsage(path, recorder, ctx)` / `client.captureTranscriptTokens({
+     * ..., observabilityRecorder, planTraceCtx })` so transcript-derived generation spans are
+     * attributed to the correct session — the SDK no longer keeps a
+     * process-global "active recorder" (see #4: concurrent sessions would
+     * otherwise misattribute usage to whichever session constructed last).
+     */
+    get observabilityRecorder() {
+        return this.obs;
+    }
+    /**
+     * Model A (Task 4): the session's active plan trace context, or `null` if
+     * none is open yet (lazily opens on first use — same as every chokepoint).
+     * Pass this as `summarizeTranscriptUsage(path, session.observabilityRecorder,
+     * session.activePlanTraceContext)` (or via
+     * `client.captureTranscriptTokens({ ..., planTraceCtx: session.activePlanTraceContext })`)
+     * so transcript-derived generation spans nest under the SAME plan trace as
+     * every other chokepoint this session recorded, instead of opening a
+     * standalone `llm.usage.report` trace.
+     */
+    get activePlanTraceContext() {
+        return this.obs ? this.ensurePlanTrace() : null;
+    }
+    // ─── Model A: active-plan-trace lifecycle ──────────────────────
+    /**
+     * Return the session's active plan trace, lazily opening one if none is
+     * active. This is the ONE trace every chokepoint's container span nests
+     * under (Model A: trace-per-plan). Returns `null` when observability is
+     * disabled — every call site already treats a null ctx as "skip emit".
+     *
+     * Back-compat (plan §"Global Constraints"): a chokepoint invoked with no
+     * prior `startPlan()` (e.g. a standalone `enforceLocal()`/`report()` call)
+     * still needs to emit — so this opens a plan trace lazily on first use
+     * rather than requiring `startPlan()` to have run first.
+     */
+    ensurePlanTrace(name = 'iap.plan', attrs = {}) {
+        if (!this.obs)
+            return null;
+        if (this.activePlanTrace)
+            return this.activePlanTrace;
+        const ctx = safeObs(() => (0, observability_1.startTrace)(this.obs, name, attrs, this.sessionId)) ?? null;
+        this.activePlanTrace = ctx;
+        return ctx;
+    }
+    /**
+     * End the active plan trace (if any) and clear it. Called on the NEXT
+     * `startPlan()` (closing the PRIOR plan before opening a new one),
+     * `close()`/`dispose()`, and `flushObservability()` — so the in-flight
+     * plan trace always ships before the process exits or a new plan begins.
+     */
+    endPlanTrace(status = 'ok') {
+        if (!this.obs || !this.activePlanTrace)
+            return;
+        const ctx = this.activePlanTrace;
+        this.activePlanTrace = null;
+        safeObs(() => (0, observability_1.endTrace)(this.obs, ctx, { status }));
     }
     // ─── Plan capture ──────────────────────────────────────────────
+    async reanchorCall(intentToken, plan, reason) {
+        const startNs = this.obs ? performance.now() : 0;
+        const ctx = this.obs ? this.ensurePlanTrace() : null;
+        const spanId = ctx && this.obs
+            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
+                name: 'iap.reanchor',
+                attributes: { reason, planStepCount: plan?.steps?.length ?? null },
+            })) ?? undefined
+            : undefined;
+        let caught;
+        let trustId;
+        try {
+            const result = await this.client.reanchor(intentToken, plan, reason);
+            trustId = result?.trustId;
+            if (ctx) {
+                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeEventRecord(ctx, 'iap.reanchor.delta', {
+                    kind: 'event',
+                    message: 'delta recorded',
+                    level: 'info',
+                    trustId: trustId ?? null,
+                }, spanId)));
+            }
+            return { trustId };
+        }
+        catch (err) {
+            caught = err;
+            if (ctx) {
+                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeEventRecord(ctx, 'iap.reanchor.delta_failed', {
+                    kind: 'event',
+                    message: `delta failed: ${err.message}`,
+                    level: 'error',
+                }, spanId)));
+            }
+            throw err;
+        }
+        finally {
+            if (ctx) {
+                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
+                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeSpanRecord(ctx, 'iap.reanchor.http', {
+                    kind: 'span',
+                    trustId: trustId ?? null,
+                    errorMessage: caught instanceof Error ? caught.message : undefined,
+                }, caught ? 'error' : 'ok', computedDuration ?? null, spanId)));
+                if (spanId) {
+                    safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
+                        status: caught ? 'error' : 'ok',
+                        durationMs: computedDuration,
+                        errorMessage: caught instanceof Error ? caught.message : undefined,
+                    }));
+                }
+            }
+        }
+    }
+    async getIntentTokenCall(planCapture, validitySeconds) {
+        const startNs = this.obs ? performance.now() : 0;
+        const ctx = this.obs ? this.ensurePlanTrace() : null;
+        const spanId = ctx && this.obs
+            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
+                name: 'iap.intent_token.mint',
+                attributes: { planStepCount: planCapture?.plan?.steps?.length ?? null },
+            })) ?? undefined
+            : undefined;
+        let caught;
+        let token;
+        try {
+            token = await this.client.getIntentToken(planCapture, undefined, validitySeconds);
+            if (ctx) {
+                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeEventRecord(ctx, 'iap.intent_token.minted', {
+                    kind: 'event',
+                    message: 'new intent token minted',
+                    level: 'info',
+                    tokenId: token?.tokenId ?? null,
+                    planId: token?.planId ?? null,
+                }, spanId)));
+            }
+            return token;
+        }
+        catch (err) {
+            caught = err;
+            throw err;
+        }
+        finally {
+            if (ctx) {
+                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
+                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeSpanRecord(ctx, 'iap.intent_token.mint.http', {
+                    kind: 'span',
+                    errorMessage: caught instanceof Error ? caught.message : undefined,
+                }, caught ? 'error' : 'ok', computedDuration ?? null, spanId)));
+                if (spanId) {
+                    safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
+                        status: caught ? 'error' : 'ok',
+                        durationMs: computedDuration,
+                        errorMessage: caught instanceof Error ? caught.message : undefined,
+                    }));
+                }
+            }
+        }
+    }
     async startPlan(toolCalls, goal) {
+        const startNs = this.obs ? performance.now() : 0;
+        // Model A: close the PRIOR plan's trace (if any) before opening the new
+        // one — one IAP plan = one trace, so a new startPlan() is a plan
+        // boundary. Then open the new active plan trace and record a
+        // container span (`iap.plan.start`) for this call's own work, nested
+        // under it exactly like every other chokepoint's container span.
+        if (this.obs)
+            safeObs(() => this.endPlanTrace('ok'));
+        const ctx = this.obs
+            ? this.ensurePlanTrace('iap.plan', {
+                toolCount: toolCalls?.length ?? 0,
+                goal: goal ?? null,
+                mode: this.mode,
+            })
+            : null;
+        const spanId = ctx && this.obs
+            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
+                name: 'iap.plan.start',
+                attributes: {
+                    toolCount: toolCalls?.length ?? 0,
+                    goal: goal ?? null,
+                    mode: this.mode,
+                },
+            })) ?? undefined
+            : undefined;
+        let caught;
+        let planTraceStatus = 'ok';
+        let planTraceError;
+        try {
+            const result = await this._startPlanImpl(toolCalls, goal, ctx);
+            if (ctx) {
+                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeEventRecord(ctx, 'iap.plan.grew', {
+                    kind: 'event',
+                    message: `plan captured: ${toolCalls?.length ?? 0} tool(s)`,
+                    level: 'info',
+                    toolCount: toolCalls?.length ?? 0,
+                })));
+            }
+            return result;
+        }
+        catch (err) {
+            caught = err;
+            planTraceStatus = 'error';
+            planTraceError = err.message;
+            throw err;
+        }
+        finally {
+            if (ctx && spanId) {
+                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
+                safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
+                    status: planTraceStatus === 'error' ? 'error' : 'ok',
+                    durationMs: computedDuration,
+                    errorMessage: planTraceError,
+                }));
+            }
+        }
+    }
+    async _startPlanImpl(toolCalls, goal, _ctx) {
         if (!toolCalls || toolCalls.length === 0) {
             throw new Error('startPlan called with no tool calls.');
         }
+        // #519 — in local mode, warm the trusted IAP public key (config/env, else
+        // one-shot fetch) so the synchronous enforceLocal() can verify the EdDSA
+        // intent-token JWT. Best-effort: a failure here just means enforceLocal
+        // fails closed later. Skipped in proxy/sdk mode (the proxy/backend verifies)
+        // to avoid an unnecessary network call for those consumers.
+        if (this.mode === 'local') {
+            await this.client.ensureIapPublicKey();
+        }
         const h = (0, plan_builder_1.hashToolCalls)(toolCalls);
         if (this.currentToken && this.currentPlanHash === h) {
             return this.currentToken;
@@ -99,7 +495,7 @@ class ArmorIQSession {
             // For autoReanchor (pragmatic v2) in deferred mode: still need to
             // re-mint because step_proofs are baked at issuance. Skip the
             // delta call here; flushReanchor() catches up later.
-            const tokenA = await this.client.getIntentToken(planCapture, undefined, this.validitySeconds);
+            const tokenA = await this.getIntentTokenCall(planCapture, this.validitySeconds);
             this.currentPlanHash = h;
             this.currentToken = tokenA;
             this.stepIndex = 0;
@@ -112,7 +508,7 @@ class ArmorIQSession {
         // preserved across the chain (paper's actual C3).
         if (this.trueReanchor && this.currentToken) {
             try {
-                await this.client.reanchor(this.currentToken, plan, 'plan grew (true-reanchor)');
+                await this.reanchorCall(this.currentToken, plan, 'plan grew (true-reanchor)');
                 // Update local state without re-minting. The JWT stays the same;
                 // only currentPlanHash advances so subsequent enforceLocal /
                 // dispatch calls see the new plan.
@@ -134,47 +530,97 @@ class ArmorIQSession {
         // pins to the JWT's plan_hash and step_proofs are baked at issuance.
         if (this.autoReanchor && this.currentToken) {
             try {
-                await this.client.reanchor(this.currentToken, plan, 'plan grew mid-session');
+                await this.reanchorCall(this.currentToken, plan, 'plan grew mid-session');
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
                 console.warn(`[armoriq] auto-reanchor delta failed (continuing): ${msg}`);
             }
         }
-        const token = await this.client.getIntentToken(planCapture, undefined, this.validitySeconds);
+        const token = await this.getIntentTokenCall(planCapture, this.validitySeconds);
         this.currentPlanHash = h;
         this.currentToken = token;
         this.stepIndex = 0;
         return token;
     }
     // ─── Policy enforcement ────────────────────────────────────────
-    enforceLocal(toolName, toolArgs) {
+    /**
+     * `parentContainerSpanId` is an internal-only hook (not part of the public
+     * signature contract other SDK consumers rely on — it's simply an extra
+     * optional trailing arg) so `check()` can nest this call's container span
+     * under `iap.check`'s own container span instead of both sitting as
+     * siblings directly under the plan trace (Task 3 risk: "check → enforce
+     * double-open" — `iap.check`'s span wraps the dispatched enforce span,
+     * it never opens a second redundant plan trace or duplicate container).
+     */
+    enforceLocal(toolName, toolArgs, parentContainerSpanId) {
+        const startNs = this.obs ? performance.now() : 0;
+        const ctx = this.obs ? this.ensurePlanTrace() : null;
+        const spanId = ctx && this.obs
+            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
+                name: 'iap.enforce.local',
+                attributes: { toolName, toolArgs: truncateForSpan(toolArgs) },
+                parentSpanId: parentContainerSpanId ?? null,
+            })) ?? undefined
+            : undefined;
+        let caught;
+        try {
+            return this._enforceLocalImpl(toolName, toolArgs, ctx, spanId);
+        }
+        catch (err) {
+            caught = err;
+            throw err;
+        }
+        finally {
+            if (ctx && spanId) {
+                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
+                safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
+                    status: caught ? 'error' : 'ok',
+                    durationMs: computedDuration,
+                    errorMessage: caught instanceof Error ? caught.message : undefined,
+                }));
+            }
+        }
+    }
+    _enforceLocalImpl(toolName, toolArgs, ctx, spanId) {
         if (!this.currentToken) {
-            return {
+            const r = {
                 allowed: false,
                 action: 'block',
                 reason: 'No intent token — call startPlan() first',
             };
+            this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk-local', {}, spanId);
+            return r;
         }
         if (models_1.IntentToken.isExpired(this.currentToken)) {
-            return { allowed: false, action: 'block', reason: 'token-expired' };
+            const r = { allowed: false, action: 'block', reason: 'token-expired' };
+            this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk-local', {}, spanId);
+            return r;
         }
         // The local decision is read from the token's policy fields, so the token
         // must be cryptographically authentic first - otherwise a forged token
-        // could assert an arbitrary allowlist. Fail closed if the signature is bad.
-        if (!(0, crypto_verify_1.verifyIntentTokenSignature)(this.currentToken.rawToken)) {
-            return { allowed: false, action: 'block', reason: 'token-signature-invalid' };
+        // could assert an arbitrary allowlist. #519: verify the backend's EdDSA
+        // (Ed25519) JWT against the TRUSTED public key (option/env, or fetched from
+        // GET /iap/public-key and warmed in startPlan) — never a key embedded in
+        // the token. Fail CLOSED if the key is unavailable or the signature is bad.
+        const iapKey = this.client.iapPublicKeySync();
+        if (!iapKey || !(0, crypto_verify_1.verifyEdDSAJwt)(this.currentToken.jwtToken ?? '', iapKey)) {
+            const r = { allowed: false, action: 'block', reason: 'token-signature-invalid' };
+            this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk-local', {}, spanId);
+            return r;
         }
         const { mcp, action } = this.toolNameParser(toolName);
         const inPlan = this.declaredTools.has(toolName) ||
             this.declaredTools.has(action) ||
             this.declaredTools.has(`${mcp}__${action}`);
         if (!inPlan) {
-            return {
+            const r = {
                 allowed: false,
                 action: 'block',
                 reason: `tool-not-in-plan: '${toolName}' was not declared in the captured plan`,
             };
+            this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk-local', { mcp }, spanId);
+            return r;
         }
         const pv = (this.currentToken.policyValidation ?? {});
         const snapshot = (this.currentToken.policySnapshot ?? []);
@@ -209,7 +655,10 @@ class ArmorIQSession {
         }
         const governingRule = governingEntry ? ruleOf(governingEntry) : undefined;
         const governingPolicyName = governingEntry?.policyName;
-        const notAllowedAction = governingEntry?.defaultEnforcementAction ?? pv.default_enforcement_action ?? 'block';
+        // Normalize the policy default action into the terminal allow|block|hold set.
+        // Previously any non-'hold' value was coerced to 'block', which wrongly
+        // blocked 'allow' and 'allow_log' defaults.
+        const defaultAction = normalizeDefaultAction(governingEntry?.defaultEnforcementAction ?? pv.default_enforcement_action);
         const deniedTools = pv.denied_tools;
         if (Array.isArray(deniedTools)) {
             if (deniedTools.includes(toolName) || deniedTools.includes(action)) {
@@ -219,14 +668,31 @@ class ArmorIQSession {
                     (governingPolicyName
                         ? `Tool '${action}' is denied by policy '${governingPolicyName}'`
                         : `Tool '${action}' is denied by policy`);
-                return {
+                // Deny-precedence: an explicitly denied tool is never allowed, even when
+                // the default action is 'allow'. hold only if the policy default is hold.
+                const r = {
                     allowed: false,
-                    action: notAllowedAction === 'hold' ? 'hold' : 'block',
+                    action: defaultAction === 'hold' ? 'hold' : 'block',
                     reason,
                     matchedPolicy: governingPolicyName,
                 };
+                this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk-local', { mcp, policyValidation: pv }, spanId);
+                return r;
             }
         }
+        // Honor the backend-baked resolved allow set: an explicit *empty*
+        // allowed_tools means the same-priority intersection removed every tool
+        // ⇒ deny-all, regardless of what any individual snapshot rule allows.
+        const bakedAllowedTools = pv.allowed_tools;
+        if (Array.isArray(bakedAllowedTools) && bakedAllowedTools.length === 0) {
+            const r = {
+                allowed: false,
+                action: 'block',
+                reason: `Tool '${action}' is not allowed by any policy in scope (empty resolved allow-list)`,
+            };
+            this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk-local', { mcp, policyValidation: pv }, spanId);
+            return r;
+        }
         if (governingRule) {
             const allowed = governingRule.allowedTools ?? [];
             if (Array.isArray(allowed) && allowed.length > 0) {
@@ -234,40 +700,109 @@ class ArmorIQSession {
                     allowed.includes(action) ||
                     allowed.includes(toolName);
                 if (!ok) {
-                    return {
+                    // Tool is outside this rule's explicit allow set. Fall back to the
+                    // policy default action: an 'allow' default permits it, hold/block
+                    // otherwise.
+                    if (defaultAction === 'allow') {
+                        const r = {
+                            allowed: true,
+                            action: 'allow',
+                            reason: `Allowed by default enforcement action for policy '${governingPolicyName}'`,
+                            matchedPolicy: governingPolicyName,
+                        };
+                        this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk-local', { mcp, policyValidation: pv }, spanId);
+                        return r;
+                    }
+                    const r = {
                         allowed: false,
-                        action: notAllowedAction === 'hold' ? 'hold' : 'block',
+                        action: defaultAction,
                         reason: `Tool '${action}' is not in the allowed tools for policy '${governingPolicyName}'`,
                         matchedPolicy: governingPolicyName,
                     };
+                    this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk-local', { mcp, policyValidation: pv }, spanId);
+                    return r;
                 }
             }
         }
-        else if (Array.isArray(snapshot) && snapshot.length > 0) {
-            const allowedTools = pv.allowed_tools;
-            if (Array.isArray(allowedTools) && allowedTools.length === 0) {
-                return {
-                    allowed: false,
-                    action: 'block',
-                    reason: `Tool '${action}' is not allowed by any policy in scope`,
-                };
-            }
-        }
         if (governingRule) {
             const thresholdDecision = this.evaluateAmountThreshold(governingRule, toolArgs, action, mcp);
             if (thresholdDecision) {
                 thresholdDecision.matchedPolicy = governingPolicyName;
+                this._emitEnforcePolicyCall(ctx, toolName, thresholdDecision, 'sdk-local', { mcp, policyValidation: pv }, spanId);
                 return thresholdDecision;
             }
         }
-        return {
+        const r = {
             allowed: true,
             action: 'allow',
             reason: 'Allowed by local policy evaluation',
             matchedPolicy: governingPolicyName,
         };
+        this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk-local', { mcp, policyValidation: pv }, spanId);
+        return r;
+    }
+    _emitEnforcePolicyCall(ctx, toolName, result, source, extras, parentSpanId) {
+        if (!ctx || !this.obs)
+            return;
+        const decision = result.action === 'allow'
+            ? 'allow'
+            : result.action === 'hold'
+                ? 'hold'
+                : 'deny';
+        const enforcementAction = result.action;
+        safeObs(() => (0, observability_1.recordPolicyCall)(this.obs, ctx, {
+            policyId: null,
+            policyName: result.matchedPolicy ?? null,
+            decision,
+            reason: result.reason ?? null,
+            source,
+            input: { toolName },
+            output: {
+                allowed: result.allowed,
+                action: result.action,
+                matchedPolicy: result.matchedPolicy ?? null,
+                delegationId: result.delegationId ?? null,
+            },
+            policyHash: null,
+            policyVersion: null,
+            matchedRuleId: null,
+            dataClasses: [],
+            enforcementAction,
+            obligations: extras.obligations ?? result.obligations ?? [],
+            delegationId: result.delegationId ?? null,
+        }, parentSpanId));
+    }
+    /** See `enforceLocal`'s doc comment re: `parentContainerSpanId` (internal-only hook for `check()`). */
+    async enforceSdk(toolName, toolArgs, userEmail, parentContainerSpanId) {
+        const startNs = this.obs ? performance.now() : 0;
+        const ctx = this.obs ? this.ensurePlanTrace() : null;
+        const spanId = ctx && this.obs
+            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
+                name: 'iap.enforce.sdk',
+                attributes: { toolName, toolArgs: truncateForSpan(toolArgs), userEmail: userEmail ?? null },
+                parentSpanId: parentContainerSpanId ?? null,
+            })) ?? undefined
+            : undefined;
+        let caught;
+        try {
+            return await this._enforceSdkImpl(toolName, toolArgs, userEmail, ctx, spanId);
+        }
+        catch (err) {
+            caught = err;
+            throw err;
+        }
+        finally {
+            if (ctx && spanId) {
+                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
+                safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
+                    status: caught ? 'error' : 'ok',
+                    durationMs: computedDuration,
+                    errorMessage: caught instanceof Error ? caught.message : undefined,
+                }));
+            }
+        }
     }
-    async enforceSdk(toolName, toolArgs, userEmail) {
+    async _enforceSdkImpl(toolName, toolArgs, userEmail, ctx, spanId) {
         if (!this.currentToken) {
             throw new Error(`enforceSdk("${toolName}") called before startPlan().`);
         }
@@ -277,11 +812,13 @@ class ArmorIQSession {
             this.declaredTools.has(action) ||
             this.declaredTools.has(`${resolvedMcp}__${action}`);
         if (!inPlan) {
-            return {
+            const r = {
                 allowed: false,
                 action: 'block',
                 reason: `tool-not-in-plan: '${toolName}' was not declared in the captured plan`,
             };
+            this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk', { mcp: resolvedMcp }, spanId);
+            return r;
         }
         const internals = this.client._sessionInternals();
         try {
@@ -302,31 +839,74 @@ class ArmorIQSession {
             const matched = typeof data.matchedPolicy === 'object'
                 ? data.matchedPolicy?.name
                 : data.matchedPolicy;
+            // Surface gating obligations metadata (additive). The backend has already
+            // collapsed gating into allowed/action; obligations explain *why*.
+            const obligations = Array.isArray(data.obligations)
+                ? data.obligations
+                : [];
             if (actionDecision === 'hold') {
-                return this.handleHold(toolName, toolArgs, {
+                const r = {
                     allowed: false,
                     action: 'hold',
                     reason: data.reason ?? data.message,
                     matchedPolicy: matched,
-                }, userEmail);
+                    obligations,
+                };
+                this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk', { mcp: resolvedMcp, obligations }, spanId);
+                return this.handleHold(toolName, toolArgs, r, userEmail);
             }
-            return {
+            const r = {
                 allowed,
                 action: actionDecision,
                 reason: data.reason ?? data.message,
                 matchedPolicy: matched,
+                obligations,
             };
+            this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk', { mcp: resolvedMcp, obligations }, spanId);
+            return r;
         }
         catch (e) {
             console.error(`enforceSdk() failed: ${e.message}. Blocking tool call (fail-closed).`);
-            return {
+            const r = {
                 allowed: false,
                 action: 'block',
                 reason: `enforce-unavailable: ${e.message}`,
             };
+            this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk', { mcp: resolvedMcp }, spanId);
+            return r;
         }
     }
-    async enforce(toolName, toolArgs) {
+    /** See `enforceLocal`'s doc comment re: `parentContainerSpanId` (internal-only hook for `check()`). */
+    async enforce(toolName, toolArgs, parentContainerSpanId) {
+        const startNs = this.obs ? performance.now() : 0;
+        const ctx = this.obs ? this.ensurePlanTrace() : null;
+        const spanId = ctx && this.obs
+            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
+                name: 'iap.enforce.proxy',
+                attributes: { toolName, toolArgs: truncateForSpan(toolArgs) },
+                parentSpanId: parentContainerSpanId ?? null,
+            })) ?? undefined
+            : undefined;
+        let caught;
+        try {
+            return await this._enforceImpl(toolName, toolArgs, ctx, spanId);
+        }
+        catch (err) {
+            caught = err;
+            throw err;
+        }
+        finally {
+            if (ctx && spanId) {
+                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
+                safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
+                    status: caught ? 'error' : 'ok',
+                    durationMs: computedDuration,
+                    errorMessage: caught instanceof Error ? caught.message : undefined,
+                }));
+            }
+        }
+    }
+    async _enforceImpl(toolName, toolArgs, ctx, spanId) {
         if (!this.currentToken) {
             throw new Error(`enforce("${toolName}") called before startPlan().`);
         }
@@ -336,11 +916,13 @@ class ArmorIQSession {
             this.declaredTools.has(action) ||
             this.declaredTools.has(`${resolvedMcp}__${action}`);
         if (!inPlan) {
-            return {
+            const r = {
                 allowed: false,
                 action: 'block',
                 reason: `tool-not-in-plan: '${toolName}' was not declared in the captured plan`,
             };
+            this._emitEnforcePolicyCall(ctx, toolName, r, 'proxy', { mcp: resolvedMcp }, spanId);
+            return r;
         }
         const internals = this.client._sessionInternals();
         try {
@@ -367,175 +949,344 @@ class ArmorIQSession {
             // Fail closed: only an explicit allow from a 2xx response permits the call.
             // Any error status (403 or otherwise) or an ambiguous body blocks.
             if (response.status >= 400) {
-                return {
+                const r = {
                     allowed: false,
                     action: data.action ?? 'block',
                     reason: data.reason ?? data.message ?? `enforce-rejected: HTTP ${response.status}`,
                     matchedPolicy: policyName,
                 };
+                this._emitEnforcePolicyCall(ctx, toolName, r, 'proxy', { mcp: resolvedMcp }, spanId);
+                return r;
             }
             const allowedFlag = data.allowed === true;
             const actionDecision = data.enforcementAction ?? data.action ?? (allowedFlag ? 'allow' : 'block');
-            return {
+            const r = {
                 allowed: allowedFlag,
                 action: actionDecision,
                 reason: data.reason,
                 delegationId: data.delegation_id,
                 matchedPolicy: policyName,
+                obligations: Array.isArray(data.obligations) ? data.obligations : [],
             };
+            this._emitEnforcePolicyCall(ctx, toolName, r, 'proxy', { mcp: resolvedMcp }, spanId);
+            return r;
         }
         catch (e) {
             console.error(`enforce() failed: ${e.message}. Blocking tool call (fail-closed).`);
-            return {
+            const r = {
                 allowed: false,
                 action: 'block',
                 reason: `enforce-unavailable: ${e.message}`,
             };
+            this._emitEnforcePolicyCall(ctx, toolName, r, 'proxy', { mcp: resolvedMcp }, spanId);
+            return r;
         }
     }
     async check(toolName, toolArgs, userEmail) {
-        if (this.mode === 'sdk') {
-            return this.enforceSdk(toolName, toolArgs, userEmail);
+        const startNs = this.obs ? performance.now() : 0;
+        const ctx = this.obs ? this.ensurePlanTrace() : null;
+        // Task 3 risk — "check → enforce double-open": `check` opens its OWN
+        // `iap.check` container span (nested under the single active plan
+        // trace, never a second trace), then passes this span's id as the
+        // PARENT for whichever enforce* it dispatches into. The dispatched
+        // enforce's container span therefore nests under `iap.check`'s span —
+        // it does not open a redundant plan trace or a sibling/duplicate
+        // container span.
+        const spanId = ctx && this.obs
+            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
+                name: 'iap.check',
+                attributes: {
+                    toolName,
+                    toolArgs: truncateForSpan(toolArgs),
+                    mode: this.mode,
+                    userEmail: userEmail ?? null,
+                },
+            })) ?? undefined
+            : undefined;
+        let caught;
+        try {
+            if (this.mode === 'sdk') {
+                return await this.enforceSdk(toolName, toolArgs, userEmail, spanId);
+            }
+            if (this.mode === 'local') {
+                const decision = this.enforceLocal(toolName, toolArgs, spanId);
+                if (decision.action === 'hold') {
+                    return {
+                        ...decision,
+                        action: 'block',
+                        reason: (decision.reason ?? 'requires approval') +
+                            ' — switch ARMORIQ_MODE=proxy to enable approval workflows for this action.',
+                    };
+                }
+                return decision;
+            }
+            const decision = await this.enforce(toolName, toolArgs, spanId);
+            if (decision.action !== 'hold')
+                return decision;
+            return this.handleHold(toolName, toolArgs, decision, userEmail);
         }
-        if (this.mode === 'local') {
-            const decision = this.enforceLocal(toolName, toolArgs);
-            if (decision.action === 'hold') {
-                return {
-                    ...decision,
-                    action: 'block',
-                    reason: (decision.reason ?? 'requires approval') +
-                        ' — switch ARMORIQ_MODE=proxy to enable approval workflows for this action.',
-                };
+        catch (err) {
+            caught = err;
+            throw err;
+        }
+        finally {
+            if (ctx && spanId) {
+                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
+                safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
+                    status: caught ? 'error' : 'ok',
+                    durationMs: computedDuration,
+                    errorMessage: caught instanceof Error ? caught.message : undefined,
+                }));
             }
-            return decision;
         }
-        const decision = await this.enforce(toolName, toolArgs);
-        if (decision.action !== 'hold')
-            return decision;
-        return this.handleHold(toolName, toolArgs, decision, userEmail);
     }
     // ─── Report / dispatch ─────────────────────────────────────────
     async report(toolName, toolArgs, result, opts) {
-        const o = opts ?? {};
-        const { mcp, action } = this.toolNameParser(toolName);
-        const resolvedMcp = this.mcpByAction.get(action) ?? mcp;
-        const internals = this.client._sessionInternals();
+        const o = {
+            ...opts,
+            durationMs: opts?.durationMs != null && Number.isFinite(opts.durationMs)
+                ? Math.round(opts.durationMs)
+                : opts?.durationMs,
+        };
+        const startNs = this.obs ? performance.now() : 0;
+        const ctx = this.obs ? this.ensurePlanTrace() : null;
+        const spanId = ctx && this.obs
+            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
+                name: 'tool.report',
+                attributes: {
+                    toolName,
+                    toolInput: truncateForSpan(toolArgs),
+                    status: o.status ?? 'success',
+                },
+            })) ?? undefined
+            : undefined;
+        let caught;
+        let reportStatus = 'ok';
+        let reportError;
         try {
-            const token = this.currentToken;
-            const userEmail = this.userEmail ?? this.client.userEmailOverride;
-            let output = result;
-            if (typeof result === 'string')
-                output = { text: result };
-            else if (result === null || result === undefined)
-                output = {};
-            await internals.httpClient.post(`${internals.backendEndpoint}/iap/audit`, {
-                token: token?.jwtToken ?? token?.tokenId ?? 'unknown',
-                plan_id: token?.planId ?? token?.tokenId ?? 'unknown',
-                step_index: this.stepIndex,
-                action,
-                tool: action,
-                mcp: resolvedMcp,
-                input: toolArgs,
-                output,
-                status: o.status ?? 'success',
-                error_message: o.errorMessage,
-                duration_ms: o.durationMs,
-                is_delegated: o.isDelegated,
-                delegated_by: o.delegatedBy,
-                user_email: userEmail,
-                delegated_to: o.delegatedTo,
-                executed_at: new Date().toISOString(),
-            }, {
-                headers: { 'X-API-Key': internals.apiKey, 'Content-Type': 'application/json' },
-                timeout: 5000,
-            });
+            const { mcp, action } = this.toolNameParser(toolName);
+            const resolvedMcp = this.mcpByAction.get(action) ?? mcp;
+            const internals = this.client._sessionInternals();
+            try {
+                const token = this.currentToken;
+                const userEmail = this.userEmail ?? this.client.userEmailOverride;
+                let output = result;
+                if (typeof result === 'string')
+                    output = { text: result };
+                else if (result === null || result === undefined)
+                    output = {};
+                await internals.httpClient.post(`${internals.backendEndpoint}/iap/audit`, {
+                    token: token?.jwtToken ?? token?.tokenId ?? 'unknown',
+                    plan_id: token?.planId ?? token?.tokenId ?? 'unknown',
+                    step_index: this.stepIndex,
+                    action,
+                    tool: action,
+                    mcp: resolvedMcp,
+                    input: toolArgs,
+                    output,
+                    status: o.status ?? 'success',
+                    error_message: o.errorMessage,
+                    duration_ms: o.durationMs,
+                    is_delegated: o.isDelegated,
+                    delegated_by: o.delegatedBy,
+                    user_email: userEmail,
+                    delegated_to: o.delegatedTo,
+                    executed_at: new Date().toISOString(),
+                }, {
+                    headers: { 'X-API-Key': internals.apiKey, 'Content-Type': 'application/json' },
+                    timeout: 5000,
+                });
+            }
+            catch (e) {
+                console.warn(`report() failed: ${e.message}`);
+            }
+            this.stepIndex += 1;
         }
-        catch (e) {
-            console.warn(`report() failed: ${e.message}`);
+        catch (err) {
+            caught = err;
+            reportStatus = 'error';
+            reportError = err.message;
+            throw err;
+        }
+        finally {
+            if (ctx) {
+                const computedDuration = o.durationMs ?? (startNs > 0 ? Math.round(performance.now() - startNs) : undefined);
+                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeSpanRecord(ctx, 'tool.report', {
+                    kind: 'span',
+                    toolName,
+                    toolInput: truncateForSpan(toolArgs),
+                    toolOutput: truncateForSpan(result),
+                    // `status` here is the caller-supplied tool outcome
+                    // ('success'|'failed'|'error' from ReportOptions), a distinct
+                    // side-channel signal from the top-level SpanRecord.status
+                    // ('ok'|'error'|'denied' span lifecycle status) below —
+                    // intentionally NOT a duplicate.
+                    status: o.status ?? 'success',
+                    errorMessage: o.errorMessage,
+                }, reportStatus === 'error' ? 'error' : 'ok', computedDuration ?? null, spanId)));
+                if (spanId) {
+                    safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
+                        status: reportStatus === 'error' ? 'error' : 'ok',
+                        durationMs: computedDuration,
+                        errorMessage: reportError,
+                    }));
+                }
+            }
         }
-        this.stepIndex += 1;
     }
     async dispatch(toolName, toolArgs) {
-        if (!this.currentToken) {
-            throw new Error(`dispatch("${toolName}") called before startPlan().`);
+        const startNs = this.obs ? performance.now() : 0;
+        const ctx = this.obs ? this.ensurePlanTrace() : null;
+        const spanId = ctx && this.obs
+            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
+                name: 'tool.dispatch',
+                attributes: { toolName, toolInput: truncateForSpan(toolArgs) },
+            })) ?? undefined
+            : undefined;
+        let caught;
+        let dispatchResult;
+        let dispatchStatus = 'ok';
+        let dispatchError;
+        try {
+            if (!this.currentToken) {
+                throw new Error(`dispatch("${toolName}") called before startPlan().`);
+            }
+            const { mcp, action } = this.toolNameParser(toolName);
+            const resolvedMcp = this.mcpByAction.get(action) ?? mcp;
+            dispatchResult = await this.client.invoke(resolvedMcp, action, this.currentToken, toolArgs);
+            this.stepIndex += 1;
+            return dispatchResult?.result;
+        }
+        catch (err) {
+            caught = err;
+            dispatchStatus = 'error';
+            dispatchError = err.message;
+            throw err;
+        }
+        finally {
+            if (ctx) {
+                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
+                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeSpanRecord(ctx, 'tool.dispatch', {
+                    kind: 'span',
+                    toolName,
+                    toolInput: truncateForSpan(toolArgs),
+                    result: truncateForSpan(dispatchResult),
+                }, dispatchStatus === 'error' ? 'error' : 'ok', computedDuration ?? null, spanId)));
+                if (spanId) {
+                    safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
+                        status: dispatchStatus === 'error' ? 'error' : 'ok',
+                        durationMs: computedDuration,
+                        errorMessage: dispatchError,
+                    }));
+                }
+            }
         }
-        const { mcp, action } = this.toolNameParser(toolName);
-        const resolvedMcp = this.mcpByAction.get(action) ?? mcp;
-        const result = await this.client.invoke(resolvedMcp, action, this.currentToken, toolArgs);
-        this.stepIndex += 1;
-        return result.result;
     }
     // ─── Helpers ────────────────────────────────────────────────────
     async handleHold(toolName, toolArgs, holdDecision, userEmail) {
-        const internals = this.client._sessionInternals();
-        const email = userEmail ?? internals.userId ?? 'unknown@armoriq';
-        const { mcp, action } = this.toolNameParser(toolName);
-        const resolvedMcp = this.mcpByAction.get(action) ?? mcp;
-        const rawAmount = ArmorIQSession.extractAmount(toolArgs) ?? 0;
-        // Single normalized amount used for BOTH the approved-delegation lookup and
-        // the create call — must agree, otherwise the SDK keeps creating new pending
-        // rows because the existing approved one (created at safeAmount) won't match
-        // a check sent at rawAmount. Backend doesn't filter by amount today (see
-        // conmap-auto delegation.service.ts checkApprovedDelegation), but staying
-        // consistent here is forward-compatible.
-        const safeAmount = typeof rawAmount === 'number' && rawAmount >= 0.01 ? rawAmount : 0.01;
+        const startNs = this.obs ? performance.now() : 0;
+        const ctx = this.obs ? this.ensurePlanTrace() : null;
+        const spanId = ctx && this.obs
+            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
+                name: 'delegation.hold',
+                attributes: {
+                    toolName,
+                    toolArgs: truncateForSpan(toolArgs),
+                    matchedPolicy: holdDecision.matchedPolicy ?? null,
+                },
+            })) ?? undefined
+            : undefined;
+        let caught;
+        let result;
+        let holdStatus = 'ok';
+        let holdError;
         try {
-            const approved = await this.client.checkApprovedDelegation(email, action, safeAmount);
-            if (approved) {
-                try {
-                    if (approved.delegationId) {
-                        await this.client.markDelegationExecuted(email, approved.delegationId);
+            const internals = this.client._sessionInternals();
+            const email = userEmail ?? internals.userId ?? 'unknown@armoriq';
+            const { mcp, action } = this.toolNameParser(toolName);
+            const resolvedMcp = this.mcpByAction.get(action) ?? mcp;
+            const rawAmount = ArmorIQSession.extractAmount(toolArgs) ?? 0;
+            const safeAmount = typeof rawAmount === 'number' && rawAmount >= 0.01 ? rawAmount : 0.01;
+            try {
+                const approved = await this.client.checkApprovedDelegation(email, action, safeAmount);
+                if (approved) {
+                    try {
+                        if (approved.delegationId) {
+                            await this.client.markDelegationExecuted(email, approved.delegationId);
+                        }
                     }
+                    catch {
+                        // best-effort
+                    }
+                    result = {
+                        allowed: true,
+                        action: 'allow',
+                        reason: `Allowed by approved delegation ${approved.delegationId ?? ''}`.trim(),
+                        delegationId: approved.delegationId,
+                        matchedPolicy: holdDecision.matchedPolicy,
+                        obligations: holdDecision.obligations ?? [],
+                    };
+                    return result;
                 }
-                catch {
-                    // best-effort
-                }
-                return {
-                    allowed: true,
-                    action: 'allow',
-                    reason: `Allowed by approved delegation ${approved.delegationId ?? ''}`.trim(),
-                    delegationId: approved.delegationId,
-                    matchedPolicy: holdDecision.matchedPolicy,
-                };
             }
+            catch {
+                // best-effort
+            }
+            let delegationId;
+            try {
+                const r = await this.client.createDelegationRequest({
+                    tool: action,
+                    action,
+                    arguments: toolArgs,
+                    amount: safeAmount,
+                    requesterEmail: email,
+                    requesterRole: 'agent_user',
+                    requesterLimit: 0,
+                    domain: resolvedMcp,
+                    planId: this.currentToken?.planId,
+                    intentReference: this.currentToken?.tokenId,
+                    merkleRoot: (this.currentToken?.rawToken ?? {}).merkle_root,
+                    reason: holdDecision.reason,
+                });
+                delegationId = r.delegationId;
+            }
+            catch (e) {
+                console.warn(`createDelegationRequest failed: ${e.message}`);
+            }
+            result = {
+                allowed: false,
+                action: 'hold',
+                reason: holdDecision.reason ?? 'Pending approval',
+                delegationId,
+                matchedPolicy: holdDecision.matchedPolicy,
+                obligations: holdDecision.obligations ?? [],
+            };
+            return result;
         }
-        catch {
-            // best-effort
+        catch (err) {
+            caught = err;
+            holdStatus = 'error';
+            holdError = err.message;
+            throw err;
         }
-        let delegationId;
-        try {
-            // The conmap-auto DTO requires amount/requesterRole/requesterLimit; for
-            // non-financial holds (PHI write, prior-auth, etc.) the SDK supplies
-            // healthcare-shaped defaults so the row gets created. The approver UI
-            // can read the original tool args from `arguments`. requesterRole
-            // matches the default used elsewhere in the SDK (resolveUserRole
-            // fallback in client.ts).
-            const result = await this.client.createDelegationRequest({
-                tool: action,
-                action,
-                arguments: toolArgs,
-                amount: safeAmount,
-                requesterEmail: email,
-                requesterRole: 'agent_user',
-                requesterLimit: 0,
-                domain: resolvedMcp,
-                planId: this.currentToken?.planId,
-                intentReference: this.currentToken?.tokenId,
-                merkleRoot: (this.currentToken?.rawToken ?? {}).merkle_root,
-                reason: holdDecision.reason,
-            });
-            delegationId = result.delegationId;
+        finally {
+            if (ctx) {
+                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
+                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeSpanRecord(ctx, 'delegation.hold', {
+                    kind: 'span',
+                    delegationId: result?.delegationId ?? null,
+                    decision: result?.action ?? 'hold',
+                    errorMessage: holdError,
+                }, holdStatus === 'error' ? 'error' : 'ok', computedDuration ?? null, spanId)));
+                if (spanId) {
+                    safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
+                        status: holdStatus === 'error' ? 'error' : 'ok',
+                        durationMs: computedDuration,
+                        errorMessage: holdError,
+                    }));
+                }
+            }
         }
-        catch (e) {
-            console.warn(`createDelegationRequest failed: ${e.message}`);
-        }
-        return {
-            allowed: false,
-            action: 'hold',
-            reason: holdDecision.reason ?? 'Pending approval',
-            delegationId,
-            matchedPolicy: holdDecision.matchedPolicy,
-        };
     }
     /**
      * Poll a held delegation until it is decided; non-blocking (async).
@@ -545,38 +1296,86 @@ class ArmorIQSession {
      * timeout/interval are in seconds (mirrors the Python SDK await_approval).
      */
     async awaitApproval(delegationId, opts = {}) {
-        const timeout = opts.timeout ?? 300;
-        const interval = opts.interval ?? 5;
-        const transient = new Set([429, 502, 503, 504]);
-        const email = opts.userEmail || this.client.userId || 'unknown@armoriq';
-        const sleep = (s) => new Promise((r) => setTimeout(r, s * 1000));
-        let waited = 0;
-        while (waited < timeout) {
-            await sleep(interval);
-            waited += interval;
-            let status;
-            try {
-                status = await this.client.getDelegationStatus(delegationId);
-            }
-            catch (e) {
-                if (e instanceof exceptions_1.DelegationException &&
-                    e.statusCode &&
-                    transient.has(e.statusCode)) {
-                    const backoff = Math.min(interval * 2, 15);
-                    await sleep(backoff);
-                    waited += backoff;
-                    continue;
+        const startNs = this.obs ? performance.now() : 0;
+        const ctx = this.obs ? this.ensurePlanTrace() : null;
+        const spanId = ctx && this.obs
+            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
+                name: 'delegation.poll',
+                attributes: { delegationId, timeout: opts.timeout ?? 300, interval: opts.interval ?? 5 },
+            })) ?? undefined
+            : undefined;
+        let caught;
+        let pollOutcome = 'timeout';
+        try {
+            const timeout = opts.timeout ?? 300;
+            const interval = opts.interval ?? 5;
+            const transient = new Set([429, 502, 503, 504]);
+            const email = opts.userEmail || this.client.userId || 'unknown@armoriq';
+            const sleep = (s) => new Promise((r) => setTimeout(r, s * 1000));
+            let waited = 0;
+            let pollCount = 0;
+            while (waited < timeout) {
+                await sleep(interval);
+                waited += interval;
+                pollCount += 1;
+                let status;
+                try {
+                    status = await this.client.getDelegationStatus(delegationId);
+                }
+                catch (e) {
+                    if (e instanceof exceptions_1.DelegationException &&
+                        e.statusCode &&
+                        transient.has(e.statusCode)) {
+                        const backoff = Math.min(interval * 2, 15);
+                        await sleep(backoff);
+                        waited += backoff;
+                        continue;
+                    }
+                    throw e;
+                }
+                if (ctx) {
+                    safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeEventRecord(ctx, 'delegation.poll.tick', {
+                        kind: 'event',
+                        message: `poll #${pollCount} status=${status}`,
+                        level: 'info',
+                        delegationId,
+                    }, spanId)));
+                }
+                if (status === 'approved') {
+                    await this.client.markDelegationExecuted(email, delegationId);
+                    pollOutcome = 'approved';
+                    return 'approved';
+                }
+                if (status === 'rejected') {
+                    pollOutcome = 'rejected';
+                    return 'rejected';
                 }
-                throw e;
             }
-            if (status === 'approved') {
-                await this.client.markDelegationExecuted(email, delegationId);
-                return 'approved';
+            pollOutcome = 'timeout';
+            return 'timeout';
+        }
+        catch (err) {
+            caught = err;
+            throw err;
+        }
+        finally {
+            if (ctx) {
+                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
+                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeSpanRecord(ctx, 'delegation.poll.terminal', {
+                    kind: 'span',
+                    delegationId,
+                    decision: pollOutcome,
+                    errorMessage: caught instanceof Error ? caught.message : undefined,
+                }, caught ? 'error' : 'ok', computedDuration ?? null, spanId)));
+                if (spanId) {
+                    safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
+                        status: caught ? 'error' : 'ok',
+                        durationMs: computedDuration,
+                        errorMessage: caught instanceof Error ? caught.message : undefined,
+                    }));
+                }
             }
-            if (status === 'rejected')
-                return 'rejected';
         }
-        return 'timeout';
     }
     static extractAmount(args) {
         if (!args || typeof args !== 'object')
@@ -640,31 +1439,63 @@ class ArmorIQSession {
      *     reanchor is off
      */
     async flushReanchor() {
-        if (!this.pendingReanchorPlan) {
-            return { fired: false };
-        }
-        if (!this.currentToken) {
-            this.pendingReanchorPlan = undefined;
-            return { fired: false };
-        }
-        if (!this.trueReanchor && !this.autoReanchor) {
-            this.pendingReanchorPlan = undefined;
-            return { fired: false };
-        }
-        const planToFlush = this.pendingReanchorPlan;
-        // Optimistically clear so a retry in the caller doesn't double-fire.
-        this.pendingReanchorPlan = undefined;
+        const startNs = this.obs ? performance.now() : 0;
+        const ctx = this.obs ? this.ensurePlanTrace() : null;
+        const spanId = ctx && this.obs
+            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
+                name: 'iap.reanchor.flush',
+                attributes: {
+                    hasPendingPlan: !!this.pendingReanchorPlan,
+                    hasToken: !!this.currentToken,
+                },
+            })) ?? undefined
+            : undefined;
+        let caught;
+        let fired = false;
+        let trustId;
         try {
-            const result = await this.client.reanchor(this.currentToken, planToFlush, 'flush at request boundary');
-            return { fired: true, trustId: result?.trustId };
+            if (!this.pendingReanchorPlan) {
+                return { fired: false };
+            }
+            if (!this.currentToken) {
+                this.pendingReanchorPlan = undefined;
+                return { fired: false };
+            }
+            if (!this.trueReanchor && !this.autoReanchor) {
+                this.pendingReanchorPlan = undefined;
+                return { fired: false };
+            }
+            const planToFlush = this.pendingReanchorPlan;
+            this.pendingReanchorPlan = undefined;
+            const result = await this.reanchorCall(this.currentToken, planToFlush, 'flush at request boundary');
+            fired = true;
+            trustId = result.trustId;
+            return { fired: true, trustId };
         }
         catch (err) {
-            // Best-effort: log and stay silent so a flaky IAP doesn't gate
-            // session lifecycle.
+            caught = err;
             const msg = err instanceof Error ? err.message : String(err);
             console.warn(`[armoriq] flushReanchor failed: ${msg}`);
             return { fired: false };
         }
+        finally {
+            if (ctx) {
+                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
+                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeSpanRecord(ctx, 'iap.reanchor.flush.result', {
+                    kind: 'span',
+                    fired,
+                    trustId: trustId ?? null,
+                    errorMessage: caught instanceof Error ? caught.message : undefined,
+                }, caught ? 'error' : 'ok', null, spanId)));
+                if (spanId) {
+                    safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
+                        status: caught ? 'error' : 'ok',
+                        durationMs: computedDuration,
+                        errorMessage: caught instanceof Error ? caught.message : undefined,
+                    }));
+                }
+            }
+        }
     }
     get currentTokenValue() {
         return this.currentToken;
@@ -672,6 +1503,64 @@ class ArmorIQSession {
     get currentMode() {
         return this.mode;
     }
+    /**
+     * Force-flush all buffered observability traces/spans to the backend ingest
+     * endpoint. No-op when observability is disabled (`observability.enabled: false`).
+     *
+     * Call this at the request boundary (e.g. Stop hook in armorClaude, end of
+     * turn in ADK consumers) to guarantee all spans for the current session have
+     * been POSTed before the process exits. The underlying shipper retries with
+     * exponential backoff and **never throws** into the SDK consumer — a flush
+     * failure is logged and the spans are dropped.
+     */
+    async flushObservability() {
+        if (!this.obs)
+            return;
+        // Model A: end the in-flight active plan trace FIRST so it's handed to
+        // the shipper's queue before we flush — otherwise an in-progress plan
+        // trace (no endTime yet) would be left behind in the ring buffer and
+        // never ship (see ObservabilityRecorder.flush()'s in-flight retention).
+        safeObs(() => this.endPlanTrace('ok'));
+        await (0, observability_1.flushObservability)(this.obs);
+    }
+    /**
+     * Stop the session's observability lifecycle: clears the shipper's
+     * repeating flush interval (`setInterval`, see `ObservabilityShipper`) and
+     * performs one final drain/flush of anything still queued. Safe to call
+     * multiple times; a no-op when observability is disabled.
+     *
+     * **Required at session end.** Without calling this, the recorder's
+     * shipper keeps its interval timer alive indefinitely — in long-running
+     * processes this is a resource leak, and in tests it is why processes
+     * (and jest) can hang or emit "cannot log after tests done" / stray
+     * network activity after teardown. `flushObservability()` alone does NOT
+     * stop the interval — it only flushes; call `close()` (or `dispose()`) at
+     * the natural end of the session's lifetime (e.g. Stop hook in armorClaude,
+     * end of process, or end of a request/turn in ADK consumers) instead of
+     * (or in addition to) `flushObservability()`.
+     *
+     * NEVER throws — observability teardown failures must not propagate into
+     * the SDK consumer, matching every other observability code path.
+     */
+    async close() {
+        if (!this.obs)
+            return;
+        // Model A: end the active plan trace before stopping the shipper so its
+        // final flush (inside obs.stop()) ships the completed plan trace rather
+        // than leaving it stranded in-flight.
+        safeObs(() => this.endPlanTrace('ok'));
+        try {
+            await this.obs.stop();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`[armoriq] observability close() failed (continuing): ${msg}`);
+        }
+    }
+    /** Alias for `close()`. Use whichever reads better at the call site. */
+    async dispose() {
+        await this.close();
+    }
 }
 exports.ArmorIQSession = ArmorIQSession;
 //# sourceMappingURL=session.js.map