@planu/cli 4.13.0 → 5.0.0

package/dist/tools/safe-handler.js

@@ -1,20 +1,18 @@
 // tools/safe-handler.ts — Generic error-boundary wrapper for MCP tool handlers.
 // Catches any unhandled error and returns a graceful MCP error response
-// instead of crashing the server. Includes execution timeout via Promise.race.
-import { withLicenseGate, withUsageTracking } from './license-gate.js';
-import { isTrialActive } from '../engine/trial-engine.js';
+// instead of crashing the server. Includes cancellation-aware execution deadlines.
+import { withUsageTracking } from './usage-tracking.js';
 import { sanitizePath } from './sanitize-path.js';
 import { ensureHooksStarted } from './start-hooks.js';
 import { ensureWorkersStarted } from '../engine/workers/index.js';
 import { recordError } from '../storage/error-telemetry-store.js';
 import { hashProjectPath } from '../storage/base-store.js';
-import { reportToolError, reportToolValidationError, isErrorReportingEnabled, } from '../engine/telemetry/error-reporter.js';
+import { reportToolError, reportToolValidationError } from '../engine/telemetry/error-reporter.js';
 import { sendTelemetryEvent } from '../engine/telemetry/telemetry-client.js';
 import { PLANU_VERSION } from '../config/version.js';
 import { recordToolTokens, extractOutputText } from './token-recording.js';
 import { DriftCacheStore } from '../storage/drift-cache-store.js';
 import { consumeUpdateBanner } from '../engine/update-notifier.js';
-import { getOrCreateInstallationId } from '../engine/telemetry/telemetry-store.js';
 import { compressToolOutput } from './output-compressor.js';
 import { recordToolTokens as recordLlmTokens } from '../engine/llm-runtime/index.js';
 import { guardToolResultOutput } from './output-integrity-guard.js';
@@ -26,7 +24,7 @@ import { checkBudgetEnforcement } from '../engine/cost-guardrails.js';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { maybeWriteCheckpoint } from '../engine/session/checkpoint-writer.js';
-import { AsyncLocalStorage } from 'node:async_hooks';
+import { createChildCancellationScope, createExecutionScope, ExecutionCancelledError, getExecutionSignal, } from '../engine/execution/context.js';
 // SPEC-922: Compact response auto-on
 import { parseContextHeader } from '../engine/compact/header-parser.js';
 import { evaluateCompactMode } from '../engine/compact/threshold-evaluator.js';
@@ -34,6 +32,13 @@ import { loadCompactThresholds } from '../engine/compact/registry-loader.js';
 import { applyCompactMode } from '../engine/compact/compact-middleware.js';
 import { globalCompactStateStore } from '../engine/compact/state-store.js';
 import { recordCompactDecision, recordVerboseDecision, recordNoHeader, } from '../engine/compact/metrics.js';
+import { getSessionContext } from '../transports/session-context.js';
+import { LocalExecutionSpan } from '../engine/observability/local-execution-spans.js';
+import { classifyBoundaryFailure } from '../errors/error-taxonomy.js';
+import { boundedEnvironmentDuration, getRuntimePolicy } from '../engine/runtime-policy.js';
+function reportOptionalDegradation(component, error) {
+    console.warn(classifyBoundaryFailure(error, component, 'The primary operation completed; inspect local diagnostics before relying on this optional output.').message);
+}
 // ---------------------------------------------------------------------------
 // Project initialization state — read-only check, zero file writes
 // ---------------------------------------------------------------------------
@@ -87,36 +92,41 @@ function getDriftBannerThreshold() {
 }
 /**
  * Checks for pending drift cache entries for a project.
- * Returns a banner string if any pending entry has driftScore >= threshold,
- * or null if nothing to show.
- * Marks all pending entries as shown (fire-and-forget).
+ * Returns the banner and a deferred acknowledgement effect. The caller invokes
+ * that effect only after every awaited postprocessing step has completed.
  */
