@gobing-ai/knowledge-kit 0.0.34 → 0.0.36

package/plugins/kk/scripts/daily-stages.ts

@@ -77,8 +77,10 @@ import {
     failWith,
     firstArtifact,
     firstPostPath,
+    firstTargetUrl,
     isFile,
     kk,
+    kkCaptured,
     metadataOf,
     NESTED_SPUR_UNSET,
     PII_FINDING_CATEGORY,
@@ -107,6 +109,7 @@ import {
     XHS_BODY_CAP,
     XHS_FORMAT,
     XHS_MAX_CARDS,
+    type XhsCard,
     xhsPlan,
 } from './kk-workflow-stages.ts';
 
@@ -121,6 +124,8 @@ export function dailyQcContent(args: string[]): void {
         minUrgency = '',
         minImpact = '',
         minEpisodeItems = '',
+        minMinutes = '',
+        vdriver = '',
     ] = args;
     const candidates = join(workDir, '21-plan', `${runDate}_04_quality-control-content_candidates.json`);
     const annotated = join(workDir, '21-plan', `${runDate}_04_quality-control-content_annotated.json`);
@@ -155,6 +160,7 @@ export function dailyQcContent(args: string[]): void {
                 },
             },
         );
+        applyFloorGate(candidates, workDir, runDate, minMinutes, vdriver);
     });
     // Topic boundary (task 0189 R2) runs on every invocation — re-applying to already-filtered
     // candidates is a no-op, so cached reruns stay idempotent while a crash between the candidates
