@12ui/design 0.2.26 → 0.2.28

package/dist/cli-convert-command.js

@@ -3,19 +3,21 @@ import { readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { materializeConversionArtifacts } from './artifact-materializer.js';
 import { booleanFlag, stringFlag } from './cli-arguments.js';
-import { prepareOutputFile, prepareOutputTarget } from './cli-output-paths.js';
-import { CONVERSION_DURATION_HINTS, createProgressReporter, durationHint, nextActionLine, } from './cli-progress.js';
-import { refuseUsage, usage } from './cli-usage.js';
+import { prepareOutputDirectory, prepareOutputFile } from './cli-output-paths.js';
+import { runConversionDerivation } from './cli-conversion-derivation.js';
+import { CONVERSION_DURATION_HINTS, createLongRunningProgress, } from './cli-progress.js';
+import { refuseUsage, usage, usageRefusal } from './cli-usage.js';
 import { readConversionConfig } from './config.js';
 import { TwelveUiConversionClient, } from './conversion-client.js';
 import { isConversionModel } from './conversion-models.js';
-import { isConversionOutput } from './conversion-outputs.js';
+import { isCliConversionOutput, } from './conversion-outputs.js';
 import { recordConvertedImageReceipt } from './conversion-receipt.js';
+import { readConversionRecovery, writeConversionRecovery, } from './conversion-recovery.js';
 import { isPendingConversionStatus, readConversionStatus, wrongConversionOutputRefusal, } from './conversion-status-contract.js';
 import { normalizeOptionalIdempotencyKey } from './idempotency-key.js';
 import { classifyLocalConversionInput, createInputForLocalFile, defaultConversionOutputPath, } from './local-conversion-input.js';
 import { normalizeImageOutputWidth, parseImageOutputWidth, } from './image-output-width.js';
-import { isProjectConversionOutput, parseConversionOutputProfile, } from './project-profiles.js';
+import { resolveNextTarget } from './next-target.js';
 import { isResponsiveConversionQuality, RESPONSIVE_CONVERSION_QUALITIES, } from './responsive-quality.js';
 import { describeInFlightRecord, readInFlightRunJournal, } from './run-journal-in-flight.js';
 /**
@@ -32,27 +34,6 @@ export const parseTimeoutMs = (value) => {
     }
     return Math.floor(timeoutMs);
 };
-const parseProjectProfileFlag = async (output, value) => {
-    if (!isProjectConversionOutput(output)) {
-        if (value !== undefined)
-            throw new Error('--profile is only valid for project outputs');
-        return undefined;
-    }
-    if (!value?.trim())
-        throw new Error(`--profile is required for ${output}`);
-    const trimmed = value.trim();
-    const source = trimmed.startsWith('{')
-        ? trimmed
-        : await readFile(path.resolve(trimmed.startsWith('@') ? trimmed.slice(1) : trimmed), 'utf8');
-    let parsed;
-    try {
-        parsed = JSON.parse(source);
-    }
-    catch (error) {
-        throw new Error(`--profile must contain valid JSON: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    return parseConversionOutputProfile(output, parsed);
-};
 const downloadCompletedConversion = async (args) => {
     const downloaded = await args.client.downloadResult(args.operation.id, args.output);
     await writeFile(args.outFile, downloaded.bytes);
@@ -61,9 +42,47 @@ const downloadCompletedConversion = async (args) => {
         id: args.operation.id,
         output: args.output,
         outFile: args.outFile,
-        artifactManifest,
+        // The artifact inventory lives in the on-disk manifest the materializer
+        // just wrote; the payload references it instead of inlining the array.
+        // The board's fused capture spent 243 of 257 lines printing the same 14
+        // artifacts twice — the manifest file already held every byte of it.
+        artifactManifest: {
+            conversionId: artifactManifest.conversionId,
+            operationExpiresAt: artifactManifest.operationExpiresAt,
+            manifestFile: artifactManifest.manifestFile,
+            artifactCount: artifactManifest.artifacts.length,
+        },
     };
 };
+const reportConversion = (reporter, operation, detail) => {
+    reporter.update({
+        // A succeeded child can still be followed by local materialization or by
+        // another member of a fused request. Keep the overall line honest: the
+        // reporter owns terminality, while a child success means collection is
+        // beginning rather than `running | stage succeeded`.
+        stage: operation.status === 'succeeded'
+            ? 'collecting'
+            : operation.progress?.stage ?? operation.status,
+        // The raw percent is deliberately NOT forwarded (owner, 2026-08-21):
+        // it is the measured stuck metric. The service's per-lane counters are
+        // the advancing signal behind every stale percent (`extracting layers
+        // 2%` held 45s on the board while the lanes moved); render them
+        // rather than discarding them.
+        ...(operation.status !== 'succeeded' && operation.progress?.active?.length
+            ? { lanes: operation.progress.active }
+            : {}),
+        ...(operation.status !== 'succeeded' && operation.progress?.milestone
+            ? { milestone: operation.progress.milestone }
+            : {}),
+        ...(operation.status !== 'succeeded' && operation.progress?.stage_since
+            ? { stageSince: operation.progress.stage_since }
+            : {}),
+        ...(operation.status !== 'succeeded' && operation.progress?.attempt !== undefined
+            ? { attempt: operation.progress.attempt }
+            : {}),
+        ...(detail ? { detail } : {}),
+    });
+};
 /**
  * A LayerDoc landed on disk and no page was written from it.
  *
@@ -78,6 +97,20 @@ const downloadCompletedConversion = async (args) => {
 export const layerDocPageAction = (outFile) => (`The document is written and no page was rendered from it. To render one:`
     + ` \`12ui convert ${outFile} --output html_fixed\`. A LayerDoc on disk is valid input for`
     + ' every output, so this derives the page rather than converting the image again.');
+export const layerDocStateAction = (args) => {
+    const linked = args.linkedExport;
+    if (!linked)
+        return layerDocPageAction(args.outFile);
+    if (linked.status === 'succeeded') {
+        return `Responsive page already exported${linked.outFile ? `: ${linked.outFile}` : ''}`
+            + ` (export ${linked.id}).`;
+    }
+    if (isPendingConversionStatus(linked.status)) {
+        return `Responsive page export ${linked.id} is ${linked.status};`
+            + ' the original purchase is still working.';
+    }
+    return `Responsive page export ${linked.id} is ${linked.status}; no additional conversion was bought.`;
+};
 /**
  * A conversion of these exact bytes is already running in this workspace.
  *
@@ -105,30 +138,142 @@ export const secondConversionNotice = (args) => ('These exact bytes are already
     + ` Read it from any shell with \`12ui next ${args.workspace}\` — that costs nothing and does not`
     + ' wait on this command. Continuing starts a SECOND, independently paid conversion of the same'
     + ' image.');
-/** The result JSON, plus the page action whenever a document stands alone. */
-const conversionResultJson = (result) => JSON.stringify({
+/** The result JSON, with guidance derived from the linked operation's real state. */
+const conversionResultJson = (result, linkedExport) => JSON.stringify({
     ...result,
-    ...(result.output === 'layerdoc' ? { nextAction: layerDocPageAction(result.outFile) } : {}),
+    ...(result.output === 'layerdoc'
+        ? { nextAction: layerDocStateAction({ outFile: result.outFile, ...(linkedExport ? { linkedExport } : {}) }) }
+        : {}),
 }, null, 2);
-const writeCompletedConversion = async (args) => {
-    console.log(conversionResultJson(await downloadCompletedConversion(args)));
+/**
+ * stdout is the machine surface: exactly one JSON document, nothing else.
+ * Human summaries (paths, per-format states) live in the stderr terminal
+ * block, so an agent can parse stdout without stripping trailing prose.
+ */
+const writeResultWithSummary = (result) => {
+    console.log(JSON.stringify(result, null, 2));
+};
+const outputPathForRecovery = async (artifact, overrideDirectory) => prepareOutputFile(overrideDirectory
+    ? path.join(overrideDirectory, path.basename(artifact.outFile))
+    : artifact.outFile);
+const completedOperation = async (args) => {
+    const current = await args.client.getConversion(args.id);
+    args.onProgress?.(current);
+    return current.status === 'succeeded'
+        ? current
+        : args.client.waitForConversion(current.id, {
+            expiresAt: current.expires_at,
+            timeoutMs: args.timeoutMs,
+            ...(args.onProgress ? { onProgress: args.onProgress } : {}),
+        });
+};
+const recoverOriginalPurchase = async (args) => {
+    const overrideDirectory = args.outDir
+        ? await prepareOutputDirectory(args.outDir)
+        : undefined;
+    const conversionOutFile = await outputPathForRecovery(args.record.conversion, overrideDirectory);
+    const linkedOutFile = args.record.linkedExport
+        ? await outputPathForRecovery(args.record.linkedExport, overrideDirectory)
+        : undefined;
+    const conversion = await completedOperation({
+        client: args.client,
+        id: args.record.conversion.conversionId,
+        ...(args.timeoutMs === undefined ? {} : { timeoutMs: args.timeoutMs }),
+        onProgress: (operation) => reportConversion(args.progress, operation, `recovering conversion ${args.record.conversion.conversionId}`),
+    });
+    if (conversion.output !== args.record.conversion.output) {
+        throw new Error(`Recovery record expects ${args.record.conversion.output}, but conversion ${conversion.id}`
+            + ` produces ${conversion.output}.`);
+    }
+    const converted = await downloadCompletedConversion({
+        client: args.client,
+        operation: conversion,
+        output: args.record.conversion.output,
+        outFile: conversionOutFile,
+    });
+    let linkedResult;
+    let linkedOperation;
+    if (args.record.linkedExport && linkedOutFile) {
+        linkedOperation = await completedOperation({
+            client: args.client,
+            id: args.record.linkedExport.conversionId,
+            ...(args.timeoutMs === undefined ? {} : { timeoutMs: args.timeoutMs }),
+            onProgress: (operation) => reportConversion(args.progress, operation, `recovering linked export ${args.record.linkedExport.conversionId}`),
+        });
+        if (linkedOperation.output !== args.record.linkedExport.output) {
+            throw new Error(`Recovery record expects ${args.record.linkedExport.output}, but linked conversion`
+                + ` ${linkedOperation.id} produces ${linkedOperation.output}.`);
+        }
+        linkedResult = await downloadCompletedConversion({
+            client: args.client,
+            operation: linkedOperation,
+            output: args.record.linkedExport.output,
+            outFile: linkedOutFile,
+        });
+    }
+    const artifacts = [conversionOutFile, ...(linkedOutFile ? [linkedOutFile] : [])];
+    args.journal.note({ runId: conversion.id, artifacts, terminal: true });
+    const nextAction = conversion.output === 'layerdoc'
+        ? layerDocStateAction({
+            outFile: conversionOutFile,
+            ...(linkedOperation
+                ? {
+                    linkedExport: {
+                        id: linkedOperation.id,
+                        status: linkedOperation.status,
+                        ...(linkedOutFile ? { outFile: linkedOutFile } : {}),
+                    },
+                }
+                : {}),
+        })
+        : undefined;
+    args.progress.finish('succeeded', {
+        artifacts: [
+            {
+                name: args.record.conversion.output,
+                state: 'recovered free',
+                path: conversionOutFile,
+            },
+            ...(linkedOutFile
+                ? [{ name: 'responsive html', state: 'recovered free', path: linkedOutFile }]
+                : []),
+        ],
+        spend: 'nothing new — the original purchase was collected',
+    });
+    writeResultWithSummary({
+        ...converted,
+        ...(nextAction ? { nextAction } : {}),
+        ...(linkedResult ? { export: { ...linkedResult, status: 'succeeded' } } : {}),
+    });
 };
 export const runConversionCommand = async (command, flags, journal) => {
     const commandStartedAt = Date.now();
     const verb = command[0];
-    // `12ui convert <image> --export html` is the whole command for a single
-    // screen. The export is derived from a LayerDoc conversion, so asking for the
-    // output as well is asking the caller to restate the only value it can have.
-    const outputValue = stringFlag(flags, 'output')
-        ?? (stringFlag(flags, 'export') !== undefined ? 'layerdoc' : undefined);
-    const output = isConversionOutput(outputValue) ? outputValue : refuseUsage({
-        reason: outputValue === undefined
-            ? `${verb === 'resume' ? 'A resume collects' : 'A conversion produces'} one named format,`
-                + ' and --output was not given.'
-            : `\`${outputValue}\` is not one of the outputs this CLI produces.`,
-        code: 'cli_usage',
-        verb: [verb === 'resume' ? 'resume' : 'convert'],
-    });
+    if (verb === 'convert') {
+        const retiredFlags = [
+            'export', 'export-quality', 'export-out', 'out', 'profile',
+            'web-profile', 'app-profile', 'detach',
+        ].filter((flag) => flags[flag] !== undefined);
+        if (retiredFlags.length > 0) {
+            throw new Error(`${retiredFlags.map((flag) => `--${flag}`).join(', ')} retired from 12ui convert.`
+                + ' Use --output to name the result and --out-dir to name its directory.');
+        }
+        const target = command[1] ? await resolveNextTarget(command[1]) : null;
+        if (target?.kind === 'conversion') {
+            for (const flag of ['model', 'width']) {
+                if (flags[flag] !== undefined) {
+                    throw new Error(`--${flag} applies to image input, not a conversion id`);
+                }
+            }
+            const derived = await runConversionDerivation(target.conversionId, flags);
+            journal.note({
+                runId: target.conversionId,
+                artifacts: [derived.manifestPath, ...derived.results.map((result) => result.outFile)],
+                purchased: derived.results.map((result) => result.conversionId),
+            });
+            return;
+        }
+    }
     const timeoutMs = parseTimeoutMs(stringFlag(flags, 'timeout-ms'));
     // Credentials resolve only after the invocation has proven usable: a usage
     // refusal must never depend on having an API key. The deploy gate caught the
@@ -138,58 +283,189 @@ export const runConversionCommand = async (command, flags, journal) => {
         apiKey: stringFlag(flags, 'api-key'),
     }));
     if (verb === 'resume') {
-        if (stringFlag(flags, 'profile') !== undefined
-            || stringFlag(flags, 'model') !== undefined
+        if (stringFlag(flags, 'model') !== undefined
             || stringFlag(flags, 'width') !== undefined
             || stringFlag(flags, 'responsive-quality') !== undefined
             || booleanFlag(flags, 'detach')) {
-            throw new Error('--profile, --model, --width, --responsive-quality, and --detach are not accepted by resume');
+            throw new Error('--model, --width, --responsive-quality, and --detach are not accepted by resume');
         }
         const conversionId = command[1]?.trim();
-        const outFile = stringFlag(flags, 'out');
         if (!conversionId) {
             refuseUsage({
-                reason: 'A resume collects one conversion already bought, and no conversion id was given.'
+                reason: 'A resume collects one purchase already bought, and no conversion id was given.'
                     + ' Every command that starts one prints it.',
                 code: 'cli_usage',
                 verb: ['resume'],
             });
         }
-        // File-only on purpose: a resume writes exactly one artifact, so there is
-        // nothing here to derive a name from the way `convert --out <dir>` does.
-        const resolvedOutFile = await prepareOutputFile(outFile || refuseUsage({
-            reason: 'A resume writes the collected result to a file, and --out was not given.',
-            code: 'cli_usage',
-            verb: ['resume'],
-        }));
         const client = conversionClient();
-        const current = await client.getConversion(conversionId);
-        if (current.output !== output) {
+        const outputValue = stringFlag(flags, 'output');
+        const outFile = stringFlag(flags, 'out');
+        if (outputValue === undefined && outFile === undefined) {
+            const recovery = await readConversionRecovery(conversionId);
+            if (!recovery) {
+                throw usageRefusal({
+                    reason: `No local recovery record was found for ${conversionId}. Bare resume works for`
+                        + ' purchases started by this CLI; use the power form below for an older or foreign id.',
+                    code: 'resume_recovery_missing',
+                    verb: ['resume'],
+                });
+            }
+            const progress = createLongRunningProgress({
+                label: `resume ${conversionId}`,
+                typicalSeconds: recovery.linkedExport
+                    ? CONVERSION_DURATION_HINTS.fused
+                    : CONVERSION_DURATION_HINTS.convert,
+                quiet: booleanFlag(flags, 'quiet'),
+            });
+            // A resume collects work already bought. Settled work arrives in
+            // seconds, so no expectation is quoted (the board's bare resume quoted
+            // ~5m for a 4s collection); only work still running server-side waits.
+            // The done paths honor --out-dir: the v2 board caught the brief quoting
+            // the record's original directory while the artifacts landed elsewhere.
+            const overrideDir = stringFlag(flags, 'out-dir');
+            const shownPath = (file) => (overrideDir
+                ? path.join(path.resolve(overrideDir), path.basename(file))
+                : file);
+            progress.brief({
+                request: `resume ${conversionId}: collect the original purchase`,
+                free: 'everything already settled server-side is recovered without buying again',
+                done: recovery.linkedExport
+                    ? `${shownPath(recovery.conversion.outFile)} + ${shownPath(recovery.linkedExport.outFile)}`
+                    : shownPath(recovery.conversion.outFile),
+                blocking: true,
+            });
+            progress.update({ stage: 'prepare', detail: 'reading the original purchase' });
+            try {
+                await recoverOriginalPurchase({
+                    client,
+                    record: recovery,
+                    journal,
+                    progress,
+                    ...(stringFlag(flags, 'out-dir') ? { outDir: stringFlag(flags, 'out-dir') } : {}),
+                    ...(timeoutMs === undefined ? {} : { timeoutMs }),
+                });
+            }
+            catch (error) {
+                progress.finish('stopped', {
+                    detail: error instanceof Error ? error.message : String(error),
+                    next: `re-run 12ui resume ${conversionId}; collection is free until the purchase expires`,
+                });
+                throw error;
+            }
+            return;
+        }
+        if (outputValue === undefined || outFile === undefined) {
+            throw usageRefusal({
+                reason: 'The optional power form needs both --output and --out; omit both to recover the'
+                    + ' original purchase and filenames.',
+                code: 'resume_power_form_incomplete',
+                verb: ['resume'],
+            });
+        }
+        if (stringFlag(flags, 'out-dir') !== undefined) {
+            throw new Error('--out-dir overrides original filenames only on bare resume; power resume uses --out');
+        }
+        const requestedOutput = isCliConversionOutput(outputValue)
+            ? outputValue
+            : refuseUsage({
+                reason: `\`${outputValue}\` is not one of the outputs this CLI produces.`,
+                code: 'cli_usage',
+                verb: ['resume'],
+            });
+        const resolvedOutFile = await prepareOutputFile(outFile);
+        const progress = createLongRunningProgress({
+            label: `resume ${conversionId}`,
+            typicalSeconds: requestedOutput === 'html'
+                ? CONVERSION_DURATION_HINTS.export
+                : CONVERSION_DURATION_HINTS.convert,
+            quiet: booleanFlag(flags, 'quiet'),
+        });
+        progress.brief({
+            request: `resume ${conversionId}: collect ${requestedOutput}`,
+            free: 'a settled purchase is recovered without buying again',
+            done: resolvedOutFile,
+            blocking: true,
+        });
+        progress.update({ stage: 'prepare', detail: 'reading the existing purchase' });
+        const current = await client.getConversion(conversionId).catch((error) => {
+            progress.finish('stopped', {
+                detail: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        });
+        if (current.output !== requestedOutput) {
+            progress.finish('stopped', {
+                detail: `purchase produces ${current.output}, not ${requestedOutput}`,
+            });
             // The refusal is written from an object that carries the id the caller
             // actually wants, so it names both rather than only the unusable one.
             throw new Error(wrongConversionOutputRefusal({
                 operation: current,
-                requested: output,
+                requested: requestedOutput,
                 collect: (id, kind) => `12ui resume ${id} --output ${kind} --out <file>`,
             }));
         }
-        const completed = current.status === 'succeeded'
-            ? current
-            : await client.waitForConversion(current.id, {
-                expiresAt: current.expires_at,
-                timeoutMs,
+        reportConversion(progress, current, `collecting ${requestedOutput}`);
+        let completed;
+        try {
+            completed = current.status === 'succeeded'
+                ? current
+                : await client.waitForConversion(current.id, {
+                    expiresAt: current.expires_at,
+                    timeoutMs,
+                    onProgress: (operation) => reportConversion(progress, operation, `collecting ${requestedOutput}`),
+                });
+        }
+        catch (error) {
+            progress.finish('stopped', {
+                detail: error instanceof Error ? error.message : String(error),
+                next: `re-run 12ui resume ${conversionId} --output ${requestedOutput} --out ${resolvedOutFile};`
+                    + ' collection is free until the purchase expires',
             });
-        await writeCompletedConversion({
+            throw error;
+        }
+        const downloaded = await downloadCompletedConversion({
             client,
             operation: completed,
-            output,
+            output: requestedOutput,
             outFile: resolvedOutFile,
         });
         journal.note({ runId: completed.id, artifacts: [resolvedOutFile] });
+        let linkedExport;
+        if (completed.output === 'layerdoc' && completed.export?.conversion_id) {
+            const linked = await client.getConversion(completed.export.conversion_id);
+            linkedExport = { id: linked.id, status: linked.status };
+        }
+        progress.finish('succeeded', {
+            artifacts: [{ name: requestedOutput, state: 'recovered free', path: resolvedOutFile }],
+            spend: 'nothing new — the existing purchase was collected',
+        });
+        writeResultWithSummary({
+            ...downloaded,
+            ...(downloaded.output === 'layerdoc'
+                ? {
+                    nextAction: layerDocStateAction({
+                        outFile: downloaded.outFile,
+                        ...(linkedExport ? { linkedExport } : {}),
+                    }),
+                }
+                : {}),
+        });
         return;
     }
     if (verb !== 'convert')
         usage();
+    const outputValue = stringFlag(flags, 'output');
+    const requestedOutput = isCliConversionOutput(outputValue)
+        ? outputValue
+        : refuseUsage({
+            reason: outputValue === undefined
+                ? 'A conversion produces one named format, and --output was not given.'
+                : `\`${outputValue}\` is not one of the outputs this CLI produces.`,
+            code: 'cli_usage',
+            verb: ['convert'],
+        });
     if (!command[1]) {
         refuseUsage({
             reason: 'A conversion starts from one image or one LayerDoc on disk, and no input was named.',
@@ -211,9 +487,10 @@ export const runConversionCommand = async (command, flags, journal) => {
     if (responsiveValue !== undefined && !isResponsiveConversionQuality(responsiveValue)) {
         throw new Error(`--responsive-quality must be one of: ${RESPONSIVE_CONVERSION_QUALITIES.join(', ')}`);
     }
-    const profile = await parseProjectProfileFlag(output, stringFlag(flags, 'profile'));
     const inputPath = path.resolve(command[1]);
     const localInput = classifyLocalConversionInput(inputPath);
+    const fusedHtml = localInput.kind === 'image' && requestedOutput === 'html';
+    const output = fusedHtml ? 'layerdoc' : requestedOutput;
     const outputWidth = parseImageOutputWidth(stringFlag(flags, 'width'));
     if (outputWidth !== undefined && localInput.kind === 'layerdoc') {
         throw new Error('--width is only valid for image input');
@@ -230,7 +507,6 @@ export const runConversionCommand = async (command, flags, journal) => {
         bytes: inputBytes,
         filePath: inputPath,
         output,
-        ...(profile ? { profile } : {}),
     });
     const idempotencyKey = normalizeOptionalIdempotencyKey(stringFlag(flags, 'idempotency-key'), '--idempotency-key');
     if (input.layerdoc !== undefined && model)
@@ -238,67 +514,48 @@ export const runConversionCommand = async (command, flags, journal) => {
     if (input.layerdoc !== undefined && responsiveValue) {
         throw new Error('--responsive-quality with LayerDoc input requires the SDK source-conversion workflow');
     }
-    if (responsiveValue && output !== 'html') {
+    if (responsiveValue && requestedOutput !== 'html') {
         throw new Error('--responsive-quality is only valid with --output html');
     }
-    // --export asks for the responsive HTML export to run ALONGSIDE the
-    // conversion in one blocking command, instead of the create-then-export
-    // choreography that costs the two runs back to back.
-    const exportValue = stringFlag(flags, 'export');
-    if (exportValue !== undefined && exportValue !== 'html') {
-        throw new Error('--export must be html');
-    }
-    const exportQualityValue = stringFlag(flags, 'export-quality');
-    if (exportQualityValue !== undefined && !isResponsiveConversionQuality(exportQualityValue)) {
-        throw new Error(`--export-quality must be one of: ${RESPONSIVE_CONVERSION_QUALITIES.join(', ')}`);
-    }
-    if (exportQualityValue !== undefined && exportValue === undefined) {
-        throw new Error('--export-quality requires --export html');
-    }
-    const exportOutValue = stringFlag(flags, 'export-out');
-    if (exportOutValue !== undefined && exportValue === undefined) {
-        throw new Error('--export-out requires --export html');
-    }
-    if (exportValue !== undefined) {
-        if (input.layerdoc !== undefined)
-            throw new Error('--export requires image input');
-        if (output !== 'layerdoc')
-            throw new Error('--export requires --output layerdoc');
-    }
-    const exportHtml = exportValue === 'html'
-        ? { ...(exportQualityValue ? { responsiveQuality: exportQualityValue } : {}) }
+    // Owner-facing `--output html` maps to the existing v1 fused wire shape.
+    // The API remains output=layerdoc + exportHtml; only the CLI vocabulary moves.
+    const exportHtml = fusedHtml
+        ? { ...(responsiveValue ? { responsiveQuality: responsiveValue } : {}) }
         : undefined;
     const conversionInput = input.layerdoc !== undefined
         ? input
         : {
             ...input,
             ...(model ? { model } : {}),
-            ...(responsiveValue ? { responsiveQuality: responsiveValue } : {}),
+            ...(!fusedHtml && responsiveValue ? { responsiveQuality: responsiveValue } : {}),
             ...(exportHtml ? { exportHtml } : {}),
         };
-    const detach = booleanFlag(flags, 'detach');
     const quiet = booleanFlag(flags, 'quiet');
     // Both destinations are made writable BEFORE the conversion is bought. The
     // paid call used to move first, so a missing parent directory lost the
     // settled document, its export, and the journal line that recorded the
     // purchase. See cli-output-paths.ts.
     //
-    // `--out` accepts a directory, and when it names one the export lands beside
-    // the document under a derived name. That is the whole point: one fused call
-    // then carries ONE output path instead of two that disagreed on their type.
-    const outValue = stringFlag(flags, 'out');
-    const outFile = outValue
-        ? await prepareOutputTarget(outValue, () => path.basename(defaultConversionOutputPath(inputPath, output)))
-        : await prepareOutputFile(defaultConversionOutputPath(inputPath, output));
+    // Convert has one directory spelling. Filenames are always derived from the
+    // input, so fused output cannot split a file flag and a directory flag again.
+    const outDirectory = stringFlag(flags, 'out-dir')
+        ? await prepareOutputDirectory(stringFlag(flags, 'out-dir'))
+        : path.dirname(inputPath);
+    const outFile = await prepareOutputFile(path.join(outDirectory, path.basename(defaultConversionOutputPath(inputPath, output))));
     const exportOutFile = exportHtml
-        ? await prepareOutputFile(exportOutValue
-            ?? path.join(path.dirname(outFile), path.basename(defaultConversionOutputPath(inputPath, 'html'))))
+        ? await prepareOutputFile(path.join(outDirectory, path.basename(defaultConversionOutputPath(inputPath, 'html'))))
         : null;
     // Everything below happens BEFORE the paid dispatch, in the workspace the
     // artifacts land in — which is where this command's journal lives, so a
     // second shell reading it is reading the same file.
     const workspace = path.dirname(outFile);
-    const typicalSeconds = CONVERSION_DURATION_HINTS[exportHtml ? 'fused' : 'convert'];
+    // A fused run stays on the fused median even at --model fast: its wall is
+    // anchor-dominated, not extraction-dominated (measured 1m53-5m6 fast).
+    const typicalSeconds = exportHtml
+        ? CONVERSION_DURATION_HINTS.fused
+        : model === 'fast'
+            ? CONVERSION_DURATION_HINTS.convertFast
+            : CONVERSION_DURATION_HINTS.convert;
     const sourceSha256 = createHash('sha256').update(inputBytes).digest('hex');
     journal.note({
         sourceSha256,
@@ -321,52 +578,75 @@ export const runConversionCommand = async (command, flags, journal) => {
         elapsedSeconds: (Date.now() - commandStartedAt) / 1000,
         typicalSeconds,
     });
-    const client = conversionClient();
-    const created = await client.createConversion({
-        ...conversionInput,
-        ...(idempotencyKey ? { idempotencyKey } : {}),
-        waitSeconds: detach ? 0 : 20,
+    const progress = createLongRunningProgress({
+        label: exportHtml ? 'convert (image + responsive HTML)' : 'convert',
+        typicalSeconds,
+        quiet,
+        heartbeat,
+    });
+    progress.brief({
+        request: `convert ${path.basename(inputPath)} -> ${exportHtml
+            ? 'layerdoc + responsive html (one fused purchase)'
+            : requestedOutput}`,
+        paid: input.layerdoc !== undefined
+            ? 'one derived conversion from the LayerDoc on disk'
+            : `1 ${model ?? 'standard'} conversion${exportHtml ? ' + 1 responsive export' : ''}`,
+        done: exportOutFile ? `${outFile} + ${exportOutFile}` : outFile,
+        expectation: {
+            typicalSeconds,
+            basis: `measured median, ${model ?? 'standard'} model${exportHtml ? ', fused' : ''}`,
+        },
+        blocking: true,
     });
+    progress.update({ stage: 'dispatching' });
+    const client = conversionClient();
+    let created;
+    try {
+        created = await client.createConversion({
+            ...conversionInput,
+            ...(idempotencyKey ? { idempotencyKey } : {}),
+            waitSeconds: 20,
+        });
+    }
+    catch (error) {
+        progress.finish('failed', {
+            detail: `the paid dispatch itself failed: ${error instanceof Error ? error.message : String(error)}`,
+        });
+        throw error;
+    }
     journal.note({
         runId: created.id,
         purchased: [created.id, ...(created.export?.conversion_id ? [created.export.conversion_id] : [])],
     });
-    if (detach) {
-        const resumeCommand = `12ui resume ${created.id} --output ${output} --out <file>`;
-        console.log(JSON.stringify({
-            id: created.id,
-            status: created.status,
-            output: created.output,
-            ...(created.export ? { export: created.export } : {}),
-            expiresAt: created.expires_at,
-            // A detached operation is the one case with nothing streaming, so the
-            // response has to say how long it takes and how to collect it.
-            nextAction: nextActionLine({
-                what: 'A conversion',
-                typicalSeconds: CONVERSION_DURATION_HINTS[created.export ? 'fused' : 'convert'],
-                statusCommand: resumeCommand,
-                waitHint: 'which blocks until it finishes and writes the result',
-            }),
-        }, null, 2));
-        return;
-    }
     const exportOperationId = created.export?.conversion_id ?? null;
-    if (!quiet) {
-        process.stderr.write(`12ui convert ${created.id}${exportOperationId ? ` (+ export ${exportOperationId})` : ''}`
-            + ` — ${durationHint(exportOperationId ? 'fused' : 'convert')}\n`
-            + `${nextActionLine({
-                what: 'A conversion',
-                typicalSeconds: CONVERSION_DURATION_HINTS[exportOperationId ? 'fused' : 'convert'],
-                statusCommand: `12ui resume ${created.id} --output ${output} --out <file>`,
-                waitHint: 'or leave this command running, which is what --wait already does by default',
-            })}\n`);
-    }
-    const reporter = createProgressReporter({
-        label: 'convert',
-        quiet,
-        typicalSeconds: CONVERSION_DURATION_HINTS[exportOperationId ? 'fused' : 'convert'],
-        heartbeat,
+    const recovery = {
+        version: 1,
+        createdAt: created.created_at,
+        expiresAt: created.expires_at,
+        conversion: { conversionId: created.id, output, outFile },
+        ...(exportOperationId && exportOutFile
+            ? {
+                linkedExport: {
+                    conversionId: exportOperationId,
+                    output: 'html',
+                    outFile: exportOutFile,
+                },
+            }
+            : {}),
+    };
+    await writeConversionRecovery(recovery).catch((error) => {
+        if (!quiet) {
+            process.stderr.write(`Could not record bare-resume recovery for ${created.id}:`
+                + ` ${error instanceof Error ? error.message : String(error)}.`
+                + ` If interrupted, use \`12ui resume ${created.id} --output ${output} --out ${outFile}\`.\n`);
+        }
     });
+    // Identity is said once, here, and again in the terminal block — never on
+    // ticks. The board's fused capture repeated both ids on 11 of 13 lines.
+    progress.note(`claimed conversion ${created.id}${exportOperationId
+        ? `; its linked responsive export is ${exportOperationId}`
+        : ''}`);
+    reportConversion(progress, created);
     let operation;
     try {
         operation = created.status === 'succeeded'
@@ -374,14 +654,26 @@ export const runConversionCommand = async (command, flags, journal) => {
             : await client.waitForConversion(created.id, {
                 expiresAt: created.expires_at,
                 timeoutMs,
-                onProgress: reporter.onProgress,
+                onProgress: (current) => { reportConversion(progress, current); },
             });
     }
     catch (error) {
         const detail = error instanceof Error ? error.message : String(error);
+        progress.finish('stopped', {
+            detail: `conversion ${created.id} did not settle: ${detail}`,
+            ...(exportOperationId && exportOutFile
+                ? {
+                    artifacts: [
+                        { name: output, state: 'not collected' },
+                        { name: 'responsive html', state: 'unknown — the linked export was not read' },
+                    ],
+                    next: `12ui resume ${created.id} recovers both halves without re-buying`,
+                }
+                : { next: `12ui resume ${created.id} recovers the purchase without re-buying` }),
+        });
         throw new Error(`Conversion ${created.id} failed: ${detail}`, { cause: error });
     }
-    reporter.done(operation);
+    reportConversion(progress, operation);
     // The proof that pairs these exact bytes with the conversion just bought, so
     // a later `12ui branch execute` from the same image attaches it instead of
     // buying viewport 1 of its source page a second time. It goes to the per-user
@@ -399,6 +691,20 @@ export const runConversionCommand = async (command, flags, journal) => {
     journal.note({ artifacts: [outFile] });
     if (!exportOperationId || !exportOutFile) {
         // No export ran, so a `layerdoc` result here IS a document with no page.
+        progress.finish('succeeded', {
+            artifacts: [{
+                    name: output,
+                    state: 'succeeded',
+                    path: outFile,
+                    ...(result.artifactManifest.artifactCount > 0
+                        ? { note: `${result.artifactManifest.artifactCount} assets, manifest ${result.artifactManifest.manifestFile}` }
+                        : {}),
+                }],
+            spend: input.layerdoc !== undefined
+                ? 'one derived conversion purchased'
+                : `1 ${model ?? 'standard'} conversion purchased`,
+            next: `free replay: 12ui resume ${created.id}`,
+        });
         console.log(conversionResultJson(result));
         return;
     }
@@ -406,21 +712,28 @@ export const runConversionCommand = async (command, flags, journal) => {
     // running after the budget must not take it back: the two halves are
     // separate operations and the conversion is the authoritative answer for its
     // own half.
-    const exportReporter = createProgressReporter({
-        label: 'export',
-        quiet,
+    //
+    // The handoff is said in words: the fused purchase's second half has its
+    // own stages and its own percent starting at 0. Rendering it silently into
+    // the same line was the board's 99% -> 29% whiplash.
+    progress.beginScope({
+        name: 'export',
         typicalSeconds: CONVERSION_DURATION_HINTS.export,
-        heartbeat,
+        sentence: 'conversion finished and its document is on disk; now the linked responsive'
+            + ' export (second half of this purchase) — it ran alongside the conversion, its'
+            + ' own percent starts at 0, and it usually finishes well inside the ~4m a'
+            + ' standalone export measures',
     });
     let exportResult = null;
+    let exportOperation = null;
     let exportError = null;
     try {
-        const exportOperation = await client.waitForConversion(exportOperationId, {
+        exportOperation = await client.waitForConversion(exportOperationId, {
             expiresAt: created.expires_at,
             timeoutMs,
-            onProgress: exportReporter.onProgress,
+            onProgress: (current) => { reportConversion(progress, current); },
         });
-        exportReporter.done(exportOperation);
+        reportConversion(progress, exportOperation);
         exportResult = await downloadCompletedConversion({
             client,
             operation: exportOperation,
@@ -440,8 +753,16 @@ export const runConversionCommand = async (command, flags, journal) => {
         : await readConversionStatus(client, exportOperationId);
     const pending = isPendingConversionStatus(exportStatus);
     const collect = `12ui resume ${exportOperationId} --output html --out <file>`;
-    console.log(JSON.stringify({
+    const report = {
         ...result,
+        nextAction: layerDocStateAction({
+            outFile,
+            linkedExport: {
+                id: exportOperationId,
+                status: exportResult ? 'succeeded' : exportStatus,
+                ...(exportResult ? { outFile: exportOutFile } : {}),
+            },
+        }),
         export: exportResult
             ? { ...exportResult, status: 'succeeded' }
             : {
@@ -450,7 +771,56 @@ export const runConversionCommand = async (command, flags, journal) => {
                 status: exportStatus,
                 ...(pending ? { nextAction: collect } : { error: exportError }),
             },
-    }, null, 2));
+    };
+    const layerdocRow = {
+        name: 'layerdoc',
+        state: 'succeeded',
+        path: outFile,
+    };
+    const spendLine = `1 ${model ?? 'standard'} conversion + 1 responsive export purchased`;
+    if (exportResult) {
+        progress.finish('succeeded', {
+            artifacts: [
+                layerdocRow,
+                { name: 'responsive html', state: 'succeeded', path: exportOutFile },
+            ],
+            spend: spendLine,
+            next: `free replay: 12ui resume ${created.id}`,
+        });
+    }
+    else if (pending) {
+        // Terminal for this command, NOT for the purchase: the block must not
+        // look final while a paid format is live server-side.
+        progress.finish('deadline', {
+            detail: 'client wait ended; the paid export continues server-side',
+            artifacts: [
+                layerdocRow,
+                {
+                    name: 'responsive html',
+                    state: `still running server-side (${exportStatus})`,
+                    note: `collect free with: ${collect}`,
+                },
+            ],
+            spend: spendLine,
+            next: `the purchase stays collectable until ${created.expires_at}`,
+        });
+    }
+    else {
+        progress.finish('failed', {
+            detail: `the linked responsive export ${exportOperationId} ${exportStatus}`,
+            artifacts: [
+                layerdocRow,
+                {
+                    name: 'responsive html',
+                    state: exportStatus,
+                    ...(exportError ? { note: exportError } : {}),
+                },
+            ],
+            spend: spendLine,
+            next: `render a fixed page free from the document: 12ui convert ${outFile} --output html_fixed`,
+        });
+    }
+    writeResultWithSummary(report);
     if (!exportResult) {
         throw new Error(pending
             ? `Conversion ${created.id} succeeded and was written to ${outFile}. Its responsive HTML`