@jackwener/opencli 1.6.8 → 1.6.10

package/dist/src/generate-verified.js

@@ -0,0 +1,696 @@
+/**
+ * Verified adapter generation:
+ * discover → synthesize → candidate-bound probe → single-session verify.
+ *
+ * v1 contract keeps scope narrow:
+ *   - PUBLIC + COOKIE only
+ *   - read-only JSON API surfaces
+ *   - single best candidate only
+ *   - bounded repair: select/itemPath replacement once
+ *
+ * Contract design principles:
+ *   1. machine-readable
+ *   2. explicit + explainable
+ *   3. testable + versioned
+ *   4. taxonomy by skill decision needs (not internal error sources)
+ *   5. early hint / terminal outcome share consistent decision language
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { exploreUrl } from './explore.js';
+import { loadExploreBundle, synthesizeFromExplore } from './synthesize.js';
+import { normalizeGoal, selectCandidate } from './generate.js';
+import { browserSession } from './runtime.js';
+import { executePipeline } from './pipeline/index.js';
+import { registerCommand, Strategy } from './registry.js';
+import { AuthRequiredError, BrowserConnectError, CommandExecutionError, SelectorError, TimeoutError, getErrorMessage, } from './errors.js';
+import { USER_CLIS_DIR } from './discovery.js';
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function parseSupportedStrategy(value) {
+    return value === Strategy.PUBLIC || value === Strategy.COOKIE ? value : null;
+}
+function commandName(site, name) {
+    return `${site}/${name}`;
+}
+function buildStats(args) {
+    return {
+        endpoint_count: args.endpointCount,
+        api_endpoint_count: args.apiEndpointCount,
+        candidate_count: args.candidateCount,
+        verified: args.verified ?? false,
+        repair_attempted: args.repairAttempted ?? false,
+        explore_dir: args.exploreDir,
+    };
+}
+function readCandidateJson(filePath) {
+    const loaded = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    if (!loaded || typeof loaded !== 'object') {
+        throw new CommandExecutionError(`Generated candidate is invalid: ${filePath}`);
+    }
+    return loaded;
+}
+function chooseEndpoint(capability, endpoints) {
+    if (!endpoints.length)
+        return null;
+    if (capability?.endpoint) {
+        const endpointPattern = capability.endpoint;
+        const exact = endpoints.find((endpoint) => endpoint.pattern === endpointPattern || endpoint.url.includes(endpointPattern));
+        if (exact)
+            return exact;
+    }
+    return [...endpoints].sort((a, b) => {
+        const aScore = (a.itemCount ?? 0) * 10 + Object.keys(a.detectedFields ?? {}).length;
+        const bScore = (b.itemCount ?? 0) * 10 + Object.keys(b.detectedFields ?? {}).length;
+        return bScore - aScore;
+    })[0] ?? null;
+}
+function cloneCandidate(candidate) {
+    return JSON.parse(JSON.stringify(candidate));
+}
+function hasBrowserOnlyStep(pipeline) {
+    return pipeline.some((step) => {
+        const op = Object.keys(step)[0];
+        return op === 'navigate' || op === 'wait' || op === 'evaluate' || op === 'click' || op === 'tap' || op === 'type' || op === 'press';
+    });
+}
+function detectBrowserFlag(candidate) {
+    return candidate.browser ?? hasBrowserOnlyStep(candidate.pipeline);
+}
+function candidateToCommand(candidate, source) {
+    return {
+        site: candidate.site,
+        name: candidate.name,
+        description: candidate.description,
+        domain: candidate.domain,
+        strategy: parseSupportedStrategy(candidate.strategy) ?? Strategy.COOKIE,
+        browser: detectBrowserFlag(candidate),
+        args: Object.entries(candidate.args ?? {}).map(([name, def]) => ({
+            name,
+            type: def.type,
+            required: def.required,
+            default: def.default,
+            help: def.description,
+        })),
+        columns: candidate.columns,
+        pipeline: candidate.pipeline,
+        source,
+    };
+}
+function buildDefaultArgs(candidate) {
+    const args = {};
+    for (const [name, def] of Object.entries(candidate.args ?? {})) {
+        if (def.default !== undefined) {
+            args[name] = def.default;
+            continue;
+        }
+        if (def.type === 'int' || def.type === 'number') {
+            args[name] = name === 'page' ? 1 : 20;
+            continue;
+        }
+        if (def.type === 'boolean' || def.type === 'bool') {
+            args[name] = false;
+            continue;
+        }
+        if (name === 'keyword' || name === 'query') {
+            args[name] = 'test';
+            continue;
+        }
+        if (def.required)
+            args[name] = 'test';
+    }
+    return args;
+}
+function getUnsupportedVerificationArgs(candidate) {
+    return Object.entries(candidate.args ?? {})
+        .filter(([name, def]) => {
+        if (!def.required || def.default !== undefined)
+            return false;
+        if (def.type === 'int' || def.type === 'number')
+            return false;
+        if (def.type === 'boolean' || def.type === 'bool')
+            return false;
+        if (name === 'keyword' || name === 'query')
+            return false;
+        return true;
+    })
+        .map(([name]) => name);
+}
+function assessResult(result, expectedFields = []) {
+    if (!Array.isArray(result))
+        return { ok: false, reason: 'non-array-result' };
+    if (result.length === 0)
+        return { ok: false, reason: 'empty-result' };
+    const sample = result[0];
+    if (!sample || typeof sample !== 'object' || Array.isArray(sample)) {
+        return { ok: false, reason: 'sparse-fields' };
+    }
+    const record = sample;
+    const keys = Object.keys(record);
+    const populated = keys.filter((key) => record[key] !== null && record[key] !== undefined && record[key] !== '');
+    if (populated.length < 2)
+        return { ok: false, reason: 'sparse-fields' };
+    if (expectedFields.length > 0) {
+        const matched = expectedFields.filter((field) => keys.includes(field));
+        if (matched.length === 0)
+            return { ok: false, reason: 'sparse-fields' };
+    }
+    return { ok: true };
+}
+function withItemPath(candidate, itemPath) {
+    if (!itemPath)
+        return null;
+    const next = cloneCandidate(candidate);
+    const selectIndex = next.pipeline.findIndex((step) => 'select' in step);
+    if (selectIndex === -1)
+        return null;
+    const current = next.pipeline[selectIndex];
+    if (current.select === itemPath)
+        return null;
+    next.pipeline[selectIndex] = { select: itemPath };
+    return next;
+}
+function applyStrategy(candidate, strategy) {
+    const next = cloneCandidate(candidate);
+    next.strategy = strategy;
+    if (strategy === Strategy.COOKIE)
+        next.browser = true;
+    return next;
+}
+// ── Escalation builders ───────────────────────────────────────────────────────
+function mapVerifyFailureToEscalation(reason) {
+    return reason; // VerifyFailureReason is a subset of EscalationReason
+}
+function suggestAction(reason) {
+    switch (reason) {
+        case 'unsupported-required-args': return 'ask-for-sample-arg';
+        case 'timeout': return 'inspect-with-browser';
+        case 'selector-mismatch': return 'inspect-with-browser';
+        case 'empty-result': return 'inspect-with-browser';
+        case 'sparse-fields': return 'inspect-with-browser';
+        case 'non-array-result': return 'inspect-with-browser';
+        case 'verify-inconclusive': return 'manual-review';
+    }
+}
+function buildEscalation(stage, reason, summary, site, opts) {
+    return {
+        stage,
+        reason,
+        confidence: opts?.confidence ?? 'medium',
+        suggested_action: suggestAction(reason),
+        candidate: {
+            name: summary.name,
+            command: commandName(site, summary.name),
+            path: summary.path ?? null,
+            reusability: opts?.reusability ?? 'unverified-candidate',
+        },
+    };
+}
+// ── Verification ──────────────────────────────────────────────────────────────
+async function verifyCandidate(page, candidate, expectedFields) {
+    try {
+        const result = await executePipeline(page, candidate.pipeline, {
+            args: buildDefaultArgs(candidate),
+        });
+        return assessResult(result, expectedFields);
+    }
+    catch (error) {
+        if (error instanceof BrowserConnectError) {
+            return { ok: false, terminal: 'blocked', reason: 'execution-environment-unavailable', issue: getErrorMessage(error) };
+        }
+        if (error instanceof AuthRequiredError) {
+            return { ok: false, terminal: 'blocked', reason: 'auth-too-complex', issue: getErrorMessage(error) };
+        }
+        if (error instanceof SelectorError) {
+            return { ok: false, terminal: 'needs-human-check', escalationReason: 'selector-mismatch', issue: getErrorMessage(error) };
+        }
+        if (error instanceof TimeoutError) {
+            return { ok: false, terminal: 'needs-human-check', escalationReason: 'timeout', issue: getErrorMessage(error) };
+        }
+        if (error instanceof CommandExecutionError) {
+            return { ok: false, terminal: 'needs-human-check', escalationReason: 'verify-inconclusive', issue: getErrorMessage(error) };
+        }
+        return { ok: false, terminal: 'needs-human-check', escalationReason: 'verify-inconclusive', issue: getErrorMessage(error) };
+    }
+}
+async function probeCandidateStrategy(page, endpointUrl) {
+    const { cascadeProbe } = await import('./cascade.js');
+    const result = await cascadeProbe(page, endpointUrl, { maxStrategy: Strategy.COOKIE });
+    const success = result.probes.find((probe) => probe.success);
+    return parseSupportedStrategy(success?.strategy);
+}
+// ── Artifact persistence ──────────────────────────────────────────────────────
+function candidateToTs(candidate) {
+    const strategyMap = {
+        public: 'Strategy.PUBLIC',
+        cookie: 'Strategy.COOKIE',
+        header: 'Strategy.HEADER',
+        intercept: 'Strategy.INTERCEPT',
+        ui: 'Strategy.UI',
+    };
+    const stratEnum = strategyMap[candidate.strategy?.toLowerCase()] ?? 'Strategy.COOKIE';
+    const browser = detectBrowserFlag(candidate);
+    const argsArray = Object.entries(candidate.args ?? {}).map(([name, def]) => {
+        const parts = [`name: '${name}'`];
+        if (def.type && def.type !== 'str')
+            parts.push(`type: '${def.type}'`);
+        if (def.required)
+            parts.push('required: true');
+        if (def.default !== undefined)
+            parts.push(`default: ${JSON.stringify(def.default)}`);
+        if (def.description)
+            parts.push(`help: '${def.description.replace(/'/g, "\\'")}'`);
+        return `    { ${parts.join(', ')} }`;
+    });
+    const formatStepValue = (v) => {
+        if (typeof v === 'string') {
+            if (v.includes('\n') || v.includes("'")) {
+                return '`' + v.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${') + '`';
+            }
+            return `'${v.replace(/\\/g, '\\\\')}'`;
+        }
+        if (typeof v === 'number' || typeof v === 'boolean')
+            return String(v);
+        if (v === null || v === undefined)
+            return 'undefined';
+        if (Array.isArray(v))
+            return `[${v.map(formatStepValue).join(', ')}]`;
+        if (typeof v === 'object') {
+            const entries = Object.entries(v);
+            const items = entries.map(([k, val]) => `${k}: ${formatStepValue(val)}`);
+            return `{ ${items.join(', ')} }`;
+        }
+        return String(v);
+    };
+    const pipelineSteps = (candidate.pipeline ?? []).map((step) => {
+        const entries = Object.entries(step);
+        if (entries.length === 1) {
+            const [op, value] = entries[0];
+            return `    { ${op}: ${formatStepValue(value)} }`;
+        }
+        return `    ${formatStepValue(step)}`;
+    });
+    const lines = [];
+    lines.push("import { cli, Strategy } from '@jackwener/opencli/registry';");
+    lines.push('');
+    lines.push('cli({');
+    lines.push(`  site: '${candidate.site}',`);
+    lines.push(`  name: '${candidate.name}',`);
+    if (candidate.description)
+        lines.push(`  description: '${candidate.description.replace(/'/g, "\\'")}',`);
+    if (candidate.domain)
+        lines.push(`  domain: '${candidate.domain}',`);
+    lines.push(`  strategy: ${stratEnum},`);
+    lines.push(`  browser: ${browser},`);
+    if (argsArray.length > 0) {
+        lines.push(`  args: [`);
+        lines.push(argsArray.join(',\n') + ',');
+        lines.push('  ],');
+    }
+    if (candidate.columns?.length) {
+        lines.push(`  columns: [${candidate.columns.map(c => `'${c}'`).join(', ')}],`);
+    }
+    if (pipelineSteps.length > 0) {
+        lines.push('  pipeline: [');
+        lines.push(pipelineSteps.join(',\n') + ',');
+        lines.push('  ],');
+    }
+    lines.push('});');
+    lines.push('');
+    return lines.join('\n');
+}
+async function registerVerifiedAdapter(candidate, metadata) {
+    const siteDir = path.join(USER_CLIS_DIR, candidate.site);
+    const adapterPath = path.join(siteDir, `${candidate.name}.ts`);
+    const metadataPath = path.join(siteDir, `${candidate.name}.meta.json`);
+    await fs.promises.mkdir(siteDir, { recursive: true });
+    await fs.promises.writeFile(adapterPath, candidateToTs(candidate));
+    await fs.promises.writeFile(metadataPath, JSON.stringify(metadata, null, 2));
+    registerCommand(candidateToCommand(candidate, adapterPath));
+    return { adapterPath, metadataPath };
+}
+async function writeVerifiedArtifact(candidate, exploreDir, metadata) {
+    const outDir = path.join(exploreDir, 'verified');
+    const adapterPath = path.join(outDir, `${candidate.name}.verified.ts`);
+    const metadataPath = path.join(outDir, `${candidate.name}.verified.meta.json`);
+    await fs.promises.mkdir(outDir, { recursive: true });
+    await fs.promises.writeFile(adapterPath, candidateToTs(candidate));
+    await fs.promises.writeFile(metadataPath, JSON.stringify(metadata, null, 2));
+    return { adapterPath, metadataPath };
+}
+// ── Session error classification ──────────────────────────────────────────────
+function classifySessionError(error, summary, stats, site) {
+    if (error instanceof BrowserConnectError) {
+        return {
+            status: 'blocked',
+            reason: 'execution-environment-unavailable',
+            stage: 'verify',
+            confidence: 'high',
+            message: getErrorMessage(error),
+            stats,
+        };
+    }
+    if (error instanceof AuthRequiredError) {
+        return {
+            status: 'blocked',
+            reason: 'auth-too-complex',
+            stage: 'verify',
+            confidence: 'high',
+            message: getErrorMessage(error),
+            stats,
+        };
+    }
+    return {
+        status: 'needs-human-check',
+        escalation: buildEscalation('verify', 'verify-inconclusive', summary, site, {
+            reusability: 'unverified-candidate',
+            confidence: 'low',
+        }),
+        reusability: 'unverified-candidate',
+        message: getErrorMessage(error),
+        stats,
+    };
+}
+// ── Main orchestrator ─────────────────────────────────────────────────────────
+export async function generateVerifiedFromUrl(opts) {
+    const normalizedGoal = normalizeGoal(opts.goal) ?? opts.goal ?? undefined;
+    const exploreResult = await exploreUrl(opts.url, {
+        BrowserFactory: opts.BrowserFactory,
+        site: opts.site,
+        goal: normalizedGoal,
+        waitSeconds: opts.waitSeconds ?? 3,
+        workspace: opts.workspace,
+    });
+    const bundle = loadExploreBundle(exploreResult.out_dir);
+    const synthesizeResult = synthesizeFromExplore(exploreResult.out_dir, { top: opts.top ?? 3 });
+    const selected = selectCandidate(synthesizeResult.candidates ?? [], opts.goal);
+    const baseStats = buildStats({
+        endpointCount: exploreResult.endpoint_count,
+        apiEndpointCount: exploreResult.api_endpoint_count,
+        candidateCount: synthesizeResult.candidate_count,
+        exploreDir: exploreResult.out_dir,
+    });
+    // ── Early hint: explore result ──────────────────────────────────────────
+    if (exploreResult.api_endpoint_count === 0) {
+        opts.onEarlyHint?.({
+            stage: 'explore',
+            continue: false,
+            reason: 'no-viable-api-surface',
+            confidence: 'high',
+        });
+        return {
+            status: 'blocked',
+            reason: 'no-viable-api-surface',
+            stage: 'explore',
+            confidence: 'high',
+            message: 'No JSON API endpoints discovered on this site.',
+            stats: baseStats,
+        };
+    }
+    opts.onEarlyHint?.({
+        stage: 'explore',
+        continue: true,
+        reason: 'api-surface-looks-viable',
+        confidence: 'medium',
+    });
+    // ── Early hint: synthesize result ───────────────────────────────────────
+    if (!selected || synthesizeResult.candidate_count === 0) {
+        opts.onEarlyHint?.({
+            stage: 'synthesize',
+            continue: false,
+            reason: 'no-viable-candidate',
+            confidence: 'high',
+        });
+        return {
+            status: 'blocked',
+            reason: 'no-viable-candidate',
+            stage: 'synthesize',
+            confidence: 'high',
+            message: 'No candidate met the quality threshold for verification.',
+            stats: baseStats,
+        };
+    }
+    const context = {
+        capability: bundle.capabilities.find((capability) => capability.name === selected.name),
+        endpoint: chooseEndpoint(bundle.capabilities.find((capability) => capability.name === selected.name), bundle.endpoints),
+    };
+    if (!context.endpoint) {
+        opts.onEarlyHint?.({
+            stage: 'synthesize',
+            continue: false,
+            reason: 'no-viable-candidate',
+            confidence: 'medium',
+        });
+        return {
+            status: 'blocked',
+            reason: 'no-viable-candidate',
+            stage: 'synthesize',
+            confidence: 'medium',
+            message: 'No endpoint could be matched to the selected candidate.',
+            stats: baseStats,
+        };
+    }
+    const expectedFields = Object.keys(context.endpoint.detectedFields ?? {});
+    const originalCandidate = readCandidateJson(selected.path);
+    const unsupportedArgs = getUnsupportedVerificationArgs(originalCandidate);
+    // ── Escalation: unsupported required args ───────────────────────────────
+    // Note: unsupported-required-args goes directly to P1 terminal.
+    // No P2 hint is emitted — this is a P1-only decision per design guardrail.
+    if (unsupportedArgs.length > 0) {
+        return {
+            status: 'needs-human-check',
+            escalation: buildEscalation('synthesize', 'unsupported-required-args', selected, bundle.manifest.site, {
+                reusability: 'unverified-candidate',
+                confidence: 'high',
+            }),
+            reusability: 'unverified-candidate',
+            message: `Auto-verification does not support required args: ${unsupportedArgs.join(', ')}`,
+            stats: baseStats,
+        };
+    }
+    opts.onEarlyHint?.({
+        stage: 'synthesize',
+        continue: true,
+        reason: 'candidate-ready-for-verify',
+        confidence: 'high',
+        candidate: {
+            name: selected.name,
+            command: commandName(bundle.manifest.site, selected.name),
+            path: selected.path ?? null,
+            reusability: 'unverified-candidate',
+        },
+    });
+    // ── Phase 3: single browser session (probe + verify + repair) ───────────
+    try {
+        return await browserSession(opts.BrowserFactory, async (page) => {
+            await page.goto(bundle.manifest.final_url ?? bundle.manifest.target_url);
+            // ── Probe: candidate-bound strategy ─────────────────────────────────
+            const bestStrategy = await probeCandidateStrategy(page, context.endpoint.url);
+            if (!bestStrategy) {
+                opts.onEarlyHint?.({
+                    stage: 'cascade',
+                    continue: false,
+                    reason: 'auth-too-complex',
+                    confidence: 'high',
+                });
+                return {
+                    status: 'blocked',
+                    reason: 'auth-too-complex',
+                    stage: 'cascade',
+                    confidence: 'high',
+                    message: 'No PUBLIC or COOKIE strategy succeeded for this endpoint.',
+                    stats: baseStats,
+                };
+            }
+            opts.onEarlyHint?.({
+                stage: 'cascade',
+                continue: true,
+                reason: 'candidate-ready-for-verify',
+                confidence: 'high',
+                candidate: {
+                    name: selected.name,
+                    command: commandName(bundle.manifest.site, selected.name),
+                    path: selected.path ?? null,
+                    reusability: 'unverified-candidate',
+                },
+            });
+            const candidate = applyStrategy(originalCandidate, bestStrategy);
+            const goalStr = normalizedGoal ?? opts.goal ?? null;
+            const buildMetadata = () => ({
+                artifact_kind: 'verified',
+                schema_version: 1,
+                source_url: opts.url,
+                goal: goalStr,
+                strategy: bestStrategy,
+                verified: true,
+                reusable: true,
+                reusability_reason: 'verified-artifact',
+            });
+            // ── First verify attempt ────────────────────────────────────────────
+            const firstAttempt = await verifyCandidate(page, candidate, expectedFields);
+            if (firstAttempt.ok) {
+                const artifact = opts.noRegister
+                    ? await writeVerifiedArtifact(candidate, exploreResult.out_dir, buildMetadata())
+                    : await registerVerifiedAdapter(candidate, buildMetadata());
+                return {
+                    status: 'success',
+                    adapter: {
+                        site: candidate.site,
+                        name: candidate.name,
+                        command: commandName(candidate.site, candidate.name),
+                        strategy: bestStrategy,
+                        path: artifact.adapterPath,
+                        metadata_path: artifact.metadataPath,
+                        reusability: 'verified-artifact',
+                    },
+                    reusability: 'verified-artifact',
+                    stats: buildStats({
+                        endpointCount: exploreResult.endpoint_count,
+                        apiEndpointCount: exploreResult.api_endpoint_count,
+                        candidateCount: synthesizeResult.candidate_count,
+                        verified: true,
+                        repairAttempted: false,
+                        exploreDir: exploreResult.out_dir,
+                    }),
+                };
+            }
+            // ── Terminal from first attempt ─────────────────────────────────────
+            if ('terminal' in firstAttempt) {
+                if (firstAttempt.terminal === 'blocked') {
+                    return {
+                        status: 'blocked',
+                        reason: firstAttempt.reason ?? 'execution-environment-unavailable',
+                        stage: 'verify',
+                        confidence: 'high',
+                        message: firstAttempt.issue,
+                        stats: baseStats,
+                    };
+                }
+                return {
+                    status: 'needs-human-check',
+                    escalation: buildEscalation('verify', firstAttempt.escalationReason ?? 'verify-inconclusive', selected, bundle.manifest.site, { reusability: 'unverified-candidate', confidence: 'medium' }),
+                    reusability: 'unverified-candidate',
+                    message: firstAttempt.issue,
+                    stats: baseStats,
+                };
+            }
+            // ── Bounded repair: itemPath relocation ─────────────────────────────
+            const repaired = firstAttempt.reason === 'empty-result'
+                ? withItemPath(candidate, context.endpoint?.itemPath ?? null)
+                : null;
+            if (!repaired) {
+                const escalationReason = mapVerifyFailureToEscalation(firstAttempt.reason);
+                return {
+                    status: 'needs-human-check',
+                    escalation: buildEscalation('verify', escalationReason, selected, bundle.manifest.site, {
+                        reusability: 'unverified-candidate',
+                        confidence: 'medium',
+                    }),
+                    reusability: 'unverified-candidate',
+                    message: `Verification failed: ${firstAttempt.reason}`,
+                    stats: buildStats({
+                        endpointCount: exploreResult.endpoint_count,
+                        apiEndpointCount: exploreResult.api_endpoint_count,
+                        candidateCount: synthesizeResult.candidate_count,
+                        repairAttempted: firstAttempt.reason === 'empty-result',
+                        exploreDir: exploreResult.out_dir,
+                    }),
+                };
+            }
+            // ── Second verify attempt (after repair) ───────────────────────────
+            const secondAttempt = await verifyCandidate(page, repaired, expectedFields);
+            const repairedStats = buildStats({
+                endpointCount: exploreResult.endpoint_count,
+                apiEndpointCount: exploreResult.api_endpoint_count,
+                candidateCount: synthesizeResult.candidate_count,
+                repairAttempted: true,
+                exploreDir: exploreResult.out_dir,
+            });
+            if (secondAttempt.ok) {
+                const artifact = opts.noRegister
+                    ? await writeVerifiedArtifact(repaired, exploreResult.out_dir, buildMetadata())
+                    : await registerVerifiedAdapter(repaired, buildMetadata());
+                return {
+                    status: 'success',
+                    adapter: {
+                        site: repaired.site,
+                        name: repaired.name,
+                        command: commandName(repaired.site, repaired.name),
+                        strategy: bestStrategy,
+                        path: artifact.adapterPath,
+                        metadata_path: artifact.metadataPath,
+                        reusability: 'verified-artifact',
+                    },
+                    reusability: 'verified-artifact',
+                    stats: { ...repairedStats, verified: true },
+                };
+            }
+            if ('terminal' in secondAttempt) {
+                if (secondAttempt.terminal === 'blocked') {
+                    return {
+                        status: 'blocked',
+                        reason: secondAttempt.reason ?? 'execution-environment-unavailable',
+                        stage: 'fallback',
+                        confidence: 'high',
+                        message: secondAttempt.issue,
+                        stats: repairedStats,
+                    };
+                }
+                return {
+                    status: 'needs-human-check',
+                    escalation: buildEscalation('fallback', secondAttempt.escalationReason ?? 'verify-inconclusive', selected, bundle.manifest.site, { reusability: 'unverified-candidate', confidence: 'low' }),
+                    reusability: 'unverified-candidate',
+                    message: secondAttempt.issue,
+                    stats: repairedStats,
+                };
+            }
+            // ── Repair exhausted ────────────────────────────────────────────────
+            const escalationReason = mapVerifyFailureToEscalation(secondAttempt.reason);
+            return {
+                status: 'needs-human-check',
+                escalation: buildEscalation('fallback', escalationReason, selected, bundle.manifest.site, {
+                    reusability: 'unverified-candidate',
+                    confidence: 'low',
+                }),
+                reusability: 'unverified-candidate',
+                message: `Repair exhausted: ${secondAttempt.reason}`,
+                stats: repairedStats,
+            };
+        }, { workspace: opts.workspace });
+    }
+    catch (error) {
+        return classifySessionError(error, selected, baseStats, bundle.manifest.site);
+    }
+}
+// ── Render ────────────────────────────────────────────────────────────────────
+export function renderGenerateVerifiedSummary(result) {
+    const lines = [
+        `opencli generate: ${result.status.toUpperCase()}`,
+    ];
+    if (result.status === 'success' && result.adapter) {
+        lines.push(`Command: ${result.adapter.command}`);
+        lines.push(`Strategy: ${result.adapter.strategy}`);
+        lines.push(`Path: ${result.adapter.path}`);
+    }
+    else if (result.status === 'blocked') {
+        lines.push(`Reason: ${result.reason}`);
+        lines.push(`Stage: ${result.stage}`);
+        lines.push(`Confidence: ${result.confidence}`);
+        if (result.message)
+            lines.push(`Message: ${result.message}`);
+    }
+    else if (result.status === 'needs-human-check' && result.escalation) {
+        lines.push(`Stage: ${result.escalation.stage}`);
+        lines.push(`Reason: ${result.escalation.reason}`);
+        lines.push(`Suggested action: ${result.escalation.suggested_action}`);
+        lines.push(`Candidate: ${result.escalation.candidate.command}`);
+        lines.push(`Reusability: ${result.escalation.candidate.reusability}`);
+        if (result.message)
+            lines.push(`Message: ${result.message}`);
+    }
+    lines.push('');
+    lines.push(`Explore: ${result.stats.endpoint_count} endpoints, ${result.stats.api_endpoint_count} API`);
+    lines.push(`Candidates: ${result.stats.candidate_count}`);
+    lines.push(`Verified: ${result.stats.verified ? 'yes' : 'no'}`);
+    lines.push(`Repair attempted: ${result.stats.repair_attempted ? 'yes' : 'no'}`);
+    return lines.join('\n');
+}