@@ -163,25 +169,41 @@ export function dailyQcContent(args: string[]): void {
     const boundaryDocs = metadataOf(readJson(candidates)).docs;
     if (!Array.isArray(boundaryDocs)) return;
     const { kept, excluded } = applyTopicBoundary(boundaryDocs, runDate, readTopicBoundary());
-    if (excluded.length === 0) return;
-    sted('write', exclusions, () =>
-        writeJsonText(exclusions, {
-            version: 1,
-            runDate,
-            excluded,
-            kept: kept.map((doc) => (doc as { id: string }).id),
-        }),
-    );
-    const content = requireJson(candidates, 'topic-boundary');
-    const meta = content.metadata;
-    if (meta === null || typeof meta !== 'object') {
-        failWith(1, 'topic-boundary: candidates content carries no metadata object');
+    // A no-op boundary must not rewrite the file: the idempotent-rerun test compares bytes.
+    if (excluded.length > 0) {
+        sted('write', exclusions, () =>
+            writeJsonText(exclusions, {
+                version: 1,
+                runDate,
+                excluded,
+                kept: kept.map((doc) => (doc as { id: string }).id),
+            }),
+        );
+        const content = requireJson(candidates, 'topic-boundary');
+        const meta = content.metadata;
+        if (meta === null || typeof meta !== 'object') {
+            failWith(1, 'topic-boundary: candidates content carries no metadata object');
+        }
+        (meta as Record<string, unknown>).docs = kept;
+        sted('write', candidates, () => writeJsonText(candidates, content));
+        console.log(
+            `topic-boundary: excluded ${excluded.length} item(s): ${excluded.map((entry) => `${entry.id}(${entry.rule})`).join(', ')}`,
+        );
     }
-    (meta as Record<string, unknown>).docs = kept;
-    sted('write', candidates, () => writeJsonText(candidates, content));
-    console.log(
-        `topic-boundary: excluded ${excluded.length} item(s): ${excluded.map((entry) => `${entry.id}(${entry.rule})`).join(', ')}`,
-    );
+    // Title dedup before plan-translate / script-write. dailyArticle repeats this on plan.json, but
+    // that runs in parallel with script-write: an id dropped after the script plan is authored is
+    // `unknown-id`, the whole plan is rejected, and generate then sees a template with fewer sections.
+    const currentDocs = excluded.length > 0 ? kept : boundaryDocs;
+    const { kept: deduped, dropped } = dedupPlanByTitle(currentDocs as Array<{ id?: unknown; title?: unknown }>);
+    if (dropped.length === 0) return;
+    const dedupedContent = requireJson(candidates, 'qc-dedup');
+    const dedupedMeta = dedupedContent.metadata;
+    if (dedupedMeta === null || typeof dedupedMeta !== 'object') {
+        failWith(1, 'qc-dedup: candidates content carries no metadata object');
+    }
+    (dedupedMeta as Record<string, unknown>).docs = deduped;
+    sted('write', candidates, () => writeJsonText(candidates, dedupedContent));
+    console.error(`qc: dropped ${dropped.length} near-duplicate candidate(s): ${dropped.join(', ')}`);
 }
 
 /**
@@ -189,6 +211,79 @@ export function dailyQcContent(args: string[]): void {
  * episode-plan-gen's `titleSimilarity`. Duplicated on purpose: this file is node-builtins-only
  * (no workspace imports), so it cannot reach that module.
  */
+/**
+ * The factor between a candidate's raw body characters and the characters the episode actually
+ * speaks, calibrated on the two 2026-10-11 runs: 3 thin candidates (1.8k chars) scripted to 1270
+ * spoken characters (4.0 min, failed the 15-min gate) and 7 candidates (4.3k chars) scripted to 5925
+ * (16.8 min, shipped). The agent expands the news register, so the raw count under-predicts by ~1.4x;
+ * with it, both runs land on the right side of the floor.
+ */
+const SPEAK_CHAR_EXPANSION = 1.4;
+
+/**
+ * The calibrated pre-spend estimate over a kept pool (title+body characters × the 1.4 expansion,
+ * over the driver's measured char rate, plus the 8 s intro sting) — shared by the pre-spend floor
+ * gate (applyFloorGate) and the post-spend duration refusal (dailyEpisodeDuration, 0266), so both
+ * artifacts report the same arithmetic. `seconds` is unrounded: the floor gate compares seconds.
+ */
+function estimateSpokenMinutes(docs: unknown[], vdriver: string): { minutes: number; seconds: number; chars: number } {
+    const chars = docs.reduce((sum, doc) => {
+        const entry = (doc ?? {}) as Record<string, unknown>;
+        return sum + `${String(entry.title ?? '')}`.length + String(entry.body ?? '').length;
+    }, 0);
+    const seconds = 8 + (chars * SPEAK_CHAR_EXPANSION) / spokenCharRate(vdriver);
+    return { minutes: Math.round((seconds / 60) * 10) / 10, seconds, chars };
+}
+
+/**
+ * Pre-spend floor gate (2026-10-12). `daily-episode-duration` also refuses a final episode below
+ * the floor, but it runs after the TTS spend — a thin pool would still pay for a full synthesis
+ * pass (the 04:30 tick of 2026-10-11: 3 candidates → 4.0 min episode, nothing published; since
+ * 0266 that post-spend refusal closes as no-content instead of aborting, but the spend is gone).
+ * This estimates the spoken length from the kept
+ * candidates and, when it cannot reach the floor, empties the candidate list: every downstream
+ * `pool-count --min 1` guard then skips the content, audio, publish and XHS subtrees, and the run
+ * closes through run-report and the ledger exactly like an empty pool. The estimate and its inputs
+ * land in a refusal artifact next to the candidates.
+ */
+function applyFloorGate(
+    candidates: string,
+    workDir: string,
+    runDate: string,
+    minMinutes: string,
+    vdriver: string,
+): void {
+    const floor = Number(minMinutes);
+    if (minMinutes === '' || !Number.isFinite(floor) || floor <= 0) return;
+    const content = readJson(candidates);
+    const docs = metadataOf(content).docs;
+    if (!Array.isArray(docs) || docs.length === 0) return;
+    const { minutes: estimatedMinutes, seconds: estimatedSeconds, chars } = estimateSpokenMinutes(docs, vdriver);
+    if (estimatedSeconds >= floor * 60) {
+        console.log(`floor gate: estimated ${estimatedMinutes} min from ${chars} chars — above the ${floor} min floor`);
+        return;
+    }
+    const refusal = join(workDir, '21-plan', `${runDate}_04_quality-control-content_floor-refusal.json`);
+    const ids = docs.map((doc) => String((doc as Record<string, unknown> | null)?.id ?? ''));
+    sted('write', refusal, () =>
+        writeJqText(refusal, {
+            estimatedMinutes,
+            minMinutes: floor,
+            candidateChars: chars,
+            expansion: SPEAK_CHAR_EXPANSION,
+            charRate: spokenCharRate(vdriver),
+            ids,
+            reason: `a ${docs.length}-item pool estimates ${estimatedMinutes} min of speech, below the ${floor} min floor — refusing before any TTS spend`,
+        }),
+    );
+    sted('write', candidates, () =>
+        writeJsonText(candidates, { ...(content ?? {}), metadata: { ...metadataOf(content), docs: [] } }),
+    );
+    console.error(
+        `floor gate: ${docs.length} candidates estimate ${estimatedMinutes} min < ${floor} min — candidates emptied, the run closes as no-content (see ${refusal})`,
+    );
+}
+
 export function dailyArticle(args: string[]): void {
     const [workDir = '', runDate = '', pluginsPath = ''] = args;
     const articleMd = join(workDir, '22-article', `${runDate}_06_article_article.md`);
@@ -364,9 +459,16 @@ export function dailyCoverNormalize(args: string[]): void {
  * content's `metadata.duration` — after the intro sting merged, this is the true episode length —
  * and fails loud outside `[min, max]` seconds-worth of minutes. A missing duration is a failure,
  * not a pass: the gate must never silently let an under-length episode through again.
+ *
+ * 0266 (policy (c), 2026-10-13): an under-minutes episode is a thin day, not a broken run — the
+ * gate refuses it like the pre-spend floor gate does instead of aborting before run-report/ledger:
+ * write `_11_generate_content_duration-refusal.json` beside the content, empty the candidates
+ * file (every pool-count-gated node downstream then skips) and exit 0, so the run closes as
+ * no-content with the measured vs estimated minutes recorded. Over-max still fails loud — trimming
+ * is a different problem.
  */
 export function dailyEpisodeDuration(args: string[]): void {
-    const [workDir = '', runDate = '', minArg = '', maxArg = ''] = args;
+    const [workDir = '', runDate = '', minArg = '', maxArg = '', vdriver = ''] = args;
     if (!workDir) fail('missing work_dir');
     if (!runDate) fail('missing run_date');
     const minMinutes = Number(minArg);
@@ -392,10 +494,43 @@ export function dailyEpisodeDuration(args: string[]): void {
     const minutes = seconds / 60;
     const shown = minutes.toFixed(1);
     if (minutes < minMinutes) {
-        failWith(
-            1,
-            `episode-duration: episode runs ${shown} min, below the ${minMinutes}–${maxMinutes} min requirement (duration is authoritative). The candidate pool is too thin — deepen per-item treatment or add items; do not ship a short episode silently.`,
+        const refusal = join(workDir, '30-audio', `${runDate}_11_generate_content_duration-refusal.json`);
+        const candidates = join(workDir, '21-plan', `${runDate}_04_quality-control-content_candidates.json`);
+        const content = readJson(candidates);
+        const docs = Array.isArray(metadataOf(content).docs) ? (metadataOf(content).docs as unknown[]) : [];
+        // Idempotency first: a rerun must not recompute an estimate from the already-emptied candidates.
+        // A kill between the two writes below leaves the refusal beside non-empty candidates, which would
+        // let the pool-gated publish fan package a sub-floor episode — so finish the emptying here.
+        if (isFile(refusal)) {
+            if (content !== null && docs.length > 0) {
+                sted('write', candidates, () =>
+                    writeJsonText(candidates, { ...content, metadata: { ...metadataOf(content), docs: [] } }),
+                );
+            }
+            console.log(`episode-duration: duration refusal already recorded (${refusal}) — nothing to do`);
+            return;
+        }
+        const estimated = estimateSpokenMinutes(docs, vdriver);
+        const measuredMinutes = Math.round(minutes * 10) / 10;
+        sted('write', refusal, () =>
+            writeJqText(refusal, {
+                measuredMinutes,
+                estimatedMinutes: estimated.minutes,
+                minMinutes,
+                keptCount: docs.length,
+                candidateChars: estimated.chars,
+                reason: `the episode ran ${shown} min of speech, below the ${minMinutes} min floor (pre-spend estimate ${estimated.minutes} min) — refusing after synthesis`,
+            }),
+        );
+        if (content !== null) {
+            sted('write', candidates, () =>
+                writeJsonText(candidates, { ...content, metadata: { ...metadataOf(content), docs: [] } }),
+            );
+        }
+        console.error(
+            `episode-duration: episode ran ${shown} min (estimate ${estimated.minutes} min), below the ${minMinutes}–${maxMinutes} min requirement — candidates emptied, the run closes as no-content (see ${refusal})`,
         );
+        return;
     }
     if (minutes > maxMinutes) {
         failWith(
@@ -441,6 +576,158 @@ function geminiQuotaProbeOk(workDir: string, pluginsPath: string, transcodeMp3:
     return true;
 }
 
+/** `VOICE_GEN_MP3` truthiness, matching voice-gen's own parse (`plugins/generations/voice-gen/src/mp3.ts`). */
+const MP3_TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+
+/**
+ * `transcode_mp3=true` is a workflow contract, not a driver hint: the run publishes an MP3
+ * enclosure and `daily-publish-prep` refuses a WAV (0171 R2). Only voice-gen honours
+ * `VOICE_GEN_MP3`; gemini-tts and omni-voice-gen write WAV only, so `metadata.mp3Path` stayed
+ * unset for them and every publishing run died at publish-prep. Derive the sibling MP3 here —
+ * the one place that knows both the requested transcode and what the driver actually wrote —
+ * so `daily-intro` re-transcodes the intro-merged audio to the same recorded path.
+ */
+function ensurePublishMp3(contentPath: string, transcodeMp3: string): void {
+    if (!MP3_TRUTHY.has(transcodeMp3.trim().toLowerCase())) return;
+    const content = readJson(contentPath);
+    if (content === null) return;
+    const meta = (content.metadata ?? {}) as Record<string, unknown>;
+    const recorded = meta.mp3Path;
+    if (typeof recorded === 'string' && recorded !== '' && existsSync(resolve(recorded))) return;
+    const wav = [meta.audioPath, content.audioPath].find(
+        (candidate): candidate is string =>
+            typeof candidate === 'string' && candidate.endsWith('.wav') && existsSync(resolve(candidate)),
+    );
+    if (wav === undefined) return;
+    const wavPath = resolve(wav);
+    const mp3Path = wavPath.replace(/\.wav$/i, '.mp3');
+    const proc = spawnSync('ffmpeg', [
+        '-y',
+        '-hide_banner',
+        '-loglevel',
+        'error',
+        '-i',
+        wavPath,
+        '-codec:a',
+        'libmp3lame',
+        '-b:a',
+        '64k',
+        mp3Path,
+    ]);
+    if (proc.status !== 0 || !existsSync(mp3Path)) {
+        const detail = (proc.stderr?.toString() ?? '').trim() || `exit ${String(proc.status)}`;
+        failWith(1, `generate: publish MP3 transcode failed: ${detail}`);
+    }
+    meta.mp3Path = mp3Path;
+    content.metadata = meta;
+    sted('write', contentPath, () => writeJsonText(contentPath, content));
+    console.log(`generate: wrote publish MP3 ${mp3Path}`);
+}
+
+/** ffprobe one audio attribute; empty string when the file is absent/unreadable. */
+function probeAudio(file: string, entries: string): string {
+    return (
+        spawnSync('ffprobe', [
+            '-v',
+            'error',
+            '-select_streams',
+            'a:0',
+            '-show_entries',
+            entries,
+            '-of',
+            'csv=p=0',
+            file,
+        ])
+            .stdout?.toString()
+            .trim() ?? ''
+    );
+}
+
+/** A playable local audio artifact: present, positive native sample rate and positive duration. */
+function validNativeAudio(path: unknown): boolean {
+    if (typeof path !== 'string' || path === '' || !existsSync(resolve(path))) return false;
+    const rate = Number.parseFloat(probeAudio(resolve(path), 'stream=sample_rate'));
+    const duration = Number.parseFloat(probeAudio(resolve(path), 'format=duration'));
+    return Number.isFinite(rate) && rate > 0 && Number.isFinite(duration) && duration > 0;
+}
+
+/**
+ * Whole-document speech cache hit (0105 R2 / 0257 R2): the recorded Content must carry THIS run's
+ * generator identity (`kk:<plugin>`), a passing QC report and a playable native-rate WAV. Foreign,
+ * legacy or corrupt output is a miss — never relabel another driver's audio. A valid cache missing
+ * only the requested MP3 is repaired in place from the already-rendered speech (no resynthesis).
+ */
+function wholeDocCache(contentPath: string, plugin: string, transcodeMp3: string): boolean {
+    const content = readJson(contentPath);
+    if (content === null) return false;
+    const meta = metadataOf(content);
+    const qc = meta.qc as Record<string, unknown> | undefined;
+    if (meta.generator !== `kk:${plugin}`) return false;
+    if (qc?.passed === true && validNativeAudio(meta.audioPath)) {
+        ensurePublishMp3(contentPath, transcodeMp3);
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Joined-final cache identity (0257 R3): exact ordered `metadata.sectionHashes` equality, matching
+ * generator, passing QC and a playable WAV. A stale or legacy final is a miss even when every
+ * section still hits — the caller rejoins the cached sections without model calls. The requested
+ * MP3 is repaired from the valid joined WAV; a failed derivative fails loud.
+ */
+function joinedFinalFresh(contentPath: string, plugin: string, hashes: string[], transcodeMp3: string): boolean {
+    const content = readJson(contentPath);
+    if (content === null) return false;
+    const meta = metadataOf(content);
+    if (meta.generator !== `kk:${plugin}`) return false;
+    const frozen = meta.sectionHashes;
+    if (!Array.isArray(frozen) || frozen.length !== hashes.length || !frozen.every((h, i) => h === hashes[i])) {
+        return false;
+    }
+    const qc = meta.qc as Record<string, unknown> | undefined;
+    if (qc?.passed !== true || !validNativeAudio(meta.audioPath)) return false;
+    ensurePublishMp3(contentPath, transcodeMp3);
+    return true;
+}
+
+/**
+ * Aggregate the current sections' QC into the shared VoiceQualityReport names (0257 R3): passed
+ * iff every section passed; overallScore is the minimum when every section reports a finite one
+ * (absent evidence stays unavailable, never an invented zero); segmentAudits are concatenated with
+ * globally ordered segmentIndex; criticalIssues are flattened with section labels.
+ */
+function aggregateSectionQc(
+    plans: Array<{ def: { name: string }; jsonPath: string }>,
+    totalDuration: number,
+): Record<string, unknown> {
+    const segmentAudits: Array<Record<string, unknown>> = [];
+    const criticalIssues: string[] = [];
+    const scores: number[] = [];
+    let allPassed = true;
+    let allScored = true;
+    for (const plan of plans) {
+        const report = metadataOf(readJson(plan.jsonPath)).qc;
+        const qc = report !== null && typeof report === 'object' ? (report as Record<string, unknown>) : {};
+        if (qc.passed !== true) allPassed = false;
+        if (typeof qc.overallScore === 'number' && Number.isFinite(qc.overallScore)) scores.push(qc.overallScore);
+        else allScored = false;
+        if (Array.isArray(qc.segmentAudits)) {
+            for (const audit of qc.segmentAudits) {
+                if (audit !== null && typeof audit === 'object') {
+                    segmentAudits.push({ ...(audit as Record<string, unknown>), segmentIndex: segmentAudits.length });
+                }
+            }
+        }
+        if (Array.isArray(qc.criticalIssues)) {
+            for (const issue of qc.criticalIssues) criticalIssues.push(`${plan.def.name}: ${String(issue)}`);
+        }
+    }
+    const aggregate: Record<string, unknown> = { passed: allPassed, totalDuration, segmentAudits, criticalIssues };
+    if (allScored && scores.length > 0) aggregate.overallScore = Math.min(...scores);
+    return aggregate;
+}
+
 export function dailyGenerate(args: string[]): void {
     const [
         workDir = '',
@@ -457,6 +744,7 @@ export function dailyGenerate(args: string[]): void {
         ominivoice: 'omni-voice-gen',
         voicebox: 'voice-gen',
         gemini: 'gemini-tts',
+        voxcpm: 'voxcpm-tts',
     };
     let voiceGenerator = VOICE_DRIVERS[vdriver];
     if (!voiceGenerator) {
@@ -475,12 +763,9 @@ export function dailyGenerate(args: string[]): void {
 
     if (!sectionConcurrency) {
         timed(workDir, 'generate', () => {
-            if (isFile(content) && metadataOf(readJson(content)).qc !== undefined) {
-                const qc = metadataOf(readJson(content)).qc as Record<string, unknown> | undefined;
-                if (qc?.passed === true) {
-                    console.log(`audio cached: ${content} (QC passed)`);
-                    return;
-                }
+            if (wholeDocCache(content, voiceGenerator, transcodeMp3)) {
+                console.log(`audio cached: ${content} (QC passed)`);
+                return;
             }
             // Gemini quota probe (20261006): the 06:00 cron hit gemini-3.8-flash-tts 429 with a
             // multi-hour retry-after after the shared key's window drained overnight. One tiny
@@ -494,11 +779,19 @@ export function dailyGenerate(args: string[]): void {
                     !geminiQuotaProbeOk(workDir, pluginsPath, transcodeMp3, [{ ...docsList[0], body: 'Hello.' }])
                 ) {
                     voiceGenerator = VOICE_DRIVERS.voicebox;
+                    // The fallback driver's own cache may already hold this episode (0257 R2) —
+                    // reuse it instead of paying for a second local render. VoxCPM never probes
+                    // Gemini and never falls back, so this branch is Gemini-only.
+                    if (wholeDocCache(content, voiceGenerator, transcodeMp3)) {
+                        console.log(`audio cached: ${content} (QC passed)`);
+                        return;
+                    }
                 }
             }
             kk(voiceExecutorArgs(voiceGenerator, docs, content, pluginsPath), {
                 env: { VOICE_GEN_MP3: transcodeMp3 },
             });
+            ensurePublishMp3(content, transcodeMp3);
         });
         return;
     }
@@ -623,6 +916,8 @@ export function dailyGenerate(args: string[]): void {
         // 4645 / 789.9 s of section speech = 5.88 — a 5.3–5.9 range, so 5.4 deliberately errs low (a
         // slightly early refusal is cheaper than a rendered episode the duration gate then rejects).
         // voice-gen: 20261006 6376 / 1135 = 5.62. A 20-minute ceiling is therefore ~6400 characters.
+        // VoxCPM (voxcpm-tts) shares the 5.6 voicebox estimate — PROVISIONAL: no measured VoxCPM
+        // episode exists yet (0258 supplies the evidence); the measured duration stays authoritative.
         // The style sidecar's 3.3 / 6.3 figures are stale and mutually inconsistent with its own
         // 4300–5800 字 budget (which is 13–29 min at 3.3); using them refused a script that really
         // renders in 17 min. Recalibrate from a fresh pair of `metadata.duration` readings when a
@@ -668,7 +963,16 @@ export function dailyGenerate(args: string[]): void {
                     try {
                         const sidecar = readJson(jsonPath) as Record<string, unknown>;
                         const sidecarMeta = metadataOf(sidecar) as Record<string, unknown>;
-                        if (sidecar.hash === hash || sidecarMeta.hash === hash) {
+                        const sidecarQc = sidecarMeta.qc as Record<string, unknown> | undefined;
+                        // A completed section is reusable only when its provenance, QC and audio
+                        // all belong to this driver/text/profile — a foreign or half-written
+                        // sidecar re-renders (0257 R2). The hash already folds in the driver.
+                        if (
+                            (sidecar.hash === hash || sidecarMeta.hash === hash) &&
+                            sidecarMeta.generator === `kk:${driver}` &&
+                            sidecarQc?.passed === true &&
+                            validNativeAudio(wavPath)
+                        ) {
                             cached = true;
                         }
                     } catch {}
@@ -686,7 +990,18 @@ export function dailyGenerate(args: string[]): void {
         let plans = computePlans(voiceGenerator);
         const anySynthesisNeeded = plans.some((p) => p.needsSynthesis);
 
-        if (!anySynthesisNeeded && existsSync(joinedWavPath) && existsSync(joinedContentPath)) {
+        // All sections hit, but the joined final is reusable only when its frozen identity matches
+        // this run's ordered section hashes (0257 R3). A stale or legacy final — e.g. a previous
+        // join failed — falls through and rejoins the cached sections below, with no model calls.
+        if (
+            !anySynthesisNeeded &&
+            joinedFinalFresh(
+                joinedContentPath,
+                voiceGenerator,
+                plans.map((p) => p.hash),
+                transcodeMp3,
+            )
+        ) {
             console.log('generate: all sections cached, joined speech reused');
             return;
         }
@@ -733,10 +1048,25 @@ export function dailyGenerate(args: string[]): void {
             };
             writeJsonText(secDocIn, [doc]);
             try {
-                const status = kk(voiceExecutorArgs(voiceGenerator, secDocIn, plan.jsonPath, pluginsPath), {
+                // 0269-shaped hardening (20261012): one retry for a failed section. The design already
+                // bounds the episode's risk with the pre-flight quota probe and the per-section cache,
+                // but a failure that arrives MID-render (a 429 once the window drains, a network blip)
+                // still cost the whole episode — the one step nothing can publish without. The retry is
+                // cheap and bounded: the successful sections are cache hits, so at most one extra
+                // request per failed section is issued, and a persistent failure still fails loud.
+                let status = kk(voiceExecutorArgs(voiceGenerator, secDocIn, plan.jsonPath, pluginsPath), {
                     env: { VOICE_GEN_MP3: transcodeMp3 },
                     soft: true,
                 });
+                if (status !== 0) {
+                    console.log(
+                        `generate: section ${plan.def.stem} synthesis failed (exit ${status}) — retrying it once`,
+                    );
+                    status = kk(voiceExecutorArgs(voiceGenerator, secDocIn, plan.jsonPath, pluginsPath), {
+                        env: { VOICE_GEN_MP3: transcodeMp3 },
+                        soft: true,
+                    });
+                }
                 if (status !== 0) {
                     failWith(status, `generate: section synthesis failed for ${plan.def.stem}`);
                 }
@@ -795,21 +1125,52 @@ export function dailyGenerate(args: string[]): void {
         }
 
         const joinedDuration = Number.parseFloat(probeHelper(joinedWavPath, 'format=duration'));
+        if (!validNativeAudio(joinedWavPath) || !Number.isFinite(joinedDuration)) {
+            failWith(1, `generate: joined audio is not a playable native-rate WAV: ${joinedWavPath}`);
+        }
 
-        let contentObj: Record<string, unknown> = {};
-        if (existsSync(joinedContentPath)) {
-            try {
-                contentObj = readJson(joinedContentPath) as Record<string, unknown>;
-            } catch {}
+        // podcast-pub renders the show-notes timeline from `metadata.segments[]` (per-segment
+        // duration + ASR transcription). The one-shot path receives them from the voice plugin, but
+        // this sectioned path synthesizes one sidecar per section and dropped them at the join — every
+        // timeline row rendered 0:00 (2026-10-11). Rebuild the list in section order from the CURRENT
+        // sidecars, never inherit the previous final's list (0257 R3).
+        const joinedSegments: Array<Record<string, unknown>> = [];
+        for (const plan of plans) {
+            const sectionSegments = metadataOf(readJson(plan.jsonPath)).segments;
+            if (Array.isArray(sectionSegments)) {
+                joinedSegments.push(...(sectionSegments as Array<Record<string, unknown>>));
+            }
         }
-        const meta = (contentObj.metadata ?? {}) as Record<string, unknown>;
-        delete meta.introMerged;
-        meta.audioPath = joinedWavPath;
-        meta.duration = joinedDuration;
-        contentObj.audioPath = joinedWavPath;
-        contentObj.mediaType = 'audio/wav';
-        contentObj.metadata = meta;
+        // Rebuild the Content envelope from the current script/sections. The previous final's
+        // generator/QC/mp3Path/sectionHashes must never survive a fresh join, and mp3Path is
+        // deliberately absent so ensurePublishMp3 regenerates the requested derivative (0257 R3).
+        const baseMeta: Record<string, unknown> = {
+            generator: `kk:${voiceGenerator}`,
+            audioPath: joinedWavPath,
+            duration: joinedDuration,
+        };
+        if (joinedSegments.length > 0) baseMeta.segments = joinedSegments;
+        const contentObj: Record<string, unknown> = {
+            title: typeof script.title === 'string' && script.title !== '' ? script.title : 'Daily AI News',
+            body: scriptRaw,
+            format: 'audio',
+            references: [],
+            audioPath: joinedWavPath,
+            mediaType: 'audio/wav',
+            metadata: baseMeta,
+        };
         writeJsonText(joinedContentPath, contentObj);
+        // Transcode the requested MP3 before any success claim is written: a failed conversion
+        // fails loud with no qc.passed on disk, so the next run rejoins the cached sections rather
+        // than trusting a broken final (0257 R3).
+        ensurePublishMp3(joinedContentPath, transcodeMp3);
+        // Join and derivative are proven; only now record the frozen identity and aggregated QC.
+        const finalized = readJson(joinedContentPath) ?? contentObj;
+        const finalMeta = metadataOf(finalized);
+        finalMeta.qc = aggregateSectionQc(plans, joinedDuration);
+        finalMeta.sectionHashes = plans.map((p) => p.hash);
+        finalized.metadata = finalMeta;
+        writeJsonText(joinedContentPath, finalized);
     });
 }
 
@@ -933,16 +1294,21 @@ export function dailyIntro(args: string[]): void {
 }
 
 export function dailyPlan(args: string[]): void {
-    const [workDir = '', runDate = '', pluginsPath = '', planMaxItems = ''] = args;
+    const [workDir = '', runDate = '', pluginsPath = '', planMaxItems = '', deferPlanDocs = ''] = args;
     const planContent = join(workDir, '21-plan', `${runDate}_03_plan_content.json`);
     const planDocs = join(workDir, '21-plan', `${runDate}_03_plan_plan.json`);
     // voice2's extract node writes 10-collect/pool.json; voice1's fan-in still writes the blended
     // file. Prefer the pool when it exists so both DAGs share this stage (0212 dogfood finding).
     const pool = join(workDir, '10-collect', 'pool.json');
     const blended = isFile(pool) ? pool : join(workDir, '10-ingest', `${runDate}_02_collect_blended.json`);
+    // voice2 passes plan_translate_enabled. When it is true, plan-translate owns plan.json: its
+    // `! test -s` guard is also the first-run gate, so writing the English docs here skips the
+    // translation. Voice1 omits the arg and still materializes the file (its translate node has no
+    // skip guard and overwrites it).
+    const deferDocs = deferPlanDocs === 'true';
     timed(workDir, 'plan', () => {
-        if (isFile(planDocs)) {
-            console.log(`plan cached: ${planDocs}`);
+        if (deferDocs ? isFile(planContent) : isFile(planDocs)) {
+            console.log(`plan cached: ${deferDocs ? planContent : planDocs}`);
             return;
         }
         kk(
@@ -953,6 +1319,7 @@ export function dailyPlan(args: string[]): void {
         );
         const docs = metadataOf(readJson(planContent)).docs;
         if (!Array.isArray(docs) || docs.length === 0) failWith(1, 'plan: content.metadata.docs missing or empty');
+        if (deferDocs) return;
         sted('write', planDocs, () => writeJsonText(planDocs, docs));
         if (!isFile(planDocs)) failWith(1, `plan: ${planDocs} not written after episode-plan-gen`);
     });
@@ -1143,18 +1510,30 @@ export function dailyPublishWechat(args: string[]): void {
             return;
         }
         const packaged = requireJson(article, 'publish-wechat');
-        // MP draft enrichment (operator preference 2026-09-29): 原创+作者, 赞赏, 合集, 原文链接
-        // (the surfdash post), AI 生成声明, cover. The brand strings are this daily show's constants.
+        // MP draft enrichment (operator preferences 2026-09-29, completed 2026-10-10): 原创, 赞赏,
+        // 作者, 合集, 原文链接 (the surfdash post), 创作来源, cover, audio material. The brand strings
+        // are this daily show's constants; every field here is consumed by `wechatmp-pub`'s flow.
         const cover = join(workDir, '23-cover', `${runDate}_07_cover_cover.png`);
         const audio = join(workDir, '30-audio', `${runDate}_11_generate_content.mp3`);
+        const surfdashResult = join(workDir, '31-publish', `${runDate}_14_publish-surfdash_result.json`);
+        const originalUrl = isFile(surfdashResult) ? firstTargetUrl(readJson(surfdashResult), 'surfdash-pub') : '';
         const wechatmp: Record<string, unknown> = {
             original: true,
-            aiGenerated: true,
+            // 赞赏 is enabled per episode; the plugin fills the 赞赏账户 only when the platform
+            // leaves it empty (it defaults from 作者, operator walk 2026-10-10).
+            reward: true,
             author: '冰原奔狼',
-            collection: collectionArg || '每日AI乱炖',
+            collection: collectionArg || '每日AI资讯',
+            // 创作来源 is the column's own stance, not an AI-declaration label — the operator owns
+            // the wording (2026-10-10).
+            claimSource: '个人观点，仅供参考',
+            // 封面 comes from 图片库: the episode cover is uploaded there as the audio material's
+            // cover, so the library's newest entry is the intended image.
+            coverSource: 'library',
+            ...(originalUrl !== '' ? { originalUrl } : {}),
             ...(isFile(cover) ? { coverPath: cover } : {}),
-            // Audio block at the article top (operator request 2026-09-29): the daily MP3 goes to
-            // the 素材库 under the article title; the plugin reuses an existing same-title material.
+            // Audio block at the article top (operator request 2026-09-29; the plugin UPLOADS the
+            // material when the 素材库 has no same-title entry, 2026-10-10).
             ...(isFile(audio)
                 ? {
                       audioPath: audio,
@@ -1579,8 +1958,141 @@ export function dailySafetyRevise(args: string[]): void {
     });
 }
 
+/** Block YAML for the fields a fitted VoiceScript actually carries. Strings use JSON quoting. */
+function voicescriptToBlockYaml(script: Record<string, unknown>): string {
+    const lines: string[] = [];
+    for (const key of [
+        'title',
+        'language',
+        'default_profile',
+        'default_profile_id',
+        'default_engine',
+        'default_emotion',
+        'default_effect_preset',
+    ]) {
+        const value = script[key];
+        if (typeof value === 'string' && value !== '') lines.push(`${key}: ${JSON.stringify(value)}`);
+    }
+    const segments = script.segments;
+    if (!Array.isArray(segments)) return lines.join('\n');
+    lines.push('segments:');
+    for (const entry of segments) {
+        const segment = entry as Record<string, unknown>;
+        lines.push(`  - text: ${JSON.stringify(segment.text ?? '')}`);
+        for (const key of ['speaker', 'profile', 'profile_id', 'emotion', 'instruct', 'effect_preset']) {
+            if (typeof segment[key] === 'string') lines.push(`    ${key}: ${JSON.stringify(segment[key])}`);
+        }
+        for (const key of ['gap_ms', 'speed', 'seed', 'personality']) {
+            if (typeof segment[key] === 'number') lines.push(`    ${key}: ${segment[key]}`);
+        }
+    }
+    return lines.join('\n');
+}
+
+/** Measured driver rates from dailyGenerate. Unknown drivers (incl. voxcpm, provisionally) use the voicebox rate. */
+function spokenCharRate(vdriver: string): number {
+    return vdriver === 'gemini' ? 5.4 : 5.6;
+}
+
+/**
+ * Shorten one fact/insight at 。！？ so the cut removes at least `removeAtLeast` characters when a
+ * boundary allows it, otherwise drop the last sentence. Returns null when the text is one sentence.
+ */
+function shrinkFactText(text: string, removeAtLeast: number): string | null {
+    const ends: number[] = [];
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === '。' || ch === '！' || ch === '？') ends.push(i + 1);
+    }
+    if (ends.length === 0) return null;
+    const limit = text.length - Math.max(removeAtLeast, 1);
+    let chosen: number | null = null;
+    for (const end of ends) {
+        if (end <= limit && end < text.length && end > 0) chosen = end;
+    }
+    if (chosen !== null) return text.slice(0, chosen);
+    const shorter = ends.filter((end) => end < text.length && end > 0);
+    const tail = shorter[shorter.length - 1];
+    if (tail === undefined) return null;
+    return text.slice(0, tail);
+}
+
+/**
+ * The pre-spend gate in dailyGenerate refuses before any TTS when the spoken character estimate
+ * exceeds `episode_max_minutes`. Optional args (voice2 only) fit the fresh VoiceScript down to that
+ * budget by shortening the longest fact segments, then insights. Absent args leave the file untouched.
+ */
+function fitVoicescriptToBudget(yamlOut: string, contentOut: string, episodeMaxMinutes: string, vdriver: string): void {
+    if (episodeMaxMinutes === '') return;
+    const maxMinutes = Number(episodeMaxMinutes);
+    if (!Number.isFinite(maxMinutes) || maxMinutes <= 0) return;
+    // Two minutes under the hard duration gate. The character rate is a past measurement; fitting
+    // flush to the ceiling renders an episode the gate then rejects.
+    const maxChars = Math.floor((maxMinutes * 60 - 8 - 120) * spokenCharRate(vdriver));
+    const original = readFileSync(yamlOut, 'utf8');
+    const script = Bun.YAML.parse(original) as { segments?: Array<Record<string, unknown>> };
+    const segments = script.segments;
+    if (!Array.isArray(segments) || segments.length < 3) return;
+    const totalOf = (): number => segments.reduce((sum, seg) => sum + [...String(seg.text ?? '')].length, 0);
+    const before = totalOf();
+    if (before <= maxChars) return;
+    const unsplittable = new Set<number>();
+    for (const factsOnly of [true, false]) {
+        while (totalOf() > maxChars) {
+            let best = -1;
+            let bestLen = 0;
+            for (let i = 1; i < segments.length - 1; i++) {
+                if (unsplittable.has(i)) continue;
+                if (factsOnly && segments[i]?.speed === 1.12) continue;
+                const len = [...String(segments[i]?.text ?? '')].length;
+                if (len > bestLen) {
+                    best = i;
+                    bestLen = len;
+                }
+            }
+            if (best < 0) break;
+            const text = String(segments[best]?.text ?? '');
+            const next = shrinkFactText(text, totalOf() - maxChars);
+            if (next === null || next.length >= text.length) {
+                unsplittable.add(best);
+                continue;
+            }
+            const segment = segments[best];
+            if (segment) segment.text = next;
+        }
+    }
+    const after = totalOf();
+    if (after === before) return;
+    // Block YAML, same shape as dailynews-gen's formatter. Bun.YAML.stringify emits a `{...}` flow
+    // document, and the VoiceScript checker JSON-parses anything that starts with `{`.
+    const fitted = `${voicescriptToBlockYaml(script)}\n`;
+    sted('write', yamlOut, () => writeRaw(yamlOut, fitted));
+    if (isFile(contentOut)) {
+        const content = readJson(contentOut);
+        if (content && typeof content.body === 'string') {
+            content.body = fitted;
+            sted('write', contentOut, () => writeJsonText(contentOut, content));
+        }
+    }
+    console.log(`script: fitted voicescript ${before} -> ${after} chars (budget ${maxChars})`);
+    if (after > maxChars) {
+        console.error(
+            `script: voicescript still ${after - maxChars} chars over the ${maxChars} budget after sentence cuts`,
+        );
+    }
+}
+
 export function dailyScript(args: string[]): void {
-    const [workDir = '', runDate = '', pluginsPath = '', language = '', title = '', voiceProfile = ''] = args;
+    const [
+        workDir = '',
+        runDate = '',
+        pluginsPath = '',
+        language = '',
+        title = '',
+        voiceProfile = '',
+        episodeMaxMinutes = '',
+        vdriver = '',
+    ] = args;
     const yamlOut = join(workDir, '24-script', `${runDate}_08_script_voicescript.yaml`);
     const contentOut = join(workDir, '24-script', `${runDate}_08_script_content.json`);
     const planIn = join(workDir, '21-plan', `${runDate}_03_plan_plan.json`);
@@ -1607,6 +2119,7 @@ export function dailyScript(args: string[]): void {
         const body = readJson(contentOut)?.body;
         if (typeof body !== 'string') failWith(1, `script: ${contentOut} has no string body`);
         sted('write', yamlOut, () => writeRaw(yamlOut, body));
+        fitVoicescriptToBudget(yamlOut, contentOut, episodeMaxMinutes, vdriver);
         // R3 (task 0139): fresh writes are validated here; the script cache path is covered by
         // wrap-docs, which runs on every path that reaches audio.
         try {
@@ -1661,8 +2174,30 @@ export function dailyShowNotes(args: string[]): void {
         // Inlined parse — this file must not import @gobing-ai/* (header contract); the same note
         // grammar lives in daily-article-gen's excludedIdsFromNote.
         const postPath = firstPostPath(readJson(result), 'surfdash-pub');
-        const articleBody = readJson(article)?.body;
+        const articleContent = readJson(article);
+        const articleBody = articleContent?.body;
         const excluded = new Set<string>();
+        // Article Content carries the dropped ids as `metadata.excludedIds` (2026-10-10): the boundary
+        // note is stripped from the published body, so re-parsing the body alone would silently stop
+        // filtering and leak excluded docs into the show notes. The note parse below stays as the
+        // fallback for Content produced before the field existed.
+        const metaExcluded = metadataOf(articleContent)?.excludedIds;
+        if (Array.isArray(metaExcluded)) {
+            for (const id of metaExcluded) {
+                if (typeof id === 'string' && id !== '') excluded.add(id);
+            }
+        }
+        // Script-plan exclusions are the prompt-layer topic boundary (foreign public affairs the
+        // keyword floor deliberately leaves in the plan). Show notes must match what was spoken.
+        const scriptPlan = readJson(join(workDir, '24-script', `${runDate}_08_script-write_plan.json`));
+        const scriptExcluded = scriptPlan?.excluded;
+        if (Array.isArray(scriptExcluded)) {
+            for (const entry of scriptExcluded) {
+                if (entry !== null && typeof entry === 'object' && typeof (entry as { id?: unknown }).id === 'string') {
+                    excluded.add((entry as { id: string }).id);
+                }
+            }
+        }
         if (typeof articleBody === 'string') {
             for (const note of articleBody.matchAll(/未写入[：:](.*)/g)) {
                 for (const id of note[1].matchAll(/(?:[a-zA-Z0-9_-]+:)?[0-9a-f]{16,64}/g)) {
@@ -1868,6 +2403,73 @@ function episodeNoteBody(body: string, lines: string[], cap: number): string {
     return note;
 }
 
+/**
+ * 0251 R1: parse the composer's safe-area overflow sentence
+ * (`text overflows the safe area for field(s): <fields> (safe area: …)`, chromium.ts) into the
+ * named `points[n]` indexes — or null when the failure is anything else: no marker, a non-points
+ * field (e.g. `headline`), or an index outside `card.points`. Null means no retry.
+ */
+export function xhsOverflowPoints(stderr: string, card: XhsCard): number[] | null {
+    const marker = 'text overflows the safe area for field(s):';
+    const at = stderr.indexOf(marker);
+    if (at < 0) return null;
+    const list = stderr.slice(at + marker.length).split('(')[0] ?? '';
+    const fields = list.split(',').map((name) => /^points\[(\d+)\]$/.exec(name.trim())?.[1]);
+    if (fields.length === 0 || fields.some((field) => field === undefined)) return null;
+    const indexes = fields.map((field) => Number(field));
+    if (indexes.some((n) => n >= card.points.length)) return null;
+    return indexes;
+}
+
+/** The sentence-ending marks the shorten rule cuts at. */
+const POINT_SENTENCE_MARKS = new Set(['。', '！', '？']);
+
+/** Fewest bullets a card keeps: below two, the block stops reading as a list. */
+const XHS_MIN_POINTS = 2;
+
+/** How many rewrites a refused card gets; each attempt re-bills one illustration. */
+const XHS_OVERFLOW_ATTEMPTS = 3;
+
+/**
+ * 0251 R1 + 2026-10-12: reduce the points of a card the composer refused, so the next compose pass
+ * can fit them. Rule 1 shortens each point the composer named ({@link shortenOverflowedPoint}). When
+ * no point can get shorter the block itself is over budget — measured on 20261011-ai-2026-10-11, whose
+ * cover points are 12–16 code-point single sentences that both shortening rules leave untouched, so
+ * the old single-shot retry never fired and the whole series was lost — so rule 2 drops the trailing
+ * point. Returns whether the card changed, the caller's signal to retry.
+ */
+export function reduceOverflowingPoints(points: string[], named: readonly number[]): boolean {
+    let changed = false;
+    for (const n of named) {
+        const point = points[n] ?? '';
+        const next = shortenOverflowedPoint(point);
+        if (next !== point) {
+            points[n] = next;
+            changed = true;
+        }
+    }
+    if (!changed && points.length > XHS_MIN_POINTS) {
+        points.pop();
+        changed = true;
+    }
+    return changed;
+}
+
+/**
+ * 0251 R1: shorten one overflowing card point — drop its last sentence (cut at the last
+ * 。/！/？ that is not the final character, inclusive); a one-sentence point longer than 36
+ * code points keeps its first 36 plus `…`. Returns the input unchanged when neither rule
+ * shortens it, which the caller reads as "nothing got shorter — do not retry".
+ */
+export function shortenOverflowedPoint(point: string): string {
+    const chars = [...point];
+    for (let i = chars.length - 2; i >= 0; i--) {
+        if (POINT_SENTENCE_MARKS.has(chars[i] ?? '')) return chars.slice(0, i + 1).join('');
+    }
+    if (chars.length > 36) return `${chars.slice(0, 36).join('')}…`;
+    return point;
+}
+
 /**
  * E8: build one `image-gen` envelope per planned card, render them sequentially, and package the
  * ordered card manifest + `Content` that `xhs-pub` consumes. Format, style, provider and model
@@ -1946,18 +2548,55 @@ export function dailyXhsRender(args: string[]): void {
                 // Sequential on purpose: one provider call per card (illustration only —
                 // card copy is typeset by image-gen's composer, never prompted), and the
                 // first failure stops the spend — later cards stay unrendered for a resume
-                // run to pick up.
-                const status = kk(
-                    ['executor', 'run', 'image-gen', '--in', envPath, '--out', out, ...pluginsArgs(pluginsPath)],
-                    { soft: true },
-                );
+                // run to pick up. 0251: the one captured call — the overflow retry branches
+                // on the composer's stderr, which kk()'s inherit stdio cannot return.
+                const imageGenArgs = [
+                    'executor',
+                    'run',
+                    'image-gen',
+                    '--in',
+                    envPath,
+                    '--out',
+                    out,
+                    ...pluginsArgs(pluginsPath),
+                ];
                 // 0219 R2: name the failed card so a hand re-run resumes without re-billing.
-                if (status !== 0) {
-                    failWith(
-                        status,
-                        `xhs render: card ${card.index} failed (image-gen exit ${status}); cards before it are kept — re-run daily-xhs-render to resume from card ${card.index}`,
+                const resumeLine = (status: number): string =>
+                    `xhs render: card ${card.index} failed (image-gen exit ${status}); cards before it are kept — re-run daily-xhs-render to resume from card ${card.index}`;
+                let result = kkCaptured(imageGenArgs, { soft: true });
+                // 0269: a failure the composer's overflow sentence does NOT explain is retried once with
+                // the SAME envelope, because the observed cause of those is the provider, not the input:
+                // on 2026-10-12 card 02 was rewritten for a points[3] overflow and the second call then
+                // failed with only a vendor-fallback warning (minimax flaked); re-running that exact
+                // saved envelope by hand rendered on the first try. 0251 R2 read "not an overflow ⇒ do not
+                // retry" as fail-fast, which is what lost the whole series that day (and every day since
+                // 10-08). The budget stays bounded: overflow rewrites keep their 3, a provider failure
+                // gets exactly 1, so a permanently broken card costs one extra illustration and not four.
+                let transientRetryUsed = false;
+                for (let attempt = 0; result.status !== 0 && attempt < XHS_OVERFLOW_ATTEMPTS; attempt += 1) {
+                    // 0251 R1 (+ the block-level rule 2): a points[n] safe-area overflow is rewritable —
+                    // shorten the named points, then drop the trailing one. The envelope is rewritten in
+                    // the same shape and image-gen is called again.
+                    const named = xhsOverflowPoints(result.stderr, card);
+                    if (named === null) {
+                        if (transientRetryUsed) break;
+                        transientRetryUsed = true;
+                        console.log(
+                            `xhs render: card ${card.index} failed without a safe-area overflow — retrying the same envelope once (exit ${result.status})`,
+                        );
+                        result = kkCaptured(imageGenArgs, { soft: true });
+                        continue;
+                    }
+                    if (!reduceOverflowingPoints(card.points, named)) break;
+                    (imageGen.vars as Record<string, unknown>).points = card.points.join('\n');
+                    sted('write', envPath, () =>
+                        writeJsonText(envPath, [
+                            { id: `xhs-card-${card.index}`, title: runDate, body: '', metadata: { imageGen } },
+                        ]),
                     );
+                    result = kkCaptured(imageGenArgs, { soft: true });
                 }
+                if (result.status !== 0) failWith(result.status, resumeLine(result.status));
                 artifact = firstArtifact(requireJson(out, 'xhs render'));
             }
             if (artifact === null) failWith(1, `xhs render: card ${card.index} recorded no image artifact (${out})`);