mobile-debug-mcp 0.32.4 → 0.33.0

package/dist/interact/index.js

@@ -1,3 +1,6 @@
+import { currentReadinessWait, observeReadinessWait, isDeviceUnavailable } from '../observe/readiness.js';
+import { readinessDelay } from '../observe/readiness-service.js';
+import { isConditionBlocked } from './conditional-action.js';
 import { remainingBudget } from '../utils/operation-budget.js';
 import { createHash } from 'crypto';
 import { AndroidInteract } from './android.js';
@@ -419,6 +422,8 @@ export class ToolsInteract {
         }
     }
     static async _captureFingerprint(platform, deviceId) {
+        if (isConditionBlocked())
+            return null;
         try {
             const fingerprint = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
             return fingerprint?.fingerprint ?? null;
@@ -2068,7 +2073,8 @@ export class ToolsInteract {
         };
         return { found: true, element: outEl, score: scoreVal, confidence: scoreVal, resolution };
     }
-    static async waitForUIHandler({ selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry = { max_attempts: 1, backoff_ms: 0 }, platform, deviceId, singleObservation = false, singleAttempt = false, rejectAmbiguous = false }) {
+    static async waitForUIHandler({ selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry = { max_attempts: 1, backoff_ms: 0 }, platform, deviceId, singleObservation = false, singleAttempt = false, rejectAmbiguous = false, resolveTapTarget = false }) {
+        const readinessTracker = currentReadinessWait();
         const overallStart = Date.now();
         const requestedIndex = typeof match?.index === 'number' ? match.index : null;
         const requested = {
@@ -2127,7 +2133,12 @@ export class ToolsInteract {
                     remainingBudget();
                     totalPollCount++;
                     try {
+                        const acquisitionStarted = Date.now();
                         const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
+                        observeReadinessWait(tree, acquisitionStarted);
+                        // A failed acquisition cannot establish that the requested tap target is absent.
+                        if (resolveTapTarget && tree?.error && /ACTION_TIMEOUT|timed out/i.test(String(tree.error)))
+                            throw new Error('ACTION_TIMEOUT');
                         const elements = (tree && Array.isArray(tree.elements)) ? tree.elements : [];
                         const matches = [];
                         for (let i = 0; i < elements.length; i++) {
@@ -2213,7 +2224,8 @@ export class ToolsInteract {
                                 conditionMet = false;
                         }
                         else if (condition === 'clickable') {
-                            matchedElement = chosen ? (ToolsInteract._resolveActionableAncestor(elements, chosen) || chosen) : null;
+                            matchedElement = chosen ? (resolveTapTarget && (!ToolsInteract._isVisibleElement(chosen.el) || chosen.el.enabled === false)
+                                ? chosen : ToolsInteract._resolveActionableAncestor(elements, chosen) || chosen) : null;
                             if (matchedElement) {
                                 const b = matchedElement.el.bounds;
                                 const visibleFlag = !!matchedElement.el.visible && Array.isArray(b) && b.length >= 4 && (b[2] > b[0] && b[3] > b[1]);
@@ -2224,6 +2236,13 @@ export class ToolsInteract {
                             else
                                 conditionMet = false;
                         }
+                        // Waiting for a label to exist/be visible is distinct from resolving its
+                        // executable control. Reuse the clickable-wait ancestor policy without
+                        // promoting hidden or disabled labels into an unrelated enabled target.
+                        if (resolveTapTarget && conditionMet && matchedElement &&
+                            ToolsInteract._isVisibleElement(matchedElement.el) && matchedElement.el.enabled !== false) {
+                            matchedElement = ToolsInteract._resolveActionableAncestor(elements, matchedElement) ?? matchedElement;
+                        }
                         const resolvedPlatform = tree?.device?.platform === 'ios' ? 'ios' : (platform || 'android');
                         const resolvedDeviceId = tree?.device?.id || deviceId;
                         lastMatchedCount = matchedCount;
@@ -2236,7 +2255,7 @@ export class ToolsInteract {
                             if (matchedAt === null)
                                 matchedAt = now;
                             stableMatchCount++;
-                            if (stableMatchCount >= stableObservationCount) {
+                            if (stableMatchCount >= stableObservationCount && (!readinessTracker || readinessTracker.summary.state === 'settled')) {
                                 const latency_ms = now - overallStart;
                                 const outEl = lastMatchedElement;
                                 return {
@@ -2261,20 +2280,26 @@ export class ToolsInteract {
                         }
                     }
                     catch (e) {
+                        // Deadline expiry does not invalidate the last successfully observed state.
                         if (e instanceof Error && e.message === 'ACTION_TIMEOUT')
                             throw e;
+                        if (readinessTracker && !String(e).includes('READINESS_'))
+                            readinessTracker.unavailable();
+                        if (readinessTracker && isDeviceUnavailable(e))
+                            throw e;
                         // Non-fatal per-poll error; record and continue
-                        console.warn('waitForUI: poll error (non-fatal):', e instanceof Error ? e.message : String(e));
+                        if (!readinessTracker)
+                            console.warn('waitForUI: poll error (non-fatal):', e instanceof Error ? e.message : String(e));
                     }
                     if (singleAttempt)
                         break;
                     // Sleep until next poll
-                    await new Promise(r => setTimeout(r, effectivePoll || 50));
+                    await (readinessTracker ? readinessDelay(effectivePoll || 50) : new Promise(r => setTimeout(r, effectivePoll || 50)));
                 }
                 // Attempt timed out; if more attempts allowed, backoff then retry
                 if (attempts < maxAttempts) {
                     if (backoff > 0)
-                        await new Promise(r => setTimeout(r, backoff));
+                        await (readinessTracker ? readinessDelay(backoff) : new Promise(r => setTimeout(r, backoff)));
                     continue;
                 }
                 // Final failure for this call
@@ -2290,7 +2315,7 @@ export class ToolsInteract {
                     : ` observed ${lastMatchedCount} match(es)`;
                 return {
                     status: 'timeout',
-                    error: { code: 'ELEMENT_NOT_FOUND', message: `Condition ${condition} not satisfied within timeout;${matchNote}` },
+                    error: { code: readinessTracker ? 'TIMEOUT' : 'ELEMENT_NOT_FOUND', message: `Condition ${condition} not satisfied within timeout;${matchNote}` },
                     metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts },
                     requested,
                     observed
@@ -2298,17 +2323,19 @@ export class ToolsInteract {
             }
         }
         catch (err) {
-            if (err instanceof Error && err.message === 'ACTION_TIMEOUT')
+            if (!readinessTracker && err instanceof Error && err.message === 'ACTION_TIMEOUT')
+                throw err;
+            if (readinessTracker && isDeviceUnavailable(err))
                 throw err;
             const elapsed = Date.now() - overallStart;
             return {
                 status: 'timeout',
-                error: { code: 'INTERNAL_ERROR', message: err instanceof Error ? err.message : String(err) },
+                error: { code: readinessTracker && String(err).includes('ACTION_TIMEOUT') ? 'TIMEOUT' : 'INTERNAL_ERROR', message: readinessTracker ? 'Readiness predicate wait did not complete' : err instanceof Error ? err.message : String(err) },
                 metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts },
                 requested,
                 observed: {
                     matched_count: lastMatchedCount,
-                    condition_satisfied: false,
+                    condition_satisfied: readinessTracker ? lastConditionSatisfied : false,
                     selected_index: lastMatchedElement?.index ?? null,
                     last_matched_element: lastMatchedElement
                 }
@@ -2393,6 +2420,7 @@ export class ToolsInteract {
         };
     }
     static async waitForUIChangeHandler({ platform, deviceId, timeout_ms = 60000, stability_window_ms = 300, expected_change, scope = 'screen', target = null }) {
+        const readinessTracker = currentReadinessWait();
         const start = Date.now();
         const pollIntervalMs = 300;
         const stabilityWindow = Math.max(0, typeof stability_window_ms === 'number' ? stability_window_ms : 300);
@@ -2415,7 +2443,11 @@ export class ToolsInteract {
         };
         while (Date.now() - start < timeout_ms) {
             try {
+                if (readinessTracker)
+                    remainingBudget();
+                const acquisitionStarted = Date.now();
                 const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
+                observeReadinessWait(tree, acquisitionStarted);
                 const scopedTree = ToolsInteract._resolveUiChangeScope(tree, scope, target);
                 if (scopedTree.error) {
                     lastScopeResolution = scopedTree.resolution;
@@ -2461,7 +2493,7 @@ export class ToolsInteract {
                             candidateSinceMs = Date.now();
                         }
                         const stableForMs = candidateSinceMs === null ? 0 : Date.now() - candidateSinceMs;
-                        if (stabilityWindow === 0 || stableForMs >= stabilityWindow) {
+                        if ((stabilityWindow === 0 || stableForMs >= stabilityWindow) && (!readinessTracker || readinessTracker.summary.state === 'settled')) {
                             return {
                                 success: true,
                                 observed_change: candidateObservedChange ?? observedChange,
@@ -2486,10 +2518,18 @@ export class ToolsInteract {
                     }
                 }
             }
-            catch {
-                // Keep polling until timeout; the observable surface should be best-effort.
+            catch (error) {
+                if (readinessTracker && !String(error).includes('READINESS_'))
+                    readinessTracker.unavailable();
+                if (readinessTracker && isDeviceUnavailable(error))
+                    throw error;
+                if (readinessTracker && String(error).includes('ACTION_TIMEOUT')) {
+                    readinessTracker.deadline();
+                    break;
+                }
+                // Default waits retain best-effort polling.
             }
-            await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+            await (readinessTracker ? readinessDelay(pollIntervalMs) : new Promise(resolve => setTimeout(resolve, pollIntervalMs)));
         }
         return {
             success: false,

package/dist/interact/ios.js

@@ -1,3 +1,5 @@
+import { evidenceDispatch } from '../observe/evidence.js';
+import { beforeInputDispatch } from './conditional-action.js';
 import { remainingBudget, markDispatchStarted } from '../utils/operation-budget.js';
 import { spawn } from "child_process";
 import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "../utils/ios/utils.js";
@@ -24,9 +26,11 @@ export class iOSInteract {
             if (targetUdid) {
                 args.push('--udid', targetUdid);
             }
-            await new Promise((resolve, reject) => {
-                markDispatchStarted();
-                const proc = spawn(getIdbCmd(), args, { timeout: remainingBudget() || undefined });
+            await beforeInputDispatch('ios', device.id);
+            const timeout = remainingBudget() || undefined;
+            markDispatchStarted();
+            await evidenceDispatch({ platform: 'ios', id: device.id }, () => new Promise((resolve, reject) => {
+                const proc = spawn(getIdbCmd(), args, { timeout });
                 let stderr = '';
                 proc.stderr.on('data', d => stderr += d.toString());
                 proc.on('close', code => {
@@ -36,7 +40,7 @@ export class iOSInteract {
                         reject(new Error(`idb ui tap failed: ${stderr}`));
                 });
                 proc.on('error', err => reject(err));
-            });
+            }));
             return { device, success: true, x, y };
         }
         catch (e) {
@@ -64,9 +68,11 @@ export class iOSInteract {
             if (targetUdid) {
                 args.push('--udid', targetUdid);
             }
-            await new Promise((resolve, reject) => {
-                markDispatchStarted();
-                const proc = spawn(getIdbCmd(), args, { timeout: remainingBudget() || undefined });
+            await beforeInputDispatch('ios', device.id);
+            const timeout = remainingBudget() || undefined;
+            markDispatchStarted();
+            await evidenceDispatch({ platform: 'ios', id: device.id }, () => new Promise((resolve, reject) => {
+                const proc = spawn(getIdbCmd(), args, { timeout });
                 let stderr = '';
                 proc.stderr.on('data', d => stderr += d.toString());
                 proc.on('close', code => {
@@ -76,7 +82,7 @@ export class iOSInteract {
                         reject(new Error(`idb ui swipe failed: ${stderr}`));
                 });
                 proc.on('error', err => reject(err));
-            });
+            }));
             return { device, success: true, start: [x1, y1], end: [x2, y2], duration };
         }
         catch (e) {

package/dist/manage/android.js

@@ -1,3 +1,4 @@
+import { evidenceDispatch } from '../observe/evidence.js';
 import { hasFiniteBudget, markDispatchStarted, remainingBudget, runWithBudget } from '../utils/operation-budget.js';
 import { promises as fs } from 'fs';
 import { spawn } from 'child_process';
@@ -152,7 +153,7 @@ export class AndroidManage {
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
             markDispatchStarted();
-            const output = await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId, { timeout: timeoutMs });
+            const output = await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId, { timeout: timeoutMs }));
             const current = await new AndroidObserve().getCurrentScreen(deviceId).catch(() => null);
             return {
                 device: deviceInfo,
@@ -178,7 +179,7 @@ export class AndroidManage {
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
             markDispatchStarted();
-            await execAdb(['shell', 'am', 'force-stop', appId], deviceId);
+            await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'am', 'force-stop', appId], deviceId));
             return { device: deviceInfo, appTerminated: true };
         }
         catch (e) {
@@ -211,7 +212,7 @@ export class AndroidManage {
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
             markDispatchStarted();
-            const output = await execAdb(['shell', 'pm', 'clear', appId], deviceId);
+            const output = await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'pm', 'clear', appId], deviceId));
             return { device: deviceInfo, dataCleared: output === 'Success' };
         }
         catch (e) {

package/dist/manage/ios.js

@@ -1,3 +1,4 @@
+import { evidenceDispatch } from '../observe/evidence.js';
 import { hasFiniteBudget, markDispatchStarted, remainingBudget, runWithBudget } from '../utils/operation-budget.js';
 import { promises as fs } from "fs";
 import { spawn, spawnSync } from "child_process";
@@ -293,7 +294,7 @@ export class iOSManage {
         validateBundleId(bundleId);
         try {
             markDispatchStarted();
-            const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId);
+            const result = await evidenceDispatch({ platform: 'ios', id: deviceId }, () => execCommand(['simctl', 'launch', deviceId, bundleId], deviceId));
             const device = await getIOSDeviceMetadata(deviceId);
             const fingerprint = observe ? await new iOSObserve().getScreenFingerprint(deviceId).catch(() => null) : null;
             const pidMatch = result.output.match(/:\s*(\d+)\s*$/);
@@ -320,7 +321,7 @@ export class iOSManage {
         validateBundleId(bundleId);
         try {
             markDispatchStarted();
-            await execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId);
+            await evidenceDispatch({ platform: 'ios', id: deviceId }, () => execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId));
             const device = await getIOSDeviceMetadata(deviceId);
             return { device, appTerminated: true };
         }

package/dist/observe/android.js

@@ -1,3 +1,4 @@
+import { captureEvidence } from './evidence.js';
 import { spawn } from "child_process";
 import { XMLParser } from "fast-xml-parser";
 import { getAdbCmd, execAdb, getAndroidDeviceMetadata, getDeviceInfo, delay, getScreenResolution, traverseNode, parseLogLine } from "../utils/android/utils.js";
@@ -11,10 +12,14 @@ import { remainingBudget } from '../utils/operation-budget.js';
 import { createObservationMeasurement } from './performance-metrics.js';
 const activeLogStreams = new Map();
 export class AndroidObserve {
+    getLogStreamDevice(sessionId = 'default') { return activeLogStreams.get(sessionId)?.device ?? null; }
     async getDeviceMetadata(appId, deviceId) {
         return getAndroidDeviceMetadata(appId, deviceId);
     }
     async getUITree(deviceId) {
+        return captureEvidence('ui_tree', { platform: 'android', id: deviceId ?? '' }, () => this.collectGetUITree(deviceId));
+    }
+    async collectGetUITree(deviceId) {
         const measurement = createObservationMeasurement('android');
         let metadata;
         try {
@@ -113,6 +118,9 @@ export class AndroidObserve {
         }
     }
     async getLogs(filters = {}) {
+        return captureEvidence('logs', { platform: 'android', id: filters.deviceId ?? '' }, () => this.collectGetLogs(filters));
+    }
+    async collectGetLogs(filters = {}) {
         const { appId, deviceId, pid, tag, level, contains, since_seconds, limit } = filters;
         const metadata = await getAndroidDeviceMetadata(appId || "", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
@@ -213,6 +221,9 @@ export class AndroidObserve {
         }
     }
     async captureScreen(deviceId) {
+        return captureEvidence('screenshot', { platform: 'android', id: deviceId ?? '' }, () => this.collectCaptureScreen(deviceId));
+    }
+    async collectCaptureScreen(deviceId) {
         const metadata = await getAndroidDeviceMetadata("", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         return new Promise((resolve, reject) => {
@@ -331,6 +342,9 @@ export class AndroidObserve {
         });
     }
     async getCurrentScreen(deviceId) {
+        return captureEvidence('activity', { platform: 'android', id: deviceId ?? '' }, () => this.collectGetCurrentScreen(deviceId));
+    }
+    async collectGetCurrentScreen(deviceId) {
         const metadata = await getAndroidDeviceMetadata("", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
@@ -385,12 +399,15 @@ export class AndroidObserve {
         }
     }
     async getScreenFingerprint(deviceId) {
+        return captureEvidence('fingerprint', { platform: 'android', id: deviceId ?? '' }, () => this.collectGetScreenFingerprint(deviceId));
+    }
+    async collectGetScreenFingerprint(deviceId) {
         try {
             const tree = await this.getUITree(deviceId);
             if (!tree || tree.error)
                 return { fingerprint: null, error: tree.error };
             const current = await this.getCurrentScreen(deviceId).catch(() => null);
-            return computeScreenFingerprint(tree, current, 'android', 50);
+            return { ...computeScreenFingerprint(tree, current, 'android', 50), captured_at_ms: tree.captured_at_ms };
         }
         catch (e) {
             return { fingerprint: null, error: e instanceof Error ? e.message : String(e) };
@@ -411,7 +428,7 @@ export class AndroidObserve {
                 catch { }
                 activeLogStreams.delete(sessionId);
             }
-            const args = ['logcat', `--pid=${pid}`, filter];
+            const args = [...(deviceId ? ['-s', deviceId] : []), 'logcat', `--pid=${pid}`, filter];
             const proc = spawn(getAdbCmd(), args);
             const tmpDir = process.env.TMPDIR || '/tmp';
             const file = path.join(tmpDir, `mobile-debug-log-${sessionId}.ndjson`);
@@ -434,9 +451,10 @@ export class AndroidObserve {
             });
             proc.on('close', () => {
                 stream.end();
-                activeLogStreams.delete(sessionId);
+                if (activeLogStreams.get(sessionId)?.proc === proc)
+                    activeLogStreams.delete(sessionId);
             });
-            activeLogStreams.set(sessionId, { proc, file });
+            activeLogStreams.set(sessionId, { proc, file, device: { platform: 'android', id: deviceId ?? '' } });
             return { success: true, stream_started: true };
         }
         catch (e) {
@@ -455,6 +473,9 @@ export class AndroidObserve {
         return { success: true };
     }
     async readLogStream(sessionId = 'default', limit = 100, since) {
+        return captureEvidence('logs', this.getLogStreamDevice(sessionId), () => this.collectReadLogStream(sessionId, limit, since));
+    }
+    async collectReadLogStream(sessionId = 'default', limit = 100, since) {
         const entry = activeLogStreams.get(sessionId);
         let file;
         if (entry && entry.file)

package/dist/observe/evidence.js

@@ -0,0 +1,273 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+const sessionId = randomUUID();
+const context = new AsyncLocalStorage();
+const history = new Map();
+const active = new Map();
+const orders = new Map();
+const stamp = () => ({ wall: Date.now(), mono: performance.now() });
+const deviceKey = (d) => `${d.platform}:${d.id}`;
+const sameDevice = (a, b) => !!a && !!b && deviceKey(a) === deviceKey(b);
+function validDevice(d) {
+    return d && ['android', 'ios'].includes(d.platform) && typeof d.id === 'string' && d.id && !['default', 'booted'].includes(d.id)
+        ? { platform: d.platform, id: d.id } : null;
+}
+function orderFor(device) {
+    if (!device)
+        return null;
+    const key = deviceKey(device);
+    let order = orders.get(key);
+    if (!order) {
+        order = { sequence: 0, active: 0, lastStarted: -Infinity };
+        orders.set(key, order);
+        if (orders.size > 1000) {
+            for (const [oldKey, oldOrder] of orders) {
+                if (oldKey !== key && oldOrder.active === 0)
+                    orders.delete(oldKey);
+                if (orders.size <= 1000)
+                    break;
+            }
+        }
+    }
+    return order;
+}
+function prune() {
+    const now = performance.now();
+    for (const [key, record] of history) {
+        if (record.completed !== null && now - record.completed >= 600000)
+            history.delete(key);
+    }
+    while (history.size > 1000)
+        history.delete(history.keys().next().value);
+}
+export function validateActionRef(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value) ||
+        Object.keys(value).some(key => !['sessionId', 'actionId'].includes(key)))
+        throw new Error('INVALID_ARGUMENT: invalid actionRef');
+    const ref = value;
+    for (const v of [ref.sessionId, ref.actionId])
+        if (typeof v !== 'string' || v.length < 1 || v.length > 128)
+            throw new Error('INVALID_ARGUMENT: invalid actionRef');
+    return { sessionId: ref.sessionId, actionId: ref.actionId };
+}
+export function currentEvidenceActionId() { return context.getStore()?.action?.id; }
+export function bindEvidenceDevice(device) {
+    const current = context.getStore();
+    const target = validDevice(device);
+    if (!current || !target)
+        return;
+    current.device ??= target;
+    if (current.isAction && current.action)
+        current.action.device ??= target;
+}
+export function markEvidenceVerification() {
+    const current = context.getStore();
+    if (current) {
+        current.verification = stamp();
+        if (current.isAction && current.action)
+            current.action.verification = current.verification;
+    }
+}
+export async function evidenceDispatch(device, operation) {
+    const current = context.getStore();
+    if (!current?.isAction || !current.action)
+        return operation();
+    bindEvidenceDevice(device);
+    const record = current.action;
+    const start = stamp();
+    record.dispatchStart ??= start;
+    record.dispatchEnd = null;
+    const order = orderFor(validDevice(device));
+    if (order) {
+        order.sequence++;
+        order.active++;
+        order.lastStarted = start.mono;
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        record.dispatchEnd = stamp();
+        if (order)
+            order.active--;
+    }
+}
+export function omitEvidence(kind) {
+    const current = context.getStore();
+    if (!current)
+        return;
+    const start = stamp();
+    current.observations.push({ value: {
+            evidence_id: randomUUID(), kind, status: 'omitted', capture_started_at_ms: null,
+            capture_completed_at_ms: null, source_captured_at_ms: null, age_ms: null,
+            freshness: kind === 'logs' ? 'not_applicable' : 'unknown', freshness_reasons: [], device: current.device
+        }, start, end: null, order: null, startSequence: 0, endSequence: 0, overlapping: false, reused: false });
+}
+export async function captureEvidence(kind, device, operation) {
+    const current = context.getStore();
+    if (!current)
+        return operation();
+    const target = validDevice(device);
+    if (target)
+        bindEvidenceDevice(target);
+    const order = orderFor(target);
+    const start = stamp();
+    const acquisition = { value: {
+            evidence_id: randomUUID(), kind, status: 'failed', capture_started_at_ms: start.wall,
+            capture_completed_at_ms: null, source_captured_at_ms: null, age_ms: null,
+            freshness: 'unknown', freshness_reasons: [], device: target
+        }, start, end: null, order, startSequence: order?.sequence ?? 0,
+        endSequence: 0, overlapping: !!order?.active, reused: false };
+    current.observations.push(acquisition);
+    try {
+        const result = await operation();
+        const value = acquisition.value;
+        const resolved = validDevice(result?.device) ?? target;
+        value.device = resolved;
+        if (resolved)
+            bindEvidenceDevice(resolved);
+        const failure = result?.error ?? result?.meta?.error;
+        value.status = failure || result?.success === false || (kind === 'fingerprint' && !result?.fingerprint) ? 'failed' : 'captured';
+        if (failure)
+            value.error = failure;
+        const source = result?.captured_at_ms;
+        if (Number.isFinite(source) && source > 0) {
+            value.source_captured_at_ms = source;
+            acquisition.reused = source < start.wall;
+        }
+        if (kind === 'ui_tree') {
+            value.snapshot_session_id = result?.snapshot_session_id;
+            value.snapshot_revision = result?.snapshot_revision;
+        }
+        if (kind === 'logs') {
+            const entries = result?.logs ?? result?.entries ?? [];
+            const times = entries.map((e) => {
+                const t = e?.timestamp ?? e?._iso;
+                return typeof t === 'number' ? t : typeof t === 'string' ? Date.parse(t) : NaN;
+            }).filter((t) => Number.isFinite(t));
+            value.clock = 'device_or_unknown';
+            value.event_time_comparable = false;
+            value.earliest_entry_at_ms = times.length ? times.reduce((a, b) => Math.min(a, b)) : null;
+            value.latest_entry_at_ms = times.length ? times.reduce((a, b) => Math.max(a, b)) : null;
+        }
+        return result;
+    }
+    catch (error) {
+        acquisition.value.error = error instanceof Error ? error.message : String(error);
+        throw error;
+    }
+    finally {
+        acquisition.end = stamp();
+        acquisition.value.capture_completed_at_ms = acquisition.end.wall;
+        acquisition.endSequence = order?.sequence ?? 0;
+        acquisition.overlapping ||= !!order?.active || acquisition.startSequence !== acquisition.endSequence;
+        if (acquisition.value.status === 'captured' && acquisition.value.source_captured_at_ms === null && kind !== 'logs') {
+            acquisition.value.source_captured_at_ms = acquisition.end.wall;
+        }
+    }
+}
+function association(current) {
+    if (current.isAction)
+        return { association: 'self', association_reason: null };
+    if (!current.ref)
+        return { association: 'none', association_reason: null };
+    const reason = current.ref.sessionId !== sessionId ? 'SESSION_MISMATCH' : !current.action ? 'ACTION_UNAVAILABLE' :
+        !sameDevice(current.device, current.action.device) ? 'DEVICE_MISMATCH' : null;
+    return { association: reason ? 'unavailable' : 'explicit', association_reason: reason };
+}
+function assemble(current) {
+    const end = stamp();
+    const link = association(current);
+    const action = link.association === 'unavailable' ? null : current.action;
+    const clockChanged = end.wall < current.start.wall;
+    const observations = current.observations.map(a => {
+        const v = { ...a.value, freshness_reasons: [] };
+        if (v.status === 'omitted')
+            return v;
+        const componentAction = sameDevice(v.device, action?.device ?? null) ? action : null;
+        const sourceMono = a.end && v.source_captured_at_ms !== null ? a.end.mono + v.source_captured_at_ms - a.end.wall : a.end?.mono;
+        const reason = (freshness, code) => { v.freshness = freshness; v.freshness_reasons.push(code); };
+        if (v.kind === 'logs')
+            reason('unknown', 'DEVICE_CLOCK_UNVERIFIED');
+        else if (clockChanged || (a.end && a.end.wall < a.start.wall))
+            reason('unknown', 'CLOCK_DISCONTINUITY');
+        else if (v.source_captured_at_ms !== null && a.end && v.source_captured_at_ms > a.end.wall)
+            reason('unknown', 'CLOCK_DISCONTINUITY');
+        else if (!v.device || !a.order || orders.get(deviceKey(v.device)) !== a.order || v.status !== 'captured' || !a.end)
+            reason('unknown', 'CAPTURE_TIME_UNKNOWN');
+        else if (componentAction?.dispatchStart && sourceMono !== undefined && sourceMono < componentAction.dispatchStart.mono)
+            reason('stale', 'BEFORE_ACTION');
+        else if (a.order && (a.order.sequence > a.endSequence || (a.reused && sourceMono !== undefined && sourceMono < a.order.lastStarted)))
+            reason('stale', 'SUPERSEDED_BY_ACTION');
+        else if (a.overlapping)
+            reason('unknown', 'OVERLAPPING_ACTION');
+        else if (a.reused)
+            reason('unknown', 'REUSED_OBSERVATION');
+        else {
+            v.freshness = 'fresh';
+        }
+        if (!clockChanged && a.end && a.end.wall >= a.start.wall && v.source_captured_at_ms !== null && v.source_captured_at_ms <= end.wall) {
+            v.age_ms = Math.max(0, end.mono - a.end.mono + a.end.wall - v.source_captured_at_ms);
+        }
+        return { ...v, session_id: sessionId, correlation_id: componentAction?.correlationId ?? current.correlationId,
+            action_id: componentAction?.id ?? null, association: componentAction ? 'internal' : link.association };
+    });
+    return {
+        session_id: sessionId, correlation_id: action?.correlationId ?? current.correlationId,
+        action_id: action?.id ?? null, device: current.device, ...link,
+        ...(current.ref ? { requested_action_ref: current.ref } : {}),
+        operation_started_at_ms: current.start.wall, operation_completed_at_ms: current.end?.wall ?? end.wall,
+        dispatch_started_at_ms: action?.dispatchStart?.wall ?? null,
+        dispatch_completed_at_ms: action?.dispatchEnd?.wall ?? null,
+        verification_completed_at_ms: current.verification?.wall ?? action?.verification?.wall ?? null,
+        observations, trace_context: { supported: false, trace_id: null, markers: [] }
+    };
+}
+export async function withEvidence(options, operation) {
+    prune();
+    const parent = context.getStore();
+    const id = randomUUID();
+    const record = options.action ? { id, correlationId: parent?.correlationId ?? id, device: null,
+        dispatchStart: null, dispatchEnd: null, verification: null, completed: null } : options.ref?.sessionId === sessionId ? active.get(options.ref.actionId) ?? history.get(options.ref.actionId) ?? null : null;
+    const current = { correlationId: options.action ? record.correlationId : options.journey ? id : randomUUID(),
+        action: record, ref: options.ref, device: null, start: stamp(), end: null, verification: null, observations: [], children: [], isAction: !!options.action };
+    if (options.action && record)
+        active.set(id, record);
+    if (parent && options.action)
+        parent.children.push(current);
+    try {
+        return await context.run(current, async () => {
+            const result = await operation();
+            current.end = stamp();
+            return { result, evidence: assemble(current) };
+        });
+    }
+    finally {
+        if (options.action && record) {
+            active.delete(id);
+            record.completed = performance.now();
+            history.set(id, record);
+            prune();
+        }
+    }
+}
+export function refreshJourneyEvidence(steps) {
+    const current = context.getStore();
+    if (!current)
+        return;
+    for (const step of steps) {
+        const previous = step.result?.evidence;
+        const child = current.children.find(c => c.action?.id === previous?.action_id);
+        if (child && step.result)
+            step.result.evidence = assemble(child);
+    }
+}
+export function completeJourneyVerification(actionId) {
+    const child = context.getStore()?.children.find(c => c.action?.id === actionId);
+    if (child?.action) {
+        child.verification = stamp();
+        child.action.verification = child.verification;
+    }
+}