@12ui/design 0.2.56 → 0.2.58

package/dist/improve-conversion-stage.js

@@ -1,14 +1,18 @@
 import { copyFile, cp, readFile, stat } from 'node:fs/promises';
 import sharp from 'sharp';
 import { runConversionCommand } from './cli-convert-command.js';
+import { formatDuration } from './cli-progress.js';
+import { createImproveConvertProgress, } from './improve-convert-progress.js';
 import { CliRefusal } from './cli-refusal.js';
 import { prepareOutputDirectory } from './cli-output-paths.js';
-import { fixedImproveHtml, improveConversionIdFromText, improveConvertRetryKey, improveConvertStallCount, improveConvertStallExhausted, improveConvertStallReason, improveConvertStallRetryAllowed, improveErrorText, improveStalled, IMPROVE_CONVERT_STALL_ATTEMPTS, IMPROVE_FRESH_ABANDON_REASON, prepareImproveTargetAttempt, resetImproveTargetAttempt, responsiveFallbackReason, } from './improve-convert-resilience.js';
+import { fixedImproveHtml, improveConversionIdFromText, improveConvertRetryKey, improveConvertStallCount, improveConvertStallHalted, improveErrorText, improveStalled, IMPROVE_FRESH_ABANDON_REASON, prepareImproveTargetAttempt, responsiveFallbackReason, } from './improve-convert-resilience.js';
+import { createConcurrencyLimiter } from './bounded-concurrency.js';
 import { improveFreshConversionKey, noteImproveConversionAttemptId, openImproveConversionAttempt, settleImproveConversionAttempt, startImproveConversionAttempt, } from './improve-conversion-attempts.js';