-async function checkPendingDriftBanner(projectPath) {
+async function checkPendingDriftBanner(projectPath, signal) {
+    const noBanner = { banner: null, acknowledge: () => undefined };
     if (process.env.PLANU_AUTO_DRIFT === 'false') {
-        return null;
+        return noBanner;
     }
     try {
+        signal.throwIfAborted();
         const projectId = hashProjectPath(projectPath);
         const store = new DriftCacheStore(projectId);
         const threshold = getDriftBannerThreshold();
         const pending = await store.getPendingBanners(threshold);
+        signal.throwIfAborted();
         if (pending.length === 0) {
-            return null;
+            return noBanner;
         }
-        // Mark as shown — fire-and-forget
-        /* v8 ignore start */
-        store.markAllShown().catch((err) => {
-            console.error('[Planu] Failed to mark drift banners as shown:', err);
-        });
-        /* v8 ignore stop */
         const specIds = pending.map((e) => e.specId).join(', ');
         const maxScore = Math.max(...pending.map((e) => e.driftScore));
-        return (`\n⚠️  Auto-drift alert: specs [${specIds}] may have drifted ` +
-            `(score: ${maxScore.toFixed(2)}). Run detect_drift to review.`);
+        return {
+            banner: `\n⚠️  Auto-drift alert: specs [${specIds}] may have drifted ` +
+                `(score: ${maxScore.toFixed(2)}). Run detect_drift to review.`,
+            acknowledge: () => {
+                /* v8 ignore start */
+                void store.markAllShown().catch((err) => {
+                    reportOptionalDegradation('drift banner acknowledgement', err);
+                });
+                /* v8 ignore stop */
+            },
+        };
     }
     catch {
         // Never block a tool call due to drift cache errors
-        return null;
+        return noBanner;
     }
 }
 /**
@@ -165,18 +175,15 @@ function sanitizeArgs(args, toolName) {
     }
     return obj;
 }
-/** Keep the server deadline below the common 60s client deadline. */
-const DEFAULT_TIMEOUT_MS = 55_000;
-const toolAbortContext = new AsyncLocalStorage();
 const activeToolControllers = new Set();
 /** Signal for the currently executing tool, including server deadline and client cancellation. */
 export function getToolExecutionSignal() {
-    return toolAbortContext.getStore();
+    return getExecutionSignal();
 }
 /** Abort every in-flight tool before stdio shutdown closes the transport. */
 export function abortActiveToolExecutions(reason = 'MCP transport closed') {
     for (const controller of activeToolControllers) {
-        controller.abort(new Error(reason));
+        controller.abort(new ExecutionCancelledError(reason));
     }
 }
 /**
@@ -185,23 +192,80 @@ export function abortActiveToolExecutions(reason = 'MCP transport closed') {
  */
 const SESSION_ID = `SES-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 function getTimeoutMs() {
-    const envVal = process.env.PLANU_TOOL_TIMEOUT_MS;
-    if (envVal === undefined || envVal === '') {
-        return DEFAULT_TIMEOUT_MS;
-    }
-    const parsed = Number(envVal);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_TIMEOUT_MS;
+    return boundedEnvironmentDuration('PLANU_TOOL_TIMEOUT_MS', getRuntimePolicy().toolExecution);
 }
 /**
  * Races a handler promise against a timeout. Returns a timeout error ToolResult
  * if the handler exceeds the configured duration.
  */
-async function withTimeout(fn, ms, upstreamSignal) {
-    let timer;
+function deadlineSafetyMargin(ms) {
+    const policy = getRuntimePolicy().toolExecution;
+    return Math.min(policy.safetyMarginMaximumMs, Math.max(policy.minimumTimeoutMs, Math.floor(ms * policy.safetyMarginRatio)));
+}
+function executionMeasurements(value) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    }
+    catch {
+        serialized = '';
+    }
+    const files = value !== null && typeof value === 'object'
+        ? Object.entries(value).filter(([key, entry]) => /(?:file|path)s?$/iu.test(key) && entry !== undefined).length
+        : 0;
+    return {
+        lockWaitMs: 0,
+        files,
+        bytes: Buffer.byteLength(serialized),
+        subprocess: false,
+    };
+}
+function commitState(phase) {
+    return phase === 'committed' || phase === 'acknowledged' ? phase : 'pre-commit';
+}
+function requestIdentity(extra) {
+    if (extra === null || typeof extra !== 'object') {
+        return {};
+    }
+    const record = extra;
+    return {
+        ...(typeof record.requestId === 'string' && record.requestId.trim() !== ''
+            ? { requestId: record.requestId }
+            : {}),
+        ...(typeof record.idempotencyKey === 'string' && record.idempotencyKey.trim() !== ''
+            ? { idempotencyKey: record.idempotencyKey }
+            : {}),
+    };
+}
+function requestAbortSignal(extra) {
+    const sdkSignal = extra !== null &&
+        typeof extra === 'object' &&
+        extra.signal instanceof AbortSignal
+        ? extra.signal
+        : undefined;
+    const transportSignal = getSessionContext()?.signal;
+    if (sdkSignal && transportSignal) {
+        return AbortSignal.any([sdkSignal, transportSignal]);
+    }
+    return sdkSignal ?? transportSignal;
+}
+async function withTimeout(fn, ms, upstreamSignal, identity = {}, operation = 'tool', measurements = {
+    lockWaitMs: 0,
+    files: 0,
+    bytes: 0,
+    subprocess: false,
+}) {
     const controller = new AbortController();
+    const deadlineAt = Date.now() + ms;
+    const responseTimeoutMs = Math.max(0, ms - deadlineSafetyMargin(ms));
     activeToolControllers.add(controller);
     const abortFromUpstream = () => {
-        controller.abort(upstreamSignal?.reason ?? new Error('Tool request aborted'));
+        const reason = upstreamSignal?.reason;
+        controller.abort(new ExecutionCancelledError(reason instanceof Error
+            ? reason.message
+            : typeof reason === 'string'
+                ? reason
+                : 'Tool request aborted'));
     };
     if (upstreamSignal?.aborted === true) {
         abortFromUpstream();
@@ -209,42 +273,74 @@ async function withTimeout(fn, ms, upstreamSignal) {
     else {
         upstreamSignal?.addEventListener('abort', abortFromUpstream, { once: true });
     }
-    const timeoutPromise = new Promise((_resolve, reject) => {
-        timer = setTimeout(() => {
-            const error = new Error(`Tool execution timed out after ${ms}ms`);
-            controller.abort(error);
-            reject(error);
-        }, ms);
+    const scope = createExecutionScope({
+        deadlineAt,
+        upstreamSignal: controller.signal,
+        ...identity,
+    });
+    const localSpan = new LocalExecutionSpan({
+        requestId: scope.context.requestId,
+        operationId: identity.idempotencyKey ?? scope.context.requestId,
+        operation,
+        deadlineAt,
+        ...measurements,
     });
-    const abortPromise = new Promise((_resolve, reject) => {
+    const handlerPromise = scope.run(() => fn(scope.context.signal));
+    // Keep an explicit terminal observer because the response path intentionally
+    // never awaits abandoned work.
+    void handlerPromise.then(() => {
+        localSpan.complete(scope.context.phase, commitState(scope.context.phase));
+    }, () => {
+        localSpan.complete(scope.context.phase, commitState(scope.context.phase));
+    });
+    const responsePromise = new Promise((resolve, reject) => {
+        let settled = false;
         const rejectAbort = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
             const reason = controller.signal.reason;
-            const error = reason instanceof Error
+            reject(reason instanceof Error
                 ? reason
-                : new Error(typeof reason === 'string' ? reason : 'Tool request aborted');
-            reject(error);
+                : new Error(typeof reason === 'string' ? reason : 'Tool request aborted'));
         };
+        controller.signal.addEventListener('abort', rejectAbort, { once: true });
+        handlerPromise.then((value) => {
+            if (!settled) {
+                settled = true;
+                controller.signal.removeEventListener('abort', rejectAbort);
+                resolve(value);
+            }
+        }, (error) => {
+            if (!settled) {
+                settled = true;
+                controller.signal.removeEventListener('abort', rejectAbort);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
         if (controller.signal.aborted) {
             rejectAbort();
         }
-        else {
-            controller.signal.addEventListener('abort', rejectAbort, { once: true });
-        }
     });
-    const handlerPromise = toolAbortContext.run(controller.signal, () => fn(controller.signal));
+    const timer = setTimeout(() => {
+        localSpan.timeout(scope.context.phase, commitState(scope.context.phase));
+        const error = new ExecutionCancelledError(`Tool execution timed out after ${ms}ms`);
+        controller.abort(error);
+        scope.cancel(error);
+    }, responseTimeoutMs);
     try {
-        return await Promise.race([handlerPromise, timeoutPromise, abortPromise]);
-    }
-    catch (error) {
-        if (controller.signal.aborted) {
-            await handlerPromise.then(() => undefined, () => undefined);
-        }
-        throw error;
+        return await responsePromise;
     }
     finally {
+        scope.acknowledge();
+        scope.dispose();
         clearTimeout(timer);
         upstreamSignal?.removeEventListener('abort', abortFromUpstream);
         activeToolControllers.delete(controller);
+        if (!localSpan.didTimeout) {
+            localSpan.complete(scope.context.phase, commitState(scope.context.phase));
+        }
     }
 }
 /**
@@ -257,25 +353,41 @@ async function withTimeout(fn, ms, upstreamSignal) {
  * @param fallback - Value returned when the timeout fires
  */
 export function withToolTimeout(p, ms, fallback) {
-    let t;
-    const timeout = new Promise((res) => {
-        t = setTimeout(() => {
-            res(fallback);
-        }, ms);
+    const scope = createChildCancellationScope(ms);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (value) => {
+            if (!settled) {
+                settled = true;
+                scope.signal.removeEventListener('abort', onAbort);
+                scope.dispose();
+                resolve(value);
+            }
+        };
+        const fail = (error) => {
+            if (!settled) {
+                settled = true;
+                scope.signal.removeEventListener('abort', onAbort);
+                scope.dispose();
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        };
+        const onAbort = () => {
+            finish(fallback);
+        };
+        scope.signal.addEventListener('abort', onAbort, { once: true });
+        p.then(finish, fail);
+        if (scope.signal.aborted) {
+            onAbort();
+        }
     });
-    return Promise.race([
-        p.finally(() => {
-            clearTimeout(t);
-        }),
-        timeout,
-    ]);
 }
 /**
  * Wraps a tool handler so that any unhandled error is caught and returned as a
  * graceful MCP error response, preventing server crashes. Also enforces a
  * configurable execution timeout (default 55s, env PLANU_TOOL_TIMEOUT_MS).
  *
- * Usage — only for alwaysAllowed tools (activate_license, license_status, etc.):
+ * Usage — for infrastructure tools that do not need usage recording:
  *   server.registerTool('my_tool', schema, safe(async (args) => { ... }));
  */
 export function safe(handler) {
@@ -312,61 +424,95 @@ function safeWithTelemetry(toolName, handler) {
             recordVerboseDecision();
         }
         try {
-            const upstreamSignal = extra &&
-                typeof extra === 'object' &&
-                extra.signal instanceof AbortSignal
-                ? extra.signal
-                : undefined;
-            const rawResult = (await withTimeout((signal) => handler(safeArgs, {
-                ...(extra && typeof extra === 'object' ? extra : {}),
-                signal,
-            }), getTimeoutMs(), upstreamSignal));
-            // Defensive guard: belt-and-suspenders alongside withUsageTracking guard and noImplicitReturns.
-            const result = rawResult ?? {
-                content: [{ type: 'text', text: 'Internal error: tool handler returned no result' }],
-                isError: true,
-            };
-            // SPEC-455: Compress verbose JSON outputs to save LLM tokens
-            const compressed = compressToolOutput(result);
-            // SPEC-922: Apply compact mode middleware
-            const compacted = applyCompactMode(compressed, decision, {
-                projectPath,
-                flow: toolName,
-            });
-            // Inject pending drift banner (non-blocking, informational only)
-            const driftBanner = projectPath !== undefined ? await checkPendingDriftBanner(projectPath) : null;
-            const withDrift = injectDriftBanner(compacted, driftBanner);
-            // Inject update banner (once per version check, consumed and cleared)
-            const updateBanner = consumeUpdateBanner();
-            const finalResult = updateBanner !== null && withDrift.isError !== true
-                ? {
-                    ...withDrift,
-                    content: [...withDrift.content, { type: 'text', text: updateBanner }],
+            const upstreamSignal = requestAbortSignal(extra);
+            const guardedResult = await withTimeout(async (signal) => {
+                const rawResult = (await handler(safeArgs, {
+                    ...(extra && typeof extra === 'object' ? extra : {}),
+                    signal,
+                }));
+                signal.throwIfAborted();
+                // Defensive guard: belt-and-suspenders alongside withUsageTracking guard and noImplicitReturns.
+                const result = rawResult ?? {
+                    content: [{ type: 'text', text: 'Internal error: tool handler returned no result' }],
+                    isError: true,
+                };
+                // SPEC-455: Compress verbose JSON outputs to save LLM tokens
+                const compressed = compressToolOutput(result);
+                // SPEC-922: Apply compact mode middleware
+                const compacted = applyCompactMode(compressed, decision, {
+                    projectPath,
+                    flow: toolName,
+                });
+                // Postprocessing remains inside the request cancellation tree. In
+                // particular, a disconnect while reading drift state cannot start
+                // the shown-marker, token, audit or checkpoint effects afterwards.
+                const driftBanner = projectPath !== undefined
+                    ? await checkPendingDriftBanner(projectPath, signal)
+                    : { banner: null, acknowledge: () => undefined };
+                signal.throwIfAborted();
+                const withDrift = injectDriftBanner(compacted, driftBanner.banner);
+                const updateBanner = consumeUpdateBanner();
+                const finalResult = updateBanner !== null && withDrift.isError !== true
+                    ? {
+                        ...withDrift,
+                        content: [...withDrift.content, { type: 'text', text: updateBanner }],
+                    }
+                    : withDrift;
+                const processedResult = guardToolResultOutput(toolName, finalResult);
+                signal.throwIfAborted();
+                let appendAudit;
+                /* v8 ignore start */
+                if (toolName !== undefined) {
+                    try {
+                        const [{ appendEntry, getLastHash }, { buildAuditEntry }, { hashEntry }] = await Promise.all([
+                            import('../storage/audit-trail-store.js'),
+                            import('../engine/audit-trail/formatter.js'),
+                            import('../engine/audit-trail/hasher.js'),
+                        ]);
+                        signal.throwIfAborted();
+                        appendAudit = () => {
+                            const prevHash = getLastHash();
+                            const partial = buildAuditEntry({
+                                toolName,
+                                args,
+                                outputType: processedResult.isError === true ? 'error' : 'success',
+                                durationMs: Date.now() - startTime,
+                                prevHash,
+                            });
+                            appendEntry({ ...partial, hash: hashEntry(partial) });
+                        };
+                    }
+                    catch (error) {
+                        if (signal.aborted) {
+                            throw signal.reason;
+                        }
+                        reportOptionalDegradation('tool success audit', error);
+                    }
                 }
-                : withDrift;
-            const guardedResult = guardToolResultOutput(toolName, finalResult);
-            // Report validation errors (isError:true returned by handler logic, not exceptions)
-            if (toolName !== undefined && guardedResult.isError === true) {
-                const firstContent = guardedResult.content[0];
-                const errText = firstContent?.type === 'text' ? firstContent.text : 'unknown error';
-                reportToolValidationError(toolName, errText);
-            }
-            // Record token usage for successful calls (fire-and-forget, only when projectPath available)
-            if (toolName !== undefined && projectPath !== undefined && guardedResult.isError !== true) {
-                const outputText = extractOutputText(guardedResult);
-                recordToolTokens(toolName, projectPath, args, outputText, SESSION_ID);
-            }
-            // SPEC-460: Track real token estimates in LLM runtime (session-scoped, measured)
-            if (toolName !== undefined) {
-                const inputText = JSON.stringify(args);
-                const outputText = extractOutputText(guardedResult);
-                recordLlmTokens(toolName, inputText, outputText);
-            }
-            // Emit tool_used telemetry for successful calls (fire-and-forget)
-            /* v8 ignore start */
-            if (toolName !== undefined && guardedResult.isError !== true && isErrorReportingEnabled()) {
-                getOrCreateInstallationId()
-                    .then((installationId) => {
+                /* v8 ignore stop */
+                signal.throwIfAborted();
+                // Report validation errors (isError:true returned by handler logic, not exceptions)
+                if (toolName !== undefined && processedResult.isError === true) {
+                    const firstContent = processedResult.content[0];
+                    const errText = firstContent?.type === 'text' ? firstContent.text : 'unknown error';
+                    reportToolValidationError(toolName, errText);
+                }
+                // Record token usage for successful calls (fire-and-forget, only when projectPath available)
+                if (toolName !== undefined &&
+                    projectPath !== undefined &&
+                    processedResult.isError !== true) {
+                    const outputText = extractOutputText(processedResult);
+                    recordToolTokens(toolName, projectPath, args, outputText, SESSION_ID);
+                }
+                // SPEC-460: Track real token estimates in LLM runtime (session-scoped, measured)
+                if (toolName !== undefined) {
+                    const inputText = JSON.stringify(args);
+                    const outputText = extractOutputText(processedResult);
+                    recordLlmTokens(toolName, inputText, outputText);
+                }
+                // Emit tool_used telemetry for successful calls (fire-and-forget)
+                /* v8 ignore start */
+                if (toolName !== undefined && processedResult.isError !== true) {
                     sendTelemetryEvent({
                         event: 'tool_used',
                         properties: {
@@ -376,47 +522,24 @@ function safeWithTelemetry(toolName, handler) {
                             platform: process.platform,
                             durationMs: Date.now() - startTime,
                         },
-                        installationId,
                     });
-                })
-                    .catch(() => {
-                    /* best-effort — never block tool response */
-                });
-            }
-            /* v8 ignore stop */
-            // SPEC-387: Audit trail — fire-and-forget, never throws
-            /* v8 ignore start */
-            if (toolName !== undefined) {
-                try {
-                    const [{ appendEntry, getLastHash }, { buildAuditEntry }, { hashEntry }] = await Promise.all([
-                        import('../storage/audit-trail-store.js'),
-                        import('../engine/audit-trail/formatter.js'),
-                        import('../engine/audit-trail/hasher.js'),
-                    ]);
-                    const prevHash = getLastHash();
-                    const partial = buildAuditEntry({
-                        toolName,
-                        args,
-                        outputType: guardedResult.isError === true ? 'error' : 'success',
-                        durationMs: Date.now() - startTime,
-                        prevHash,
-                    });
-                    appendEntry({ ...partial, hash: hashEntry(partial) });
                 }
-                catch {
-                    // Silent — audit must never affect tool execution
+                /* v8 ignore stop */
+                // No awaited boundary remains below this point. Cancellation cannot
+                // interleave between the final check and these synchronous starters.
+                driftBanner.acknowledge();
+                appendAudit?.();
+                if (toolName !== undefined) {
+                    maybeWriteCheckpoint(toolName, processedResult.isError !== true, projectPath);
                 }
-            }
-            /* v8 ignore stop */
-            // SPEC-563: Auto session checkpoint — fire-and-forget, non-blocking
-            if (toolName !== undefined) {
-                maybeWriteCheckpoint(toolName, guardedResult.isError !== true, projectPath);
-            }
+                return processedResult;
+            }, getTimeoutMs(), upstreamSignal, requestIdentity(extra), toolName, executionMeasurements(safeArgs));
             return guardedResult;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            if (toolName !== undefined && projectPath !== undefined) {
+            const cancelledBeforeCommit = error instanceof ExecutionCancelledError;
+            if (!cancelledBeforeCommit && toolName !== undefined && projectPath !== undefined) {
                 const projectId = hashProjectPath(projectPath);
                 // Fire-and-forget: do not block the error response
                 recordError(projectId, {
@@ -426,12 +549,12 @@ function safeWithTelemetry(toolName, handler) {
                     message,
                     /* v8 ignore start */
                 }).catch((err) => {
-                    console.error('[Planu] Telemetry recording failed:', err);
+                    reportOptionalDegradation('local error telemetry', err);
                 });
                 /* v8 ignore stop */
             }
             // Remote error reporting — fire-and-forget, respects PLANU_TELEMETRY=off
-            if (toolName !== undefined) {
+            if (!cancelledBeforeCommit && toolName !== undefined) {
                 reportToolError(toolName, error);
             }
             // SPEC-902: Structured error contract with recovery hints
@@ -443,7 +566,7 @@ function safeWithTelemetry(toolName, handler) {
             // Log unmatched errors for registry improvement (fire-and-forget)
             /* v8 ignore start */
             const matchedRule = registry.match(error);
-            if (!matchedRule && toolName !== undefined) {
+            if (!cancelledBeforeCommit && !matchedRule && toolName !== undefined) {
                 void Promise.resolve().then(async () => {
                     try {
                         const { recordError: recordErrorTelemetry } = await import('../storage/error-telemetry-store.js');
@@ -453,25 +576,25 @@ function safeWithTelemetry(toolName, handler) {
                             module: `tools/${toolName}`,
                             severity: 'warning',
                             message: `Unmatched error: ${message}`,
-                        }).catch(() => {
-                            // best-effort logging, ignore failure
+                        }).catch((telemetryError) => {
+                            reportOptionalDegradation('unmatched error telemetry', telemetryError);
                         });
                     }
-                    catch {
-                        // best-effort
+                    catch (telemetryError) {
+                        reportOptionalDegradation('unmatched error telemetry import', telemetryError);
                     }
                 });
             }
             /* v8 ignore stop */
             // SPEC-387: Audit trail for error path — fire-and-forget, never throws
             /* v8 ignore start */
-            if (toolName !== undefined) {
-                try {
-                    const [{ appendEntry, getLastHash }, { buildAuditEntry }, { hashEntry }] = await Promise.all([
-                        import('../storage/audit-trail-store.js'),
-                        import('../engine/audit-trail/formatter.js'),
-                        import('../engine/audit-trail/hasher.js'),
-                    ]);
+            if (!cancelledBeforeCommit && toolName !== undefined) {
+                void Promise.all([
+                    import('../storage/audit-trail-store.js'),
+                    import('../engine/audit-trail/formatter.js'),
+                    import('../engine/audit-trail/hasher.js'),
+                ])
+                    .then(([{ appendEntry, getLastHash }, { buildAuditEntry }, { hashEntry }]) => {
                     const prevHash = getLastHash();
                     const partial = buildAuditEntry({
                         toolName,
@@ -481,10 +604,10 @@ function safeWithTelemetry(toolName, handler) {
                         prevHash,
                     });
                     appendEntry({ ...partial, hash: hashEntry(partial) });
-                }
-                catch {
-                    // Silent — audit must never affect tool execution
-                }
+                })
+                    .catch((auditError) => {
+                    reportOptionalDegradation('tool error audit', auditError);
+                });
             }
             /* v8 ignore stop */
             return errorResult;
@@ -492,26 +615,18 @@ function safeWithTelemetry(toolName, handler) {
     };
 }
 /**
- * Composable wrapper: usage tracking + error boundary.
- * Use for free-tier tools that need rate limiting and usage recording.
+ * Composable wrapper: neutral local usage tracking + error boundary.
  *
  * Usage:
- *   server.registerTool('free_tool', schema, safeTracked('free_tool', async (args) => { ... }));
+ *   server.registerTool('tracked_tool', schema, safeTracked('tracked_tool', async (args) => { ... }));
  */
 export function safeTracked(toolName, handler) {
     return safeWithTelemetry(toolName, withUsageTracking(toolName, handler));
 }
 /**
- * Composable wrapper: usage tracking + license gate + error boundary.
- * Use for tools that require a paid plan.
- *
- * Trial bypass: if the 30-day free trial is active, skips the license gate
- * entirely and routes to safeTracked (usage tracking without restriction).
- *
- * Usage:
- *   server.registerTool('pro_tool', schema, safeLicensed('pro_tool', async (args) => { ... }));
+ * Neutral governed wrapper: engineering budget + local usage + error boundary.
  */
-export function safeLicensed(toolName, handler) {
+export function safeGoverned(toolName, handler) {
     return safeWithTelemetry(toolName, async (args, extra) => {
         // Enforce spec budget limit when specId is present in args (opt-in enforcement)
         if (args !== null && typeof args === 'object') {
@@ -522,14 +637,7 @@ export function safeLicensed(toolName, handler) {
                 await checkBudgetEnforcement(specId, projectPath);
             }
         }
-        // Check server-backed 30-day trial (fast local read only)
-        if (process.env.PLANU_SKIP_TRIAL !== 'true') {
-            const trialActive = isTrialActive(); // always false — trial tools removed
-            if (trialActive) {
-                return withUsageTracking(toolName, handler)(args, extra);
-            }
-        }
-        return withUsageTracking(toolName, withLicenseGate(toolName, handler))(args, extra);
+        return withUsageTracking(toolName, handler)(args, extra);
     });
 }
 //# sourceMappingURL=safe-handler.js.map