publishport-opencli 1.8.4-pp.1

package/dist/src/manifest-types.js

@@ -0,0 +1,9 @@
+/**
+ * Shared manifest types — kept in their own module so both runtime code
+ * (discovery.ts) and the build-time compiler (build-manifest.ts) can
+ * import them without pulling each other in. This is what lets us
+ * exclude `src/build-manifest.ts` from `tsc`'s emit set: the only thing
+ * runtime code needs from build-manifest is the `ManifestEntry` type,
+ * and that lives here.
+ */
+export {};

package/dist/src/node-network.d.ts

@@ -0,0 +1,10 @@
+import { type Dispatcher } from 'undici';
+export interface ProxyDecision {
+    mode: 'direct' | 'proxy';
+    proxyUrl?: string;
+}
+export declare function hasProxyEnv(env?: NodeJS.ProcessEnv): boolean;
+export declare function decideProxy(url: URL, env?: NodeJS.ProcessEnv): ProxyDecision;
+export declare function getDispatcherForUrl(url: URL, env?: NodeJS.ProcessEnv): Dispatcher;
+export declare function fetchWithNodeNetwork(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+export declare function installNodeNetwork(): void;

package/dist/src/node-network.js

@@ -0,0 +1,174 @@
+import { Agent, EnvHttpProxyAgent, fetch as undiciFetch } from 'undici';
+const LOOPBACK_NO_PROXY_ENTRIES = ['127.0.0.1', 'localhost', '::1'];
+const PROXY_ENV_BY_PROTOCOL = {
+    'http:': ['http_proxy', 'HTTP_PROXY', 'all_proxy', 'ALL_PROXY'],
+    'https:': ['https_proxy', 'HTTPS_PROXY', 'all_proxy', 'ALL_PROXY'],
+};
+const DEFAULT_PORT_BY_PROTOCOL = {
+    'http:': '80',
+    'https:': '443',
+};
+let installed = false;
+const directDispatcher = new Agent();
+const proxyDispatcherCache = new Map();
+const nativeFetch = globalThis.fetch.bind(globalThis);
+function readEnv(env, lower, upper) {
+    const lowerValue = env[lower];
+    if (typeof lowerValue === 'string' && lowerValue.trim() !== '')
+        return lowerValue;
+    const upperValue = env[upper];
+    if (typeof upperValue === 'string' && upperValue.trim() !== '')
+        return upperValue;
+    return undefined;
+}
+function readProxyEnv(env, keys) {
+    for (const key of keys) {
+        const value = env[key];
+        if (typeof value === 'string' && value.trim() !== '')
+            return value;
+    }
+    return undefined;
+}
+function normalizeHostname(hostname) {
+    return hostname.replace(/^\[(.*)\]$/, '$1').toLowerCase();
+}
+function splitNoProxy(raw) {
+    return (raw ?? '')
+        .split(/[,\s]+/)
+        .map((token) => token.trim())
+        .filter(Boolean);
+}
+function parseNoProxyEntry(entry) {
+    if (entry === '*')
+        return { host: '*' };
+    const trimmed = entry.trim().replace(/^\*?\./, '');
+    if (trimmed.startsWith('[')) {
+        const end = trimmed.indexOf(']');
+        if (end !== -1) {
+            const host = trimmed.slice(1, end);
+            const rest = trimmed.slice(end + 1);
+            if (rest.startsWith(':'))
+                return { host: normalizeHostname(host), port: rest.slice(1) };
+            return { host: normalizeHostname(host) };
+        }
+    }
+    const colonCount = (trimmed.match(/:/g) ?? []).length;
+    if (colonCount === 1) {
+        const [host, port] = trimmed.split(':');
+        return { host: normalizeHostname(host), port };
+    }
+    return { host: normalizeHostname(trimmed) };
+}
+function effectiveNoProxyEntries(env) {
+    const raw = readEnv(env, 'no_proxy', 'NO_PROXY');
+    const entries = splitNoProxy(raw).map(parseNoProxyEntry);
+    const seen = new Set(entries.map((entry) => `${entry.host}:${entry.port ?? ''}`));
+    for (const rawEntry of LOOPBACK_NO_PROXY_ENTRIES) {
+        const entry = parseNoProxyEntry(rawEntry);
+        const key = `${entry.host}:${entry.port ?? ''}`;
+        if (seen.has(key))
+            continue;
+        entries.push(entry);
+        seen.add(key);
+    }
+    return entries;
+}
+function serializeNoProxyEntry(entry) {
+    if (entry.host === '*')
+        return '*';
+    const host = entry.host.includes(':') ? `[${entry.host}]` : entry.host;
+    return entry.port ? `${host}:${entry.port}` : host;
+}
+function effectiveNoProxyValue(entries) {
+    if (entries.length === 0)
+        return undefined;
+    return entries.map(serializeNoProxyEntry).join(',');
+}
+function matchesNoProxyEntry(url, entry) {
+    const { host, port } = entry;
+    if (host === '*')
+        return true;
+    const hostname = normalizeHostname(url.hostname);
+    const urlPort = url.port || DEFAULT_PORT_BY_PROTOCOL[url.protocol] || undefined;
+    if (port && port !== urlPort)
+        return false;
+    return hostname === host || hostname.endsWith(`.${host}`);
+}
+function resolveProxyConfig(env = process.env) {
+    const noProxyEntries = effectiveNoProxyEntries(env);
+    return {
+        httpProxy: readProxyEnv(env, PROXY_ENV_BY_PROTOCOL['http:']),
+        httpsProxy: readProxyEnv(env, [
+            'https_proxy',
+            'HTTPS_PROXY',
+            'http_proxy',
+            'HTTP_PROXY',
+            'all_proxy',
+            'ALL_PROXY',
+        ]),
+        noProxy: effectiveNoProxyValue(noProxyEntries),
+        noProxyEntries,
+    };
+}
+function createProxyDispatcher(config) {
+    const cacheKey = JSON.stringify([
+        config.httpProxy ?? '',
+        config.httpsProxy ?? '',
+        config.noProxy ?? '',
+    ]);
+    const cached = proxyDispatcherCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const dispatcher = new EnvHttpProxyAgent({
+        httpProxy: config.httpProxy,
+        httpsProxy: config.httpsProxy,
+        noProxy: config.noProxy,
+    });
+    proxyDispatcherCache.set(cacheKey, dispatcher);
+    return dispatcher;
+}
+function resolveUrl(input) {
+    if (typeof input === 'string')
+        return new URL(input);
+    if (input instanceof URL)
+        return input;
+    if (typeof Request !== 'undefined' && input instanceof Request)
+        return new URL(input.url);
+    return null;
+}
+export function hasProxyEnv(env = process.env) {
+    const config = resolveProxyConfig(env);
+    return Boolean(config.httpProxy || config.httpsProxy);
+}
+export function decideProxy(url, env = process.env) {
+    const config = resolveProxyConfig(env);
+    if (config.noProxyEntries.some((entry) => matchesNoProxyEntry(url, entry))) {
+        return { mode: 'direct' };
+    }
+    const proxyUrl = url.protocol === 'https:' ? config.httpsProxy : config.httpProxy;
+    if (!proxyUrl)
+        return { mode: 'direct' };
+    return { mode: 'proxy', proxyUrl };
+}
+export function getDispatcherForUrl(url, env = process.env) {
+    const config = resolveProxyConfig(env);
+    if (!config.httpProxy && !config.httpsProxy)
+        return directDispatcher;
+    return createProxyDispatcher(config);
+}
+export async function fetchWithNodeNetwork(input, init = {}) {
+    const url = resolveUrl(input);
+    if (!url || !hasProxyEnv()) {
+        return nativeFetch(input, init);
+    }
+    return (await undiciFetch(input, {
+        ...init,
+        dispatcher: getDispatcherForUrl(url),
+    }));
+}
+export function installNodeNetwork() {
+    if (installed)
+        return;
+    globalThis.fetch = ((input, init) => (fetchWithNodeNetwork(input, init)));
+    installed = true;
+}

package/dist/src/node-network.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/node-network.test.js

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { decideProxy, hasProxyEnv } from './node-network.js';
+describe('node network proxy decisions', () => {
+    it('detects common proxy env variables', () => {
+        expect(hasProxyEnv({ https_proxy: 'http://127.0.0.1:7897' })).toBe(true);
+        expect(hasProxyEnv({ HTTP_PROXY: 'http://proxy.example:8080' })).toBe(true);
+        expect(hasProxyEnv({})).toBe(false);
+    });
+    it('routes external https traffic through https_proxy', () => {
+        const decision = decideProxy(new URL('https://www.v2ex.com/api/topics/latest.json'), { https_proxy: 'http://127.0.0.1:7897' });
+        expect(decision).toEqual({
+            mode: 'proxy',
+            proxyUrl: 'http://127.0.0.1:7897',
+        });
+    });
+    it('falls back to HTTP_PROXY for https traffic when HTTPS_PROXY is absent', () => {
+        const decision = decideProxy(new URL('https://www.v2ex.com/api/topics/latest.json'), { HTTP_PROXY: 'http://127.0.0.1:7897' });
+        expect(decision).toEqual({
+            mode: 'proxy',
+            proxyUrl: 'http://127.0.0.1:7897',
+        });
+    });
+    it('bypasses proxies for loopback addresses', () => {
+        const env = { https_proxy: 'http://127.0.0.1:7897', http_proxy: 'http://127.0.0.1:7897' };
+        expect(decideProxy(new URL('http://127.0.0.1:19825/status'), env)).toEqual({ mode: 'direct' });
+        expect(decideProxy(new URL('http://localhost:19825/status'), env)).toEqual({ mode: 'direct' });
+        expect(decideProxy(new URL('http://[::1]:19825/status'), env)).toEqual({ mode: 'direct' });
+    });
+    it('honors NO_PROXY domain matches', () => {
+        const decision = decideProxy(new URL('https://api.example.com/v1/items'), {
+            https_proxy: 'http://127.0.0.1:7897',
+            no_proxy: '.example.com',
+        });
+        expect(decision).toEqual({ mode: 'direct' });
+    });
+    it('supports wildcard-style NO_PROXY subdomain entries', () => {
+        const decision = decideProxy(new URL('https://api.example.com/v1/items'), {
+            https_proxy: 'http://127.0.0.1:7897',
+            no_proxy: '*.example.com',
+        });
+        expect(decision).toEqual({ mode: 'direct' });
+    });
+    it('matches NO_PROXY entries that rely on the default URL port', () => {
+        const env = { https_proxy: 'http://127.0.0.1:7897', http_proxy: 'http://127.0.0.1:7897' };
+        expect(decideProxy(new URL('https://example.com/'), { ...env, NO_PROXY: 'example.com:443' })).toEqual({ mode: 'direct' });
+        expect(decideProxy(new URL('http://example.com/health'), { ...env, NO_PROXY: 'example.com:80' })).toEqual({ mode: 'direct' });
+    });
+    it('falls back to ALL_PROXY when protocol-specific settings are absent', () => {
+        const decision = decideProxy(new URL('http://example.net/data'), { ALL_PROXY: 'socks5://127.0.0.1:1080' });
+        expect(decision).toEqual({
+            mode: 'proxy',
+            proxyUrl: 'socks5://127.0.0.1:1080',
+        });
+    });
+});

package/dist/src/observation/artifact.d.ts

@@ -0,0 +1,16 @@
+import type { ObservationExportResult, ObservationExportStatus, ObservationTraceReceipt } from './events.js';
+import { ObservationSession } from './session.js';
+import { type TraceRetentionPolicyInput } from './retention.js';
+export interface ExportObservationOptions {
+    baseDir?: string;
+    error?: unknown;
+    status?: ObservationExportStatus;
+    retentionPolicy?: TraceRetentionPolicyInput;
+}
+export declare function getTraceDirectory(contextId: string | undefined, traceId: string, baseDir?: string): string;
+export declare function exportObservationSession(session: ObservationSession, opts?: ExportObservationOptions): ObservationExportResult;
+export declare function buildTraceReceipt(result: Pick<ObservationExportResult, 'traceId' | 'dir' | 'summaryPath' | 'receiptPath'>, status: ObservationExportStatus, error?: unknown, opts?: {
+    createdAt?: string;
+    scope?: ObservationSession['scope'];
+    retentionPolicy?: TraceRetentionPolicyInput;
+}): ObservationTraceReceipt;

package/dist/src/observation/artifact.js

@@ -0,0 +1,260 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { redactValue } from './redaction.js';
+import { pruneTraceArtifacts, traceExpiresAt } from './retention.js';
+import { CliError, getErrorMessage } from '../errors.js';
+import { log } from '../logger.js';
+import { PKG_VERSION } from '../version.js';
+function baseOpenCliDir() {
+    return process.env.OPENCLI_CONFIG_DIR || path.join(os.homedir(), '.opencli');
+}
+function safeSegment(value) {
+    const safe = (value || 'default').replace(/[^a-zA-Z0-9_-]+/g, '_');
+    return safe || 'default';
+}
+export function getTraceDirectory(contextId, traceId, baseDir = baseOpenCliDir()) {
+    return path.join(baseDir, 'profiles', safeSegment(contextId), 'traces', safeSegment(traceId));
+}
+export function exportObservationSession(session, opts = {}) {
+    const dir = getTraceDirectory(session.scope.contextId, session.id, opts.baseDir);
+    const status = opts.status ?? (opts.error === undefined ? 'success' : 'failure');
+    const createdAt = new Date().toISOString();
+    fs.mkdirSync(dir, { recursive: true });
+    fs.mkdirSync(path.join(dir, 'screenshots'), { recursive: true });
+    fs.mkdirSync(path.join(dir, 'state'), { recursive: true });
+    const originalEvents = session.events();
+    const sanitizedEvents = originalEvents.map((event) => redactObservationEvent(event));
+    const traceLines = [];
+    const networkLines = [];
+    const consoleLines = [];
+    let screenshotIndex = 0;
+    let stateIndex = 0;
+    for (let i = 0; i < sanitizedEvents.length; i++) {
+        const originalEvent = originalEvents[i];
+        const event = sanitizedEvents[i];
+        const serializable = { ...event };
+        if (event.stream === 'screenshot' && originalEvent.stream === 'screenshot' && typeof originalEvent.data === 'string') {
+            const ext = event.format === 'jpeg' ? 'jpg' : 'png';
+            const file = `screenshots/${String(++screenshotIndex).padStart(4, '0')}.${ext}`;
+            fs.writeFileSync(path.join(dir, file), originalEvent.data, 'base64');
+            serializable.path = file;
+            delete serializable.data;
+        }
+        if (event.stream === 'state' && serializable.snapshot !== undefined) {
+            const file = `state/${String(++stateIndex).padStart(4, '0')}.json`;
+            fs.writeFileSync(path.join(dir, file), JSON.stringify(serializable.snapshot, null, 2), 'utf-8');
+            serializable.snapshotPath = file;
+            delete serializable.snapshot;
+        }
+        const line = JSON.stringify(serializable);
+        traceLines.push(line);
+        if (event.stream === 'network')
+            networkLines.push(line);
+        if (event.stream === 'console')
+            consoleLines.push(line);
+    }
+    fs.writeFileSync(path.join(dir, 'trace.jsonl'), traceLines.join('\n') + (traceLines.length ? '\n' : ''), 'utf-8');
+    fs.writeFileSync(path.join(dir, 'network.jsonl'), networkLines.join('\n') + (networkLines.length ? '\n' : ''), 'utf-8');
+    fs.writeFileSync(path.join(dir, 'console.jsonl'), consoleLines.join('\n') + (consoleLines.length ? '\n' : ''), 'utf-8');
+    const summaryPath = path.join(dir, 'summary.md');
+    fs.writeFileSync(summaryPath, renderSummary(session, sanitizedEvents, {
+        error: opts.error,
+        status,
+        dir,
+        createdAt,
+        retentionPolicy: opts.retentionPolicy,
+    }), 'utf-8');
+    const receiptPath = path.join(dir, 'receipt.json');
+    const resultBase = { traceId: session.id, dir, summaryPath, receiptPath };
+    const receipt = buildTraceReceipt(resultBase, status, opts.error, {
+        createdAt,
+        scope: session.scope,
+        retentionPolicy: opts.retentionPolicy,
+    });
+    fs.writeFileSync(receiptPath, JSON.stringify(receipt, null, 2), 'utf-8');
+    pruneTraceArtifactsBestEffort(path.dirname(dir), dir, opts.retentionPolicy);
+    return { ...resultBase, receipt };
+}
+function redactObservationEvent(event) {
+    return redactValue(event);
+}
+export function buildTraceReceipt(result, status, error, opts = {}) {
+    const maybeCliError = error instanceof CliError ? error : undefined;
+    const createdAt = opts.createdAt ?? new Date().toISOString();
+    return {
+        schemaVersion: 1,
+        opencliVersion: PKG_VERSION,
+        traceId: result.traceId,
+        traceDir: result.dir,
+        summaryPath: result.summaryPath,
+        receiptPath: result.receiptPath,
+        status,
+        createdAt,
+        expiresAt: traceExpiresAt(createdAt, opts.retentionPolicy),
+        ...(opts.scope ? { scope: opts.scope } : {}),
+        ...(error === undefined ? {} : {
+            error: {
+                ...(error instanceof Error ? { name: error.name } : {}),
+                ...(maybeCliError ? { code: maybeCliError.code, hint: maybeCliError.hint, exitCode: maybeCliError.exitCode } : {}),
+                message: String(redactValue(getErrorMessage(error))),
+            },
+        }),
+    };
+}
+function pruneTraceArtifactsBestEffort(tracesDir, protectedTraceDir, retentionPolicy) {
+    try {
+        pruneTraceArtifacts(tracesDir, {
+            policy: retentionPolicy,
+            protectedTraceDirs: [protectedTraceDir],
+            warn: (message) => log.warn(`[trace] ${message}`),
+        });
+    }
+    catch (err) {
+        log.warn(`[trace] Failed to prune trace artifacts: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function renderSummary(session, events, opts) {
+    const counts = events.reduce((acc, event) => {
+        acc[event.stream] = (acc[event.stream] ?? 0) + 1;
+        return acc;
+    }, {});
+    const error = serializeSummaryError(opts.error);
+    const errorEvents = events.filter((event) => event.stream === 'error').slice(-20).reverse();
+    const failedNetwork = events
+        .filter((event) => event.stream === 'network')
+        .filter((event) => event.status === undefined || event.status === 0 || event.status >= 400)
+        .slice(-20)
+        .reverse();
+    const suspiciousConsole = events
+        .filter((event) => event.stream === 'console')
+        .filter((event) => /^(error|warning|warn|assert)$/i.test(event.level))
+        .slice(-20)
+        .reverse();
+    const actions = events
+        .filter((event) => event.stream === 'action')
+        .slice(-30);
+    const lines = [
+        '---',
+        'schemaVersion: 1',
+        `opencliVersion: ${yamlScalar(PKG_VERSION)}`,
+        `traceId: ${yamlScalar(session.id)}`,
+        `status: ${opts.status}`,
+        `contextId: ${yamlScalar(session.scope.contextId ?? 'default')}`,
+        `session: ${yamlScalar(session.scope.session)}`,
+        ...(session.scope.target ? [`target: ${yamlScalar(session.scope.target)}`] : []),
+        ...(session.scope.site ? [`site: ${yamlScalar(session.scope.site)}`] : []),
+        ...(session.scope.command ? [`command: ${yamlScalar(session.scope.command)}`] : []),
+        ...(session.scope.adapterSourcePath ? [`adapterSourcePath: ${yamlScalar(session.scope.adapterSourcePath)}`] : []),
+        ...(session.scope.adapterSourcePath ? [`adapterSourcePathExists: ${fs.existsSync(session.scope.adapterSourcePath)}`] : []),
+        `traceDir: ${yamlScalar(opts.dir)}`,
+        `startedAt: ${yamlScalar(new Date(session.startedAt).toISOString())}`,
+        `exportedAt: ${yamlScalar(opts.createdAt)}`,
+        `expiresAt: ${yamlScalar(traceExpiresAt(opts.createdAt, opts.retentionPolicy))}`,
+        ...(error ? [
+            `errorCode: ${yamlScalar(error.code ?? 'UNKNOWN')}`,
+            `errorMessage: ${yamlScalar(error.message)}`,
+        ] : []),
+        '---',
+        '',
+        '# OpenCLI Trace Summary',
+        '',
+        '## How To Use',
+        '',
+        '- Start with this summary, then inspect `trace.jsonl` only when the evidence below is insufficient.',
+        '- For adapter repair policy and retry limits, use the `opencli-autofix` skill.',
+        '- `adapterSourcePathExists: false` means the path is a best-effort hint, not a confirmed editable file.',
+        '',
+        '## Error',
+        '',
+        ...renderErrorSection(error, errorEvents),
+        '',
+        '## Failed Network',
+        '',
+        ...renderNetworkSection(failedNetwork),
+        '',
+        '## Suspicious Console',
+        '',
+        ...renderConsoleSection(suspiciousConsole),
+        '',
+        '## Action Timeline',
+        '',
+        ...renderActionSection(actions),
+        '',
+        '## Event Counts',
+        '',
+        ...Object.entries(counts).map(([stream, count]) => `- ${stream}: ${count}`),
+        '',
+        '## Artifact Files',
+        '',
+        '- `trace.jsonl`: full redacted event timeline',
+        '- `network.jsonl`: redacted network events',
+        '- `console.jsonl`: redacted console events',
+        '- `state/`: final state snapshots when available',
+        '- `screenshots/`: final screenshots when available',
+        '',
+    ];
+    return lines.join('\n');
+}
+function serializeSummaryError(error) {
+    if (error === undefined)
+        return undefined;
+    if (error instanceof CliError) {
+        return {
+            code: error.code,
+            message: String(redactValue(error.message)),
+            ...(error.hint ? { hint: String(redactValue(error.hint)) } : {}),
+        };
+    }
+    return { message: String(redactValue(getErrorMessage(error))) };
+}
+function yamlScalar(value) {
+    return JSON.stringify(value);
+}
+function renderErrorSection(error, errorEvents) {
+    const lines = [];
+    if (error) {
+        lines.push(`- ${error.code ?? 'UNKNOWN'}: ${error.message}`);
+        if (error.hint)
+            lines.push(`- hint: ${error.hint}`);
+    }
+    for (const event of errorEvents) {
+        if (event.stream !== 'error')
+            continue;
+        lines.push(`- ${formatTs(event.ts)} ${event.code ?? 'ERROR'}: ${event.message}`);
+    }
+    return lines.length ? lines : ['- none'];
+}
+function renderNetworkSection(events) {
+    if (!events.length)
+        return ['- none'];
+    return events.map((event) => {
+        const status = event.status ?? 'unknown';
+        const method = event.method ?? 'GET';
+        const contentType = event.contentType ? ` ${event.contentType}` : '';
+        return `- ${formatTs(event.ts)} ${status} ${method} ${event.url}${contentType}`;
+    });
+}
+function renderConsoleSection(events) {
+    if (!events.length)
+        return ['- none'];
+    return events.map((event) => `- ${formatTs(event.ts)} ${event.level}: ${trimLine(event.text, 240)}`);
+}
+function renderActionSection(events) {
+    if (!events.length)
+        return ['- none'];
+    return events.map((event) => {
+        const phase = event.phase ? ` ${event.phase}` : '';
+        const data = event.data && Object.keys(event.data).length
+            ? ` ${trimLine(JSON.stringify(redactValue(event.data)), 240)}`
+            : '';
+        return `- ${formatTs(event.ts)} ${event.name}${phase}${data}`;
+    });
+}
+function formatTs(ts) {
+    return new Date(ts).toISOString();
+}
+function trimLine(value, max) {
+    const compact = value.replace(/\s+/g, ' ').trim();
+    return compact.length > max ? `${compact.slice(0, max)}...` : compact;
+}

package/dist/src/observation/artifact.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/observation/artifact.test.js

@@ -0,0 +1,121 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { buildTraceReceipt, exportObservationSession, getTraceDirectory } from './artifact.js';
+import { ObservationSession } from './session.js';
+describe('observation artifact', () => {
+    let baseDir;
+    beforeEach(() => {
+        baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-trace-'));
+    });
+    afterEach(() => {
+        fs.rmSync(baseDir, { recursive: true, force: true });
+    });
+    it('writes artifacts under profile-scoped trace directory', () => {
+        const session = new ObservationSession({
+            id: 'trace-1',
+            scope: {
+                contextId: 'work',
+                session: 'site:demo',
+                site: 'demo',
+                command: 'demo/run',
+                adapterSourcePath: '/tmp/clis/demo/run.js',
+            },
+            now: () => 1_700_000_000_000,
+        });
+        session.record({ stream: 'action', name: 'command', phase: 'start' });
+        session.record({ stream: 'screenshot', format: 'png', data: Buffer.from('png-bytes').toString('base64'), label: 'final' });
+        session.record({
+            stream: 'network',
+            url: 'https://api.test/data?token=secret',
+            method: 'GET',
+            status: 500,
+            requestHeaders: { authorization: 'Bearer secret' },
+            responseBody: { ok: false },
+        });
+        session.record({ stream: 'console', level: 'error', text: 'boom password=supersecret' });
+        const result = exportObservationSession(session, { baseDir, error: new Error('failed') });
+        expect(result.dir).toBe(getTraceDirectory('work', 'trace-1', baseDir));
+        expect(fs.existsSync(path.join(result.dir, 'trace.jsonl'))).toBe(true);
+        expect(fs.existsSync(path.join(result.dir, 'network.jsonl'))).toBe(true);
+        expect(fs.existsSync(path.join(result.dir, 'console.jsonl'))).toBe(true);
+        expect(fs.existsSync(result.receiptPath)).toBe(true);
+        expect(fs.readFileSync(path.join(result.dir, 'screenshots', '0001.png'), 'utf-8')).toBe('png-bytes');
+        const trace = fs.readFileSync(path.join(result.dir, 'trace.jsonl'), 'utf-8');
+        expect(trace).toContain('token=[REDACTED]');
+        expect(trace).toContain('"authorization":"[REDACTED]"');
+        expect(trace).not.toContain('supersecret');
+        const summary = fs.readFileSync(result.summaryPath, 'utf-8');
+        expect(summary).toContain('schemaVersion: 1');
+        expect(summary).toContain('opencliVersion:');
+        expect(summary).toContain('expiresAt:');
+        expect(summary).toContain('status: failure');
+        expect(summary).toContain('contextId: "work"');
+        expect(summary).toContain('adapterSourcePath: "/tmp/clis/demo/run.js"');
+        expect(summary).toContain('adapterSourcePathExists: false');
+        expect(summary).toContain('## Failed Network');
+        expect(summary).toContain('500 GET https://api.test/data?token=[REDACTED]');
+        expect(summary).toContain('network: 1');
+        const receipt = JSON.parse(fs.readFileSync(result.receiptPath, 'utf-8'));
+        expect(receipt).toMatchObject({
+            schemaVersion: 1,
+            opencliVersion: expect.any(String),
+            traceId: 'trace-1',
+            traceDir: result.dir,
+            summaryPath: result.summaryPath,
+            receiptPath: result.receiptPath,
+            status: 'failure',
+            expiresAt: expect.any(String),
+            scope: {
+                contextId: 'work',
+                session: 'site:demo',
+                site: 'demo',
+                command: 'demo/run',
+                adapterSourcePath: '/tmp/clis/demo/run.js',
+            },
+            error: { message: 'failed' },
+        });
+    });
+    it('builds a compact trace receipt', () => {
+        const receipt = buildTraceReceipt({
+            traceId: 'trace-1',
+            dir: '/tmp/opencli/profiles/work/traces/trace-1',
+            summaryPath: '/tmp/opencli/profiles/work/traces/trace-1/summary.md',
+            receiptPath: '/tmp/opencli/profiles/work/traces/trace-1/receipt.json',
+        }, 'failure', new Error('failed with token=secret'), {
+            createdAt: '2026-05-03T00:00:00.000Z',
+            retentionPolicy: { maxAgeDays: 7 },
+        });
+        expect(receipt).toMatchObject({
+            schemaVersion: 1,
+            opencliVersion: expect.any(String),
+            traceId: 'trace-1',
+            traceDir: '/tmp/opencli/profiles/work/traces/trace-1',
+            receiptPath: '/tmp/opencli/profiles/work/traces/trace-1/receipt.json',
+            status: 'failure',
+            expiresAt: '2026-05-10T00:00:00.000Z',
+        });
+        expect(receipt.error?.message).toContain('token=[REDACTED]');
+    });
+    it('prunes older traces after export while protecting the exported trace', () => {
+        const oldTraceDir = getTraceDirectory('work', 'old-trace', baseDir);
+        fs.mkdirSync(oldTraceDir, { recursive: true });
+        fs.writeFileSync(path.join(oldTraceDir, 'receipt.json'), JSON.stringify({
+            createdAt: '2026-04-01T00:00:00.000Z',
+        }), 'utf-8');
+        fs.writeFileSync(path.join(oldTraceDir, 'trace.jsonl'), '{}\n', 'utf-8');
+        const session = new ObservationSession({
+            id: 'new-trace',
+            scope: { contextId: 'work', session: 'site:demo' },
+            now: () => Date.parse('2026-05-03T00:00:00.000Z'),
+        });
+        session.record({ stream: 'action', name: 'command', phase: 'start' });
+        const result = exportObservationSession(session, {
+            baseDir,
+            retentionPolicy: { maxAgeDays: 365, maxCountPerProfile: 1, maxBytesPerProfile: '500MB' },
+        });
+        expect(fs.existsSync(oldTraceDir)).toBe(false);
+        expect(fs.existsSync(result.dir)).toBe(true);
+    });
+});