-import { canvasOfDoc } from './improve-layerdoc-diff.js';
-import { abandonImproveConversion, abandonImproveConversions, noteAbandonedAttempts, withoutImproveStages, } from './improve-reset.js';
-import { improveSha256, noteImproveStage, } from './improve-stage-shared.js';
-import { readImproveRecord, writeImproveRecord } from './improve-workspace.js';
+import { canvasOfDoc } from './improve-core/index.js';
+import { trackImproveDurableWrite } from './improve-stop-handler.js';
+import { abandonImproveConversion, noteAbandonedAttempts, withoutImproveStages, } from './improve-reset.js';
+import { improveSha256, noteImproveStage, noteImproveStageDispatched, } from './improve-stage-shared.js';
+import { improvePagePaths, readImproveRecord, writeImproveRecord, } from './improve-workspace.js';
 export const runImproveConversion = async (args) => {
     const artifacts = [];
     const purchaseIds = [];
@@ -18,25 +22,33 @@ export const runImproveConversion = async (args) => {
             artifacts.push(...(facts.artifacts ?? []));
             purchaseIds.push(...(facts.purchased ?? []));
             if (facts.runId) {
-                if (!runIds.includes(facts.runId))
+                if (!runIds.includes(facts.runId)) {
                     args.onConversionId?.(facts.runId);
+                    args.progress?.noteConversionId(facts.runId);
+                }
                 runIds.push(facts.runId);
             }
             args.journal?.note(facts);
         },
-        heartbeat: (progress) => { args.journal?.heartbeat(progress); },
+        heartbeat: (progress) => {
+            args.journal?.heartbeat(progress);
+            args.progress?.heartbeat(progress);
+        },
     };
     const flags = {
+        ...args.passthrough,
         output: args.output,
         ...(args.model ? { model: args.model } : {}),
         ...(args.responsiveQuality ? { 'responsive-quality': args.responsiveQuality } : {}),
-        ...(args.timeoutMs === undefined ? {} : { 'timeout-ms': String(args.timeoutMs) }),
         'out-dir': args.outDir,
         'idempotency-key': args.key,
         quiet: true,
     };
     try {
-        await args.runner(['convert', args.input], flags, collector, { writeResult: () => undefined });
+        await args.runner(['convert', args.input], flags, collector, {
+            writeResult: () => undefined,
+            ...(args.stallTimeoutMs === undefined ? {} : { stallTimeoutMs: args.stallTimeoutMs }),
+        });
     }
     catch (error) {
         throw new ImproveConvertAttemptError(error, {
@@ -71,7 +83,7 @@ const recordFreshConversion = async (args) => {
         reason: IMPROVE_FRESH_ABANDON_REASON,
         warn: args.dependencies.warn ?? ((line) => { console.warn(line); }),
     });
-    const record = withoutImproveStages(abandoned.record, ['convert', 'plan']);
+    const record = withoutImproveStages(abandoned.record, ['convert', 'plan', 'site']);
     await writeImproveRecord(args.options.paths.record, record);
     return record;
 };
@@ -129,14 +141,14 @@ export const runImproveConvertStage = async (args) => {
         throw new Error('Improve has no design image to convert');
     const targetIdentity = improveSha256(Buffer.from(`${inputSha}:${args.record.conversionModel}:${args.options.responsiveQuality}`)).slice(0, 32);
     const baseKey = `improve-target:v2:${targetIdentity}`;
-    // How many conversions of this winner the kit has already bought and
-    // abandoned to a stall, and which of them to wait on now. A resume
-    // re-attaches to the NEWEST one — it is bought, it is still running, and it
-    // is the only way to get anything back for it — instead of rebuilding the
-    // base key and waiting out the whole bound on the first, oldest, already
-    // declared-dead conversion.
-    let bought = args.options.fresh ? 0 : improveConvertStallCount(recordBeforeConvert);
-    let index = Math.max(1, bought);
+    // How many conversions of this winner a PRE-F19 kit bought and abandoned to a
+    // stall, and which of them to wait on now. A resume re-attaches to the NEWEST
+    // one — it is bought, it is still running, and it is the only way to get
+    // anything back for it — instead of rebuilding the base key and waiting out
+    // the whole bound on the first, oldest conversion. Nothing adds to this count
+    // any more; a stall no longer abandons anything.
+    const bought = args.options.fresh ? 0 : improveConvertStallCount(recordBeforeConvert);
+    const index = Math.max(1, bought);
     // WHICH CONVERSION THIS INVOCATION IS ABOUT TO WAIT ON. The attempt ledger
     // decides, because it holds the exact key: a `--fresh` or retry attempt that
     // was stopped mid-flight is reachable only through the key it was dispatched
@@ -147,13 +159,15 @@ export const runImproveConvertStage = async (args) => {
     // kits written before the ledger.
     //
     // Only an attempt minted for THIS winner counts: every recorded key is the
-    // base key plus a suffix, so the prefix is what says the conversion behind it
-    // is of the design this run is converting. A redraw or a re-pick already
-    // closes its attempts (`abandonImproveConversions`); this is the second lock
-    // on that door, because re-attaching to a conversion of a discarded design
-    // would deliver the wrong page and read as a replay.
+    // base key itself or the base key plus a suffix, so the prefix is what says
+    // the conversion behind it is of the design this run is converting. A redraw
+    // or a re-pick already closes its attempts (`abandonImproveConversions`);
+    // this is the second lock on that door, because re-attaching to a conversion
+    // of a discarded design would deliver the wrong page and read as a replay.
     const open = args.options.fresh ? undefined : openImproveConversionAttempt(recordBeforeConvert);
-    const resumed = open?.key.startsWith(`${baseKey}:`) ? open : undefined;
+    const resumed = open && (open.key === baseKey || open.key.startsWith(`${baseKey}:`))
+        ? open
+        : undefined;
     const nonce = args.freshConversionNonce;
     if (args.options.fresh && !nonce) {
         throw new Error('improve --fresh needs a per-invocation conversion nonce, so the conversion it dispatches'
@@ -162,9 +176,9 @@ export const runImproveConvertStage = async (args) => {
     const key = args.options.fresh && nonce
         ? improveFreshConversionKey(baseKey, nonce)
         : resumed?.key ?? (index === 1 ? baseKey : improveConvertRetryKey(baseKey, index));
-    // The transaction is taken ONCE, outside the retry: a second
-    // `prepareImproveTargetAttempt` while the first backup exists would delete
-    // the previous good target instead of preserving it.
+    // The transaction is taken ONCE: a second `prepareImproveTargetAttempt`
+    // while the first backup exists would delete the previous good target
+    // instead of preserving it.
     const transaction = await prepareImproveTargetAttempt(args.options.paths.targetDir);
     const warn = args.dependencies.warn ?? ((line) => { console.warn(line); });
     try {
@@ -174,6 +188,14 @@ export const runImproveConvertStage = async (args) => {
         // the ordinary base-key path writes nothing extra. The writes are chained
         // and drained before the stage writes the record itself: a stamp landing
         // after the settled record would write a record that has no convert block.
+        //
+        // The id arrives on a callback that cannot be awaited, so the write is the
+        // one durable fact of this stage that is NOT on disk before it is needed.
+        // Both ends of the stage therefore drain it — the ordinary end below, and
+        // the signal path, which is why each link is also handed to
+        // `trackImproveDurableWrite`. A SIGTERM used to exit with this write still
+        // in flight, leaving a kit that had paid for a conversion, was still being
+        // billed for it, and could not name it.
         let pendingLedgerWrite = Promise.resolve();
         const rememberConversionId = (attemptKey, id) => {
             const noted = noteImproveConversionAttemptId(recordBeforeConvert, {
@@ -189,165 +211,171 @@ export const runImproveConvertStage = async (args) => {
                 warn(`[ledger] convert: could not record conversion ${id} against its key:`
                     + ` ${improveErrorText(error)}`);
             });
+            trackImproveDurableWrite(pendingLedgerWrite);
         };
-        const attemptConversion = async (attemptKey) => runImproveConversion({
-            input,
-            outDir: args.options.paths.targetDir,
-            output: 'html',
-            model: args.record.conversionModel,
-            responsiveQuality: args.options.responsiveQuality,
-            timeoutMs: args.options.convertStallSeconds * 1_000,
-            key: attemptKey,
-            runner: args.dependencies.runConvert ?? runConversionCommand,
-            journal: args.dependencies.journal,
-            onConversionId: (id) => { rememberConversionId(attemptKey, id); },
-        }).catch(async (error) => {
-            const attempt = error instanceof ImproveConvertAttemptError
-                ? error.attempt
-                : { artifacts: [], purchaseIds: [], runIds: [] };
-            const warning = responsiveFallbackReason(error);
-            const sourceConversionId = attempt.runIds[0]
-                ?? improveConversionIdFromText(improveErrorText(error));
-            const layerDocPresent = (await stat(args.options.paths.targetLayerDoc).catch(() => undefined))?.isFile();
-            const assetsPresent = (await stat(`${args.options.paths.targetLayerDoc}.assets`).catch(() => undefined))?.isDirectory();
-            if (!warning || !sourceConversionId || !layerDocPresent || !assetsPresent)
-                throw error;
-            (args.dependencies.warn ?? console.warn)(`Responsive HTML was unavailable; deriving fixed-layout HTML free from ${sourceConversionId}`);
-            // The derivation is free, not unbounded. Passing no timeout dropped it
-            // through to waitForOperation's twenty-minute default while the docs
-            // promised `--convert-stall-seconds` bounds the conversion wait, so a
-            // wedged derivation hung the run for twenty minutes with no STALL.md —
-            // the pipedrive shape, on the one path the reader was told was bounded.
-            const fixed = await runImproveConversion({
-                input: sourceConversionId,
+        const bound = args.options.convertStallSeconds;
+        // Progress goes where every other 12ui progress stream goes — stderr, via
+        // the same channel the fallback line uses — so stdout stays the record.
+        const tick = args.dependencies.warn ?? ((line) => { console.warn(line); });
+        const attemptConversion = async (attemptKey) => {
+            // The wait a lane actually sits through, ticked once a minute so the
+            // terminal never goes silent (F8). The client applies `bound` only to a
+            // stretch with no newly observed live stage or active lane; a healthy
+            // tall conversion remains attached to this exact idempotent purchase.
+            const startedAt = Date.now();
+            const progress = createImproveConvertProgress({
+                label: 'responsive export',
+                boundSeconds: bound,
+                write: tick,
+            });
+            return runImproveConversion({
+                input,
                 outDir: args.options.paths.targetDir,
-                output: 'html_fixed',
-                timeoutMs: args.options.convertStallSeconds * 1_000,
-                key: `improve-fixed:v1:${sourceConversionId}`,
+                output: 'html',
+                model: args.record.conversionModel,
+                responsiveQuality: args.options.responsiveQuality,
+                stallTimeoutMs: args.options.convertStallSeconds * 1_000,
+                key: attemptKey,
+                passthrough: args.options.passthrough,
                 runner: args.dependencies.runConvert ?? runConversionCommand,
                 journal: args.dependencies.journal,
+                onConversionId: (id) => { rememberConversionId(attemptKey, id); },
+                progress,
+            }).catch(async (error) => {
+                const attempt = error instanceof ImproveConvertAttemptError
+                    ? error.attempt
+                    : { artifacts: [], purchaseIds: [], runIds: [] };
+                // The stage the SERVICE declared decides the sentence, not the shape of
+                // the error text (F34).
+                const fallbackReason = responsiveFallbackReason(error, {
+                    ...(progress.serviceStage() ? { serviceStage: progress.serviceStage() } : {}),
+                });
+                const sourceConversionId = attempt.runIds[0]
+                    ?? improveConversionIdFromText(improveErrorText(error));
+                const layerDocPresent = (await stat(args.options.paths.targetLayerDoc).catch(() => undefined))?.isFile();
+                const assetsPresent = (await stat(`${args.options.paths.targetLayerDoc}.assets`).catch(() => undefined))?.isDirectory();
+                if (!fallbackReason || !sourceConversionId || !layerDocPresent || !assetsPresent)
+                    throw error;
+                const waitedSeconds = Math.round(progress.waitedSeconds() ?? (Date.now() - startedAt) / 1_000);
+                (args.dependencies.warn ?? console.warn)(`${fallbackReason.warning} After ${formatDuration(waitedSeconds)}`
+                    + ` (bound ${formatDuration(bound)});`
+                    + ` deriving fixed-layout HTML free from ${sourceConversionId}`);
+                // The derivation is free, but it still stops after the same period
+                // without a newly observed live service fact. It therefore cannot
+                // quietly use the conversion client's generic twenty-minute wall.
+                const fixed = await runImproveConversion({
+                    input: sourceConversionId,
+                    outDir: args.options.paths.targetDir,
+                    output: 'html_fixed',
+                    stallTimeoutMs: args.options.convertStallSeconds * 1_000,
+                    key: `improve-fixed:v1:${sourceConversionId}`,
+                    passthrough: args.options.passthrough,
+                    runner: args.dependencies.runConvert ?? runConversionCommand,
+                    journal: args.dependencies.journal,
+                    progress: createImproveConvertProgress({
+                        label: 'fixed-layout derivation',
+                        boundSeconds: bound,
+                        write: tick,
+                    }),
+                });
+                const fixedOutput = await fixedImproveHtml(args.options.paths.targetDir);
+                args.dependencies.journal?.note({ degradations: ['improve_fixed_layout_fallback'] });
+                return {
+                    artifacts: [...new Set([
+                            ...attempt.artifacts,
+                            ...fixed.artifacts,
+                            args.options.paths.targetLayerDoc,
+                            `${args.options.paths.targetLayerDoc}.assets`,
+                            fixedOutput.html,
+                            fixedOutput.assets,
+                        ])],
+                    purchaseIds: [...new Set([...attempt.purchaseIds, ...fixed.purchaseIds])],
+                    runIds: [...new Set([sourceConversionId, ...attempt.runIds, ...fixed.runIds])],
+                    fallback: {
+                        html: fixedOutput.html,
+                        warning: fallbackReason.warning,
+                        outcome: fallbackReason.outcome,
+                        waitedSeconds,
+                    },
+                };
             });
-            const fixedOutput = await fixedImproveHtml(args.options.paths.targetDir);
-            args.dependencies.journal?.note({ degradations: ['improve_fixed_layout_fallback'] });
-            return {
-                artifacts: [...new Set([
-                        ...attempt.artifacts,
-                        ...fixed.artifacts,
-                        args.options.paths.targetLayerDoc,
-                        `${args.options.paths.targetLayerDoc}.assets`,
-                        fixedOutput.html,
-                        fixedOutput.assets,
-                    ])],
-                purchaseIds: [...new Set([...attempt.purchaseIds, ...fixed.purchaseIds])],
-                runIds: [...new Set([sourceConversionId, ...attempt.runIds, ...fixed.runIds])],
-                fallback: { html: fixedOutput.html, warning },
-            };
-        });
-        // ONE retry, and only for the stall with nothing to derive: the wait ended,
-        // no LayerDoc reached disk, so no fixed-layout fallback is possible and the
-        // stage has nothing at all. The guard is the LayerDoc on disk rather than
-        // the error text — if the conversion delivered, re-dispatching is pure
-        // waste of a second paid conversion.
+        };
+        // ONE DISPATCH PER INVOCATION, ALWAYS (F19, CLAUDE.md item 3).
         //
-        // What is actually guaranteed, stated exactly: the default bound is twice
-        // the model's typical wall (see improveConvertStallDefaultSeconds), and an
-        // explicit --convert-stall-seconds is refused below one typical wall. So
-        // the retry sits outside the median by construction and inside no measured
-        // healthy population — nobody has measured P(convert half > bound | healthy)
-        // on the fused population, so it is a bound, not a proof.
+        // A stall used to buy a second parent conversion of the same winner. The
+        // justification was that the bound sits outside the model's typical window,
+        // so it could not fire on healthy work — a bound, never a measurement. What
+        // it produced on pipedrive was one operator command, two parent conversions,
+        // four conversion ids, and an abandoned-conversion list the CLI wrote
+        // against itself while the first conversion kept running and kept billing.
+        //
+        // So there is no retry, no abandonment, and no second key. A stall that left
+        // a LayerDoc derives the free fixed-layout fallback from the conversion that
+        // is already running (inside `attemptConversion`); a stall that left nothing
+        // ends the invocation with the conversion still open in the ledger, so
+        // `plan/STALL.md` and `--from convert` both re-attach to it.
         //
-        // The budget belongs to the KIT, not to this process. Both the retry's
-        // identity and its count come from the durable ledgers, so a resume
-        // attaches to the conversion the retry actually dispatched instead of to
-        // the first, known-stalled one, and a kit that has already retried refuses
-        // to buy a third rather than dispatching one per resume forever.
-        let converted;
-        let convertedKey;
-        const retries = bought === 0 && improveConvertStallRetryAllowed(args.record.conversionModel)
-            ? IMPROVE_CONVERT_STALL_ATTEMPTS - 1
-            : 0;
         // Why an attempt is being dispatched, which is what the ledger records it
         // as. A resume of a recorded attempt re-declares the reason it was opened
-        // with and dedupes to a no-op; the plain base key is not recorded at all.
-        const dispatchReason = (attempt) => {
-            if (attempt > 0)
-                return 'stall-retry';
-            if (args.options.fresh)
-                return 'fresh';
-            return resumed?.reason ?? (index === 1 ? undefined : 'stall-retry');
-        };
-        for (let attempt = 0; attempt <= retries; attempt += 1) {
-            const attemptKey = attempt === 0 ? key : improveConvertRetryKey(key, index);
-            // BEFORE THE DISPATCH, because a conversion nothing wrote down before it
-            // started is a conversion a stop cannot leave resumable. `--fresh` also
-            // walks away here from whatever attempt this kit still had open: it is
-            // buying a replacement for it, and an attempt left open would send the
-            // next resume back to the run this one supersedes.
-            const reason = dispatchReason(attempt);
-            if (reason) {
-                const started = startImproveConversionAttempt(recordBeforeConvert, {
-                    key: attemptKey,
-                    reason,
-                    ...(args.options.fresh ? { supersedes: IMPROVE_FRESH_ABANDON_REASON } : {}),
-                });
-                if (started.record !== recordBeforeConvert) {
-                    recordBeforeConvert = noteAbandonedAttempts({
-                        record: started.record,
-                        attempts: started.superseded,
-                        reason: IMPROVE_FRESH_ABANDON_REASON,
-                        warn,
-                    });
-                    await writeImproveRecord(args.options.paths.record, recordBeforeConvert);
-                }
-            }
-            try {
-                converted = await attemptConversion(attemptKey);
-                convertedKey = attemptKey;
-                await pendingLedgerWrite;
-                break;
-            }
-            catch (error) {
-                await pendingLedgerWrite;
-                const layerDocPresent = (await stat(args.options.paths.targetLayerDoc)
-                    .catch(() => undefined))?.isFile();
-                if (layerDocPresent || !improveStalled(error))
-                    throw error;
-                // The stalled attempt knows its own id even when the record does not:
-                // nothing settled, so `recordedImproveConversionId` has nowhere to look.
-                const stalledId = (error instanceof ImproveConvertAttemptError
-                    ? error.attempt.runIds[0]
-                    : undefined) ?? improveConversionIdFromText(improveErrorText(error));
-                // The attempt ledger closes with the conversion, by key: the run this
-                // key reaches is dead, and a later resume must not rebuild it.
-                const abandoned = await abandonImproveConversions({
-                    record: recordBeforeConvert,
-                    reason: improveConvertStallReason(args.options.convertStallSeconds),
-                    ...(stalledId ? { id: stalledId } : {}),
-                    warn,
-                });
-                recordBeforeConvert = abandoned.record;
-                await writeImproveRecord(args.options.paths.record, recordBeforeConvert);
-                // The ledger is the source of truth, and it cannot record a stall whose
-                // id nothing reported. Taking the larger of the two keeps the next key
-                // distinct in that case without ever going backwards.
-                bought = Math.max(bought + 1, improveConvertStallCount(recordBeforeConvert));
-                index = bought + 1;
-                if (attempt >= retries) {
-                    throw improveConvertStallExhausted({
-                        seconds: args.options.convertStallSeconds,
-                        bought,
-                        model: args.record.conversionModel,
-                        cause: error,
-                    });
-                }
-                args.dependencies.journal?.note({ degradations: ['improve_convert_stall_retry'] });
-                warn(`[stall] convert: nothing materialized in ${args.options.convertStallSeconds}s;`
-                    + ' dispatching one fresh conversion of the same winner');
-                await resetImproveTargetAttempt(args.options.paths.targetDir);
-            }
+        // with and dedupes to a no-op.
+        const reason = args.options.fresh
+            ? 'fresh'
+            : resumed?.reason ?? (index === 1 ? 'primary' : 'stall-retry');
+        // BEFORE THE DISPATCH, because a conversion nothing wrote down before it
+        // started is a conversion a stop cannot leave resumable — and because a
+        // price nobody wrote down is a paid call with no receipt. `--fresh` also
+        // walks away here from whatever attempt this kit still had open: it is
+        // buying a replacement for it, and an attempt left open would send the
+        // next resume back to the run this one supersedes.
+        const started = startImproveConversionAttempt(recordBeforeConvert, {
+            key,
+            reason,
+            priceCeilingUsd: args.price,
+            ...(args.options.fresh ? { supersedes: IMPROVE_FRESH_ABANDON_REASON } : {}),
+        });
+        if (started.record !== recordBeforeConvert) {
+            recordBeforeConvert = noteAbandonedAttempts({
+                record: started.record,
+                attempts: started.superseded,
+                reason: IMPROVE_FRESH_ABANDON_REASON,
+                warn,
+            });
+        }
+        // The stage's own priced entry, written now rather than on settlement: a
+        // kit that stalled had no `convert` entry at all, so its recorded ceiling
+        // was the draft's and a lane converting a page twice could not say so.
+        recordBeforeConvert = noteImproveStageDispatched({
+            record: recordBeforeConvert, stage: 'convert', priceCeilingUsd: args.price,
+        });
+        await writeImproveRecord(args.options.paths.record, recordBeforeConvert);
+        let converted;
+        try {
+            converted = await attemptConversion(key);
+            await pendingLedgerWrite;
         }
-        if (!converted)
-            throw new Error('Improve conversion ended without a result');
+        catch (error) {
+            await pendingLedgerWrite;
+            if (!improveStalled(error))
+                throw error;
+            // The stalled attempt knows its own id even when the record does not:
+            // nothing settled, so `recordedImproveConversionId` has nowhere to look.
+            // It stays OPEN in the ledger — it is running, it is paid for, and the
+            // resume this error prints is the only way to get anything back for it.
+            const stalledId = (error instanceof ImproveConvertAttemptError
+                ? error.attempt.runIds[0]
+                : undefined) ?? improveConversionIdFromText(improveErrorText(error));
+            warn(`[stall] convert: nothing settled in ${args.options.convertStallSeconds}s;`
+                + `${stalledId ? ` conversion ${stalledId}` : ' the conversion'} is still running,`
+                + ' and improve is not buying another');
+            throw improveConvertStallHalted({
+                seconds: args.options.convertStallSeconds,
+                ...(stalledId ? { conversionId: stalledId } : {}),
+                input: args.record.input.value,
+                runDir: args.options.paths.runDir,
+                cause: error,
+            });
+        }
+        const convertedKey = key;
         const html = converted.fallback ? converted.fallback.html : args.options.paths.targetHtml;
         for (const expected of [args.options.paths.targetLayerDoc, html]) {
             if (!(await stat(expected).catch(() => undefined))?.isFile()) {
@@ -361,11 +389,28 @@ export const runImproveConvertStage = async (args) => {
                 html,
                 layout: converted.fallback ? 'fixed' : 'responsive',
                 ...(converted.runIds[0] ? { sourceConversionId: converted.runIds[0] } : {}),
-                ...(converted.fallback ? { responsiveWarning: converted.fallback.warning } : {}),
+                ...(converted.fallback
+                    ? {
+                        responsiveWarning: converted.fallback.warning,
+                        responsiveOutcome: converted.fallback.outcome,
+                    }
+                    : {}),
+                // What the responsive half did before the derivation replaced it, kept
+                // durably so `plan/STALL.md`, the README and the run summary all read
+                // one account of the same wait rather than three (F8).
+                ...(converted.fallback && converted.runIds[0]
+                    ? {
+                        responsiveStall: {
+                            conversionId: converted.runIds[0],
+                            waitedSeconds: converted.fallback.waitedSeconds,
+                            boundSeconds: bound,
+                        },
+                    }
+                    : {}),
                 artifacts: converted.artifacts,
                 purchaseIds: converted.purchaseIds,
             },
-        }, { ...(convertedKey === undefined ? {} : { key: convertedKey }) });
+        }, { key: convertedKey });
         record = await noteImproveStage({
             record, stage: 'convert', priceCeilingUsd: args.price, replayed: false, write: false,
         });
@@ -378,4 +423,167 @@ export const runImproveConvertStage = async (args) => {
         throw error;
     }
 };
+const fileExists = async (file) => ((await stat(file).catch(() => undefined))?.isFile() ?? false);
+const directoryExists = async (directory) => ((await stat(directory).catch(() => undefined))?.isDirectory() ?? false);
+const mergeConvertAttempts = (...attempts) => ({
+    artifacts: [...new Set(attempts.flatMap((attempt) => attempt.artifacts))],
+    purchaseIds: [...new Set(attempts.flatMap((attempt) => attempt.purchaseIds))],
+    runIds: [...new Set(attempts.flatMap((attempt) => attempt.runIds))],
+});
+const convertImproveTarget = async (args) => {
+    const transaction = await prepareImproveTargetAttempt(args.outDir);
+    try {
+        let attempt;
+        let responsiveWarning;
+        let responsiveOutcome;
+        try {
+            attempt = await runImproveConversion({
+                input: args.input,
+                outDir: args.outDir,
+                output: 'html',
+                model: args.model,
+                responsiveQuality: args.responsiveQuality,
+                stallTimeoutMs: args.stallTimeoutMs,
+                key: args.key,
+                passthrough: args.passthrough,
+                runner: args.runner,
+                journal: args.journal,
+            });
+        }
+        catch (error) {
+            const layerDocPresent = await fileExists(args.targetLayerDoc);
+            const fallback = responsiveFallbackReason(error);
+            if (!fallback || !layerDocPresent)
+                throw error;
+            responsiveWarning = fallback.warning;
+            responsiveOutcome = fallback.outcome;
+            attempt = error instanceof ImproveConvertAttemptError
+                ? error.attempt
+                : { artifacts: [], purchaseIds: [], runIds: [] };
+            const conversionId = attempt.runIds[0]
+                ?? improveConversionIdFromText(improveErrorText(error));
+            if (conversionId) {
+                attempt = mergeConvertAttempts(attempt, {
+                    artifacts: [], purchaseIds: [], runIds: [conversionId],
+                });
+            }
+        }
+        if (!(await fileExists(args.targetLayerDoc))) {
+            throw new Error(`Improve conversion completed without ${args.targetLayerDoc}`);
+        }
+        const responsiveHtmlPresent = await fileExists(args.targetHtml);
+        if (!responsiveHtmlPresent && !responsiveWarning) {
+            responsiveWarning = 'Responsive HTML was not generated; the LayerDoc remains available for planning.';
+        }
+        let html = responsiveHtmlPresent ? args.targetHtml : '';
+        let layout = responsiveHtmlPresent ? 'responsive' : 'document';
+        const sourceConversionId = attempt.runIds[0];
+        if (!responsiveHtmlPresent && sourceConversionId) {
+            (args.warn ?? console.warn)(`Responsive HTML was unavailable; deriving fixed-layout HTML free from ${sourceConversionId}`);
+            try {
+                const fixedAttempt = await runImproveConversion({
+                    input: sourceConversionId,
+                    outDir: args.outDir,
+                    output: 'html_fixed',
+                    stallTimeoutMs: args.stallTimeoutMs,
+                    key: `improve-fixed:v1:${sourceConversionId}`,
+                    passthrough: args.passthrough,
+                    runner: args.runner,
+                    journal: args.journal,
+                });
+                attempt = mergeConvertAttempts(attempt, fixedAttempt);
+                const fixed = await fixedImproveHtml(args.outDir);
+                attempt = mergeConvertAttempts(attempt, {
+                    artifacts: [args.targetLayerDoc, fixed.html, fixed.assets],
+                    purchaseIds: [],
+                    runIds: [],
+                });
+                html = fixed.html;
+                layout = 'fixed';
+                args.journal?.note({ degradations: ['improve_fixed_layout_fallback'] });
+            }
+            catch (error) {
+                if (error instanceof ImproveConvertAttemptError) {
+                    attempt = mergeConvertAttempts(attempt, error.attempt);
+                }
+                (args.warn ?? console.warn)(`Fixed-layout derivation was unavailable; retaining the LayerDoc only: ${improveErrorText(error)}`);
+            }
+        }
+        if (!responsiveHtmlPresent) {
+            const layerDocAssets = `${args.targetLayerDoc}.assets`;
+            attempt = mergeConvertAttempts(attempt, {
+                artifacts: [
+                    args.targetLayerDoc,
+                    ...((await directoryExists(layerDocAssets)) ? [layerDocAssets] : []),
+                ],
+                purchaseIds: [],
+                runIds: [],
+            });
+            args.journal?.note({ degradations: ['improve_responsive_html_unavailable'] });
+        }
+        const converted = {
+            layerDoc: args.targetLayerDoc,
+            html,
+            layout,
+            ...(sourceConversionId ? { sourceConversionId } : {}),
+            ...(responsiveWarning ? { responsiveWarning } : {}),
+            ...(responsiveOutcome ? { responsiveOutcome } : {}),
+            artifacts: attempt.artifacts,
+            purchaseIds: attempt.purchaseIds,
+        };
+        await transaction.commit();
+        return converted;
+    }
+    catch (error) {
+        await transaction.restore();
+        throw error;
+    }
+};
+export const runImproveSiteConvertStage = async (args) => {
+    const complete = !args.options.fresh
+        && Boolean(args.record.convert)
+        && args.record.pages.length > 0
+        && args.record.pages.every((page) => page.branch?.status === 'failed' || page.convert);
+    if (complete)
+        return noteImproveStage({
+            record: args.record, stage: 'convert', priceCeilingUsd: args.price, replayed: true, write: true,
+        });
+    let record = args.record.convert && !args.options.fresh
+        ? args.record
+        : await runImproveConvertStage(args);
+    const limiter = createConcurrencyLimiter(args.options.pageConcurrency);
+    const convertedPages = await Promise.all(record.pages.map((page) => limiter(async () => {
+        if (page.branch?.status === 'failed')
+            return page;
+        if (page.convert)
+            return page;
+        if (page.branch?.status !== 'succeeded' || !page.branch.sha256 || !page.branch.imagePath) {
+            throw new Error(`Cannot convert site page ${page.id} before branch succeeds`);
+        }
+        const paths = improvePagePaths(record.runDir, page.id);
+        const targetIdentity = improveSha256(Buffer.from(`${page.branch.sha256}:${record.conversionModel}:${args.options.responsiveQuality}`)).slice(0, 32);
+        const baseKey = `improve-page-target:v2:${targetIdentity}`;
+        const key = args.options.fresh
+            ? `${baseKey}:fresh:${args.freshConversionNonce}`
+            : baseKey;
+        const converted = await convertImproveTarget({
+            input: page.branch.imagePath,
+            outDir: paths.targetDir,
+            targetLayerDoc: paths.targetLayerDoc,
+            targetHtml: paths.targetHtml,
+            model: record.conversionModel,
+            responsiveQuality: args.options.responsiveQuality,
+            key,
+            stallTimeoutMs: args.options.convertStallSeconds * 1_000,
+            passthrough: args.options.passthrough,
+            runner: args.dependencies.runConvert ?? runConversionCommand,
+            journal: args.dependencies.journal,
+            warn: args.dependencies.warn,
+        });
+        return { ...page, convert: converted };
+    })));
+    record = { ...record, pages: convertedPages };
+    await writeImproveRecord(args.options.paths.record, record);
+    return record;
+};
 //# sourceMappingURL=improve-conversion-stage.js.map