@gobing-ai/knowledge-kit 0.0.33 → 0.0.35

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,
@@ -104,8 +106,10 @@ import {
     writeJqText,
     writeJsonText,
     writeRaw,
+    XHS_BODY_CAP,
     XHS_FORMAT,
     XHS_MAX_CARDS,
+    type XhsCard,
     xhsPlan,
 } from './kk-workflow-stages.ts';
 
@@ -162,25 +166,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(', ')}`,
+        );
+    }
+    // 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');
     }
-    (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(', ')}`,
-    );
+    (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(', ')}`);
 }
 
 /**
@@ -197,12 +217,31 @@ export function dailyArticle(args: string[]): void {
     timed(workDir, 'article', () => {
         let planUsable = true;
         const raw = isFile(planIn) ? readFileSync(planIn, 'utf-8') : '';
+        // The plan file is canonically the plan `Doc[]` — `dailyPlan` writes the generator's
+        // `metadata.docs` — and every downstream stage reads it as one. `plan-translate`'s executor
+        // has been observed writing the generator's Content ENVELOPE back instead: valid JSON of the
+        // wrong shape, which the article generator then refuses with `expected array, received
+        // object`. Unwrap that envelope rather than discard the translation; anything else unusable
+        // still falls back to the untranslated candidates.
+        let planShape: unknown;
         try {
-            JSON.parse(raw);
+            planShape = JSON.parse(raw);
         } catch (error) {
             console.error(
                 `article: plan.json invalid JSON — replacing with untranslated plan (downstream states read this file): ${(error as Error).message}`,
             );
+        }
+        if (planShape !== undefined && !Array.isArray(planShape)) {
+            const enveloped = metadataOf(planShape as Record<string, unknown>).docs;
+            if (Array.isArray(enveloped) && enveloped.length > 0) {
+                console.error(
+                    `article: plan.json carries the Content envelope, not the Doc[] — unwrapping metadata.docs (${enveloped.length} doc(s))`,
+                );
+                sted('write', planIn, () => writeJsonText(planIn, enveloped));
+                planShape = enveloped;
+            }
+        }
+        if (!Array.isArray(planShape)) {
             const docs = metadataOf(readJson(candidates)).docs;
             if (!Array.isArray(docs) || docs.length === 0) {
                 console.error('article: candidates.json metadata.docs missing');
@@ -386,8 +425,51 @@ export function dailyEpisodeDuration(args: string[]): void {
     console.log(`episode-duration ok: ${shown} min within ${minMinutes}–${maxMinutes} min`);
 }
 
+/** Ceiling for the pre-spend estimate when the caller passes no `episode_max_minutes`. */
+const DEFAULT_EPISODE_MAX_MINUTES = 20;
+
+/** `kk executor run` argv shared by the quota probe, the voice1 one-shot, and each section. */
+function voiceExecutorArgs(generator: string, input: string, output: string, pluginsPath: string): string[] {
+    return ['executor', 'run', generator, '--in', input, '--out', output, ...pluginsArgs(pluginsPath)];
+}
+
+/**
+ * One tiny gemini-tts render before any episode speech. A non-zero exit (quota, key, network)
+ * means this run should use voicebox. Probe files are removed either way.
+ * Returns false when the caller should fall back.
+ */
+function geminiQuotaProbeOk(workDir: string, pluginsPath: string, transcodeMp3: string, probeDocs: unknown): boolean {
+    const probeDir = join(workDir, '30-audio');
+    const probeIn = join(probeDir, '.gemini-probe-in.json');
+    const probeOut = join(probeDir, '.gemini-probe-out.json');
+    writeJsonText(probeIn, probeDocs);
+    const probe = spawnSync('kk', voiceExecutorArgs('gemini-tts', probeIn, probeOut, pluginsPath), {
+        encoding: 'utf8',
+        timeout: 120_000,
+        env: { ...process.env, VOICE_GEN_MP3: transcodeMp3 },
+    });
+    for (const stale of [probeIn, probeOut, probeOut.replace(/\.json$/, '.wav'), probeOut.replace(/\.json$/, '.mp3')]) {
+        rmSync(stale, { force: true });
+    }
+    if (probe.status !== 0) {
+        const reason = (probe.stderr ?? '').trim().split('\n').slice(-1)[0] || `exit ${probe.status}`;
+        console.log(`generate: gemini quota probe failed (${reason}) — falling back to voicebox for this run`);
+        return false;
+    }
+    console.log('generate: gemini quota probe ok');
+    return true;
+}
+
 export function dailyGenerate(args: string[]): void {
-    const [workDir = '', runDate = '', pluginsPath = '', transcodeMp3 = '', vdriver = ''] = args;
+    const [
+        workDir = '',
+        runDate = '',
+        pluginsPath = '',
+        transcodeMp3 = '',
+        vdriver = '',
+        sectionConcurrency = '',
+        episodeMaxMinutes = '',
+    ] = args;
     // 20260917 review: the workflow picks a voice driver by short name; both drivers' envs are
     // passed unconditionally so switching `vdriver` needs no shell changes. Unknown -> fail loud.
     const VOICE_DRIVERS: Record<string, string> = {
@@ -402,54 +484,351 @@ export function dailyGenerate(args: string[]): void {
             `generate: unknown vdriver '${vdriver}' (expected one of: ${Object.keys(VOICE_DRIVERS).join(', ')})`,
         );
     }
+    // Strict `Number`, not `parseFloat`: a typo'd var ('2O') must refuse, not cap the episode at 2 min.
+    const maxMinutes = episodeMaxMinutes === '' ? DEFAULT_EPISODE_MAX_MINUTES : Number(episodeMaxMinutes);
+    if (!Number.isFinite(maxMinutes) || maxMinutes <= 0) {
+        failWith(1, `generate: invalid episode_max_minutes: ${episodeMaxMinutes}`);
+    }
     const docs = join(workDir, '30-audio', `${runDate}_10_wrap-docs_docs.json`);
     const content = join(workDir, '30-audio', `${runDate}_11_generate_content.json`);
+
+    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;
+                }
+            }
+            // 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
+            // render (~1 request) before the real episode; ANY probe failure (quota, key, network)
+            // flips this run to the local voicebox driver instead of dying mid-episode — voicebox
+            // needs no key. Operator decision 20261006: keep the gemini default + auto-fallback.
+            if (vdriver === 'gemini') {
+                const docsList = readJson(docs) as Array<Record<string, unknown>>;
+                if (
+                    docsList.length > 0 &&
+                    !geminiQuotaProbeOk(workDir, pluginsPath, transcodeMp3, [{ ...docsList[0], body: 'Hello.' }])
+                ) {
+                    voiceGenerator = VOICE_DRIVERS.voicebox;
+                }
+            }
+            kk(voiceExecutorArgs(voiceGenerator, docs, content, pluginsPath), {
+                env: { VOICE_GEN_MP3: transcodeMp3 },
+            });
+        });
+        return;
+    }
+
+    if (sectionConcurrency !== '1') {
+        failWith(1, `generate: section_concurrency '${sectionConcurrency}' not supported (must be 1)`);
+    }
+
     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;
+        const scriptPath = join(workDir, '24-script', `${runDate}_08_script_voicescript.yaml`);
+        if (!existsSync(scriptPath)) {
+            failWith(1, `generate: voicescript not found: ${scriptPath}`);
+        }
+        const scriptRaw = readFileSync(scriptPath, 'utf8');
+        const script = Bun.YAML.parse(scriptRaw) as Record<string, unknown>;
+        const segments = (script.segments ?? []) as Array<Record<string, unknown>>;
+        if (!Array.isArray(segments) || segments.length < 2) {
+            failWith(1, 'generate: invalid voicescript (expected at least opening and closing segments)');
+        }
+
+        // Grouping: first is opening, last is closing, middle segments split after gap_ms: 1200
+        const middleSegments = segments.slice(1, -1);
+        const itemSections: Array<Array<Record<string, unknown>>> = [];
+        let currentItem: Array<Record<string, unknown>> = [];
+        for (const seg of middleSegments) {
+            currentItem.push(seg);
+            if (seg.gap_ms === 1200) {
+                itemSections.push(currentItem);
+                currentItem = [];
             }
         }
-        // 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
-        // render (~1 request) before the real episode; ANY probe failure (quota, key, network)
-        // flips this run to the local voicebox driver instead of dying mid-episode — voicebox
-        // needs no key. Operator decision 20261006: keep the gemini default + auto-fallback.
-        if (vdriver === 'gemini') {
-            const probeDir = join(workDir, '30-audio');
-            const probeIn = join(probeDir, '.gemini-probe-in.json');
-            const probeOut = join(probeDir, '.gemini-probe-out.json');
-            const docsList = readJson(docs) as Array<Record<string, unknown>>;
-            if (docsList.length > 0) {
-                writeJsonText(probeIn, [{ ...docsList[0], body: 'Hello.' }]);
-                const probe = spawnSync(
-                    'kk',
-                    ['executor', 'run', 'gemini-tts', '--in', probeIn, '--out', probeOut, ...pluginsArgs(pluginsPath)],
-                    { encoding: 'utf8', timeout: 120_000, env: { ...process.env, VOICE_GEN_MP3: transcodeMp3 } },
-                );
-                for (const stale of [
-                    probeIn,
-                    probeOut,
-                    probeOut.replace(/\.json$/, '.wav'),
-                    probeOut.replace(/\.json$/, '.mp3'),
-                ])
-                    rmSync(stale, { force: true });
-                if (probe.status !== 0) {
-                    const reason = (probe.stderr ?? '').trim().split('\n').slice(-1)[0] || `exit ${probe.status}`;
-                    console.log(
-                        `generate: gemini quota probe failed (${reason}) — falling back to voicebox for this run`,
+        if (currentItem.length > 0) {
+            itemSections.push(currentItem);
+        }
+
+        const planPath = join(workDir, '24-script', `${runDate}_08_script-write_plan.json`);
+        if (existsSync(planPath)) {
+            try {
+                const plan = readJson(planPath) as { items?: unknown[] };
+                if (Array.isArray(plan.items) && plan.items.length !== itemSections.length) {
+                    failWith(
+                        1,
+                        `generate: plan item count (${plan.items.length}) does not match script item sections (${itemSections.length})`,
                     );
-                    voiceGenerator = VOICE_DRIVERS.voicebox;
-                } else {
-                    console.log('generate: gemini quota probe ok');
                 }
+            } catch (e: unknown) {
+                if (e instanceof StageFailure) throw e;
             }
         }
-        kk(['executor', 'run', voiceGenerator, '--in', docs, '--out', content, ...pluginsArgs(pluginsPath)], {
-            env: { VOICE_GEN_MP3: transcodeMp3 },
+
+        interface SectionDef {
+            index: number;
+            role: string;
+            stem: string;
+            name: string;
+            segments: Array<Record<string, unknown>>;
+            characters: number;
+            gap_ms: number;
+            text: string;
+        }
+
+        const sectionDefs: SectionDef[] = [];
+        // 00-opening
+        const openSegs = [segments[0]];
+        const openText = openSegs.map((s) => String(s.text ?? '')).join('');
+        sectionDefs.push({
+            index: 0,
+            role: 'opening',
+            stem: '00-opening',
+            name: '00-opening',
+            segments: openSegs,
+            characters: [...openText].length,
+            gap_ms:
+                typeof openSegs[openSegs.length - 1].gap_ms === 'number'
+                    ? (openSegs[openSegs.length - 1].gap_ms as number)
+                    : 1200,
+            text: openText,
         });
+
+        // 01-item ...
+        itemSections.forEach((segs, idx) => {
+            const itemIdx = idx + 1;
+            const pad = String(itemIdx).padStart(2, '0');
+            const stem = `${pad}-item`;
+            const itemText = segs.map((s) => String(s.text ?? '')).join('');
+            const lastSeg = segs[segs.length - 1];
+            sectionDefs.push({
+                index: itemIdx,
+                role: 'item',
+                stem,
+                name: stem,
+                segments: segs,
+                characters: [...itemText].length,
+                gap_ms: typeof lastSeg?.gap_ms === 'number' ? (lastSeg.gap_ms as number) : 1200,
+                text: itemText,
+            });
+        });
+
+        // closing
+        const closeIdx = sectionDefs.length;
+        const closePad = String(closeIdx).padStart(2, '0');
+        const closeSegs = [segments[segments.length - 1]];
+        const closeText = closeSegs.map((s) => String(s.text ?? '')).join('');
+        sectionDefs.push({
+            index: closeIdx,
+            role: 'closing',
+            stem: `${closePad}-closing`,
+            name: `${closePad}-closing`,
+            segments: closeSegs,
+            characters: [...closeText].length,
+            gap_ms:
+                typeof closeSegs[closeSegs.length - 1].gap_ms === 'number'
+                    ? (closeSegs[closeSegs.length - 1].gap_ms as number)
+                    : 300,
+            text: closeText,
+        });
+
+        // Character-rate estimate: section characters / driver rate + 8 s sting > the workflow's
+        // ceiling (`episode_max_minutes`, arg 8; default 20 for a bare five/six-argument call).
+        // The rates are MEASURED from shipped renders, not the style contract's prose. gemini-tts:
+        // 20261004 5466 chars / 1026 s = 5.33, 20261007 5970 / 1096 = 5.45, and the 0237 live dry run
+        // 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.
+        // 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
+        // driver changes model or speed.
+        const charRate = voiceGenerator === 'gemini-tts' ? 5.4 : 5.6;
+        const totalChars = sectionDefs.reduce((acc, s) => acc + s.characters, 0);
+        const estimatedSeconds = 8 + totalChars / charRate;
+        if (estimatedSeconds > maxMinutes * 60) {
+            const longest3 = [...sectionDefs].sort((a, b) => b.characters - a.characters).slice(0, 3);
+            failWith(
+                1,
+                `generate: character-rate estimate ${Math.round(estimatedSeconds / 60)} min exceeds ${maxMinutes} min limit (longest sections: ${longest3.map((s) => s.name).join(', ')})`,
+            );
+        }
+
+        const voiceProfile =
+            (typeof script.default_profile_id === 'string' && script.default_profile_id) ||
+            (typeof script.default_profile === 'string' && script.default_profile) ||
+            process.env.VOICEBOX_DEFAULT_PROFILE ||
+            'robin-news';
+
+        const secDir = join(workDir, '30-audio', 'sections', runDate);
+        mkdirSync(secDir, { recursive: true });
+
+        const joinedWavPath = join(workDir, '30-audio', `${runDate}_11_generate_content.wav`);
+        const joinedContentPath = join(workDir, '30-audio', `${runDate}_11_generate_content.json`);
+
+        interface SectionPlan {
+            def: SectionDef;
+            hash: string;
+            wavPath: string;
+            jsonPath: string;
+            needsSynthesis: boolean;
+        }
+
+        const computePlans = (driver: string): SectionPlan[] => {
+            return sectionDefs.map((def) => {
+                const hash = createHash('sha256').update(`${def.text}\0${voiceProfile}\0${driver}`).digest('hex');
+                const wavPath = join(secDir, `${def.stem}.wav`);
+                const jsonPath = join(secDir, `${def.stem}.json`);
+                let cached = false;
+                if (existsSync(wavPath) && existsSync(jsonPath)) {
+                    try {
+                        const sidecar = readJson(jsonPath) as Record<string, unknown>;
+                        const sidecarMeta = metadataOf(sidecar) as Record<string, unknown>;
+                        if (sidecar.hash === hash || sidecarMeta.hash === hash) {
+                            cached = true;
+                        }
+                    } catch {}
+                }
+                return {
+                    def,
+                    hash,
+                    wavPath,
+                    jsonPath,
+                    needsSynthesis: !cached,
+                };
+            });
+        };
+
+        let plans = computePlans(voiceGenerator);
+        const anySynthesisNeeded = plans.some((p) => p.needsSynthesis);
+
+        if (!anySynthesisNeeded && existsSync(joinedWavPath) && existsSync(joinedContentPath)) {
+            console.log('generate: all sections cached, joined speech reused');
+            return;
+        }
+
+        // Same quota probe as the one-shot path, before any section request. A fallback changes
+        // the cache key, so plans are recomputed and no Gemini file is played as voicebox speech.
+        if (
+            anySynthesisNeeded &&
+            vdriver === 'gemini' &&
+            !geminiQuotaProbeOk(workDir, pluginsPath, transcodeMp3, [
+                {
+                    id: 'probe',
+                    title: 'Probe',
+                    body: Bun.YAML.stringify({
+                        title: 'Probe',
+                        segments: [{ text: 'Hello.' }],
+                    }),
+                    sourceUri: 'file://probe',
+                    mediaType: 'application/yaml',
+                    metadata: { voiceProfile },
+                },
+            ])
+        ) {
+            voiceGenerator = VOICE_DRIVERS.voicebox;
+            plans = computePlans(voiceGenerator);
+        }
+
+        // Synthesize sections sequentially (concurrency 1)
+        for (const plan of plans) {
+            if (!plan.needsSynthesis) {
+                console.log(`generate: section cached: ${plan.def.stem}`);
+                continue;
+            }
+            console.log(`generate: synthesizing section: ${plan.def.stem}`);
+            const secScript = { ...script, segments: plan.def.segments };
+            const secDocIn = join(secDir, `.${plan.def.stem}_in.json`);
+            const doc = {
+                id: createHash('sha256').update(`section-${plan.def.stem}`).digest('hex').slice(0, 16),
+                title: `Daily AI News VoiceScript - ${plan.def.stem}`,
+                sourceUri: `file://${resolve(scriptPath)}#${plan.def.stem}`,
+                body: Bun.YAML.stringify(secScript),
+                mediaType: 'application/yaml',
+                metadata: { voiceProfile },
+            };
+            writeJsonText(secDocIn, [doc]);
+            try {
+                const 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}`);
+                }
+            } finally {
+                rmSync(secDocIn, { force: true });
+            }
+            try {
+                const sidecar = readJson(plan.jsonPath) as Record<string, unknown>;
+                sidecar.hash = plan.hash;
+                if (sidecar.metadata && typeof sidecar.metadata === 'object') {
+                    (sidecar.metadata as Record<string, unknown>).hash = plan.hash;
+                }
+                writeJsonText(plan.jsonPath, sidecar);
+            } catch {}
+        }
+
+        // Join sections with ffmpeg
+        const probeHelper = (file: string, entries: string): string =>
+            spawnSync('ffprobe', [
+                '-v',
+                'error',
+                '-select_streams',
+                'a:0',
+                '-show_entries',
+                entries,
+                '-of',
+                'csv=p=0',
+                file,
+            ])
+                .stdout?.toString()
+                .trim() ?? '';
+
+        const sampleRate = probeHelper(plans[0].wavPath, 'stream=sample_rate') || '24000';
+        const ffmpegArgs = ['-y', '-hide_banner', '-loglevel', 'error'];
+        const filterParts: string[] = [];
+        const concatInputs: string[] = [];
+
+        plans.forEach((plan, i) => {
+            ffmpegArgs.push('-i', plan.wavPath);
+            filterParts.push(`[${i}:a]aresample=${sampleRate},aformat=sample_fmts=s16:channel_layouts=mono[a${i}]`);
+            concatInputs.push(`[a${i}]`);
+            if (i < plans.length - 1) {
+                const gapMs = plan.def.gap_ms;
+                const gapS = gapMs > 0 ? (gapMs / 1000).toFixed(4) : '0';
+                filterParts.push(`anullsrc=r=${sampleRate}:cl=mono,atrim=duration=${gapS}[sil${i}]`);
+                concatInputs.push(`[sil${i}]`);
+            }
+        });
+
+        const filterComplex = `${filterParts.join(';')};${concatInputs.join('')}concat=n=${concatInputs.length}:v=0:a=1[out]`;
+        ffmpegArgs.push('-filter_complex', filterComplex, '-map', '[out]', '-c:a', 'pcm_s16le', joinedWavPath);
+
+        const conv = spawnSync('ffmpeg', ffmpegArgs);
+        if (conv.status !== 0 || !existsSync(joinedWavPath)) {
+            failWith(1, `generate: ffmpeg join failed: ${conv.stderr?.toString().trim()}`);
+        }
+
+        const joinedDuration = Number.parseFloat(probeHelper(joinedWavPath, 'format=duration'));
+
+        let contentObj: Record<string, unknown> = {};
+        if (existsSync(joinedContentPath)) {
+            try {
+                contentObj = readJson(joinedContentPath) as Record<string, unknown>;
+            } catch {}
+        }
+        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;
+        writeJsonText(joinedContentPath, contentObj);
     });
 }
 
@@ -573,16 +952,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(
@@ -593,6 +977,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`);
     });
@@ -783,18 +1168,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,
@@ -842,10 +1239,15 @@ export function dailyPublishWechat(args: string[]): void {
  * its own). Non-blocking by operator decision: a missing/expired XHS session or a changed console
  * logs a loud failure and leaves the run alive, and the outcome never enters `publish_status`
  * (surfdash + podcast remain the episode's publication contract).
+ *
+ * 0236: the optional trailing `<podcast>` arg (`'true'` from voice2 only) attaches the episode's
+ * 发播客 note to the same visit as `metadata.followUps` — one console visit, two notes, one cap entry
+ * (ADR-025 amendment 2026-10-09).
  */
 export function dailyPublishXhs(args: string[]): void {
-    const [workDir = '', runDate = '', pluginsPath = '', live = 'false'] = args;
+    const [workDir = '', runDate = '', pluginsPath = '', live = 'false', podcast = ''] = args;
     const content = join(workDir, '25-xhs', 'content.json');
+    const prep = join(workDir, '31-publish', `${runDate}_13_publish-prep_content.json`);
     const input = join(workDir, '31-publish', `${runDate}_19_publish-xhs_content.json`);
     const result = join(workDir, '31-publish', `${runDate}_19_publish-xhs_result.json`);
     const want = live === 'true' ? 'public' : 'draft';
@@ -854,6 +1256,17 @@ export function dailyPublishXhs(args: string[]): void {
         // xhs_live=true re-run (that would report a live post that never happened).
         if (resultPublishStatus(result) === want) {
             console.log(`publish-xhs cached: ${want} already recorded in ${result}`);
+            // 0236: the cache keys on the visit's primary note, so a 发播客 follow-up that failed in
+            // that visit is named here instead of hidden. It is not retried: a re-visit would post
+            // a second 图文 draft (the console has no idempotency key).
+            const followUps = metadataOf(readJson(result)).followUps;
+            for (const entry of Array.isArray(followUps) ? followUps : []) {
+                const step = (entry ?? {}) as Record<string, unknown>;
+                if (step.ok === true) continue;
+                console.log(
+                    `publish-xhs cached: follow-up ${String(metadataOf(step).operation ?? '?')} did not complete: ${String(step.error ?? 'no error recorded')}`,
+                );
+            }
             return;
         }
         if (!isFile(content)) {
@@ -861,8 +1274,16 @@ export function dailyPublishXhs(args: string[]): void {
             return;
         }
         const packaged = requireJson(content, 'publish-xhs');
+        const followUp = podcast === 'true' ? xhsPodcastNote(prep, want) : undefined;
         sted('write', input, () =>
-            writeJsonText(input, { ...packaged, metadata: { ...metadataOf(packaged), publishStatus: want } }),
+            writeJsonText(input, {
+                ...packaged,
+                metadata: {
+                    ...metadataOf(packaged),
+                    publishStatus: want,
+                    ...(followUp === undefined ? {} : { followUps: [followUp] }),
+                },
+            }),
         );
         // `soft` keeps the XHS target non-blocking: the plugin still writes its own failed Result
         // and prints the failing step (login gate, upload, body, submit control), which is what the
@@ -878,6 +1299,34 @@ export function dailyPublishXhs(args: string[]): void {
     });
 }
 
+/**
+ * 0236 R1: the 发播客 Content for the same episode — the run's publish-prep Content (the final mp3
+ * with the intro, `23-cover`'s PNG, title and body) plus `metadata.operation` and the run's own
+ * `publishStatus`. No artifact is produced here: both files already exist.
+ *
+ * `metadata.audio` repeats the prep's `metadata.audioFile` under the key the xhs channel's 发播客 mode
+ * reads (`xhs-pub/src/modes.ts`); `metadata.coverImage` is already the shared spelling. A run with no
+ * publish-prep output names the missing episode drafts and carries the 图文 note alone — the 发播客
+ * note is never invented.
+ */
+function xhsPodcastNote(prepPath: string, publishStatus: 'draft' | 'public'): Record<string, unknown> | undefined {
+    const prep = readJson(prepPath);
+    if (prep === null) {
+        console.log(`publish-xhs: no publish-prep Content at ${prepPath} — the 发播客 note is skipped`);
+        return undefined;
+    }
+    const metadata = metadataOf(prep);
+    return {
+        ...prep,
+        metadata: {
+            ...metadata,
+            operation: '发播客',
+            audio: metadata.audioFile,
+            publishStatus,
+        },
+    };
+}
+
 /**
  * WeChat MP: drive the console via `wechatmp-pub`'s browser transport and save the article to the
  * draft box (草稿箱). Draft by default; the 发表 flow runs only on an explicit launch-time
@@ -1167,8 +1616,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 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`);
@@ -1195,6 +1777,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 {
@@ -1249,8 +1832,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)) {
@@ -1290,9 +1895,8 @@ export function dailyShowNotes(args: string[]): void {
                 PODCAST_PUB_RUN_DATE: runDate,
                 PODCAST_PUB_BRIEF_MODE: 'true',
                 PODCAST_PUB_ARTICLE_POST_PATH: postPath,
-                // Task 0189 R1 / Apple §1.11: AI-voice disclosure in the episode metadata, not only
-                // in the audio sign-off and the article footer.
-                PODCAST_PUB_FOOTER_NOTE: '本期文字由 AI 辅助整理，音频为 AI 合成配音。',
+                // 2026-10-08: the column settings carry the AI-production note. Do not append the
+                // stock closer to show notes (or the article, or the spoken sign-off).
                 ...(isFile(audioContent) ? { PODCAST_PUB_AUDIO_CONTENT: audioContent } : {}),
             },
         });
@@ -1310,7 +1914,10 @@ export function dailyShowNotes(args: string[]): void {
  */
 export function dailyTranslateLocalize(args: string[]): void {
     const [workDir = '', runDate = '', pluginsPath = ''] = args;
-    const result = join(workDir, '31-publish', `${runDate}_17_publish_result.json`);
+    // Same seam as show-notes (task 0137): `_17_publish_result.json` is written later by
+    // publish-classify, which depends on translate-sync. Reading it here always saw no zh
+    // path, so en/ja were never scaffolded (2026-10-08 dogfood).
+    const result = join(workDir, '31-publish', `${runDate}_14_publish-surfdash_result.json`);
     const zhFile = join(workDir, '31-publish', `${runDate}_20_translate-localize_zh-post-path.txt`);
     timed(workDir, 'translate-localize', () => {
         const postPath = firstPostPath(readJson(result), 'surfdash-pub');
@@ -1408,12 +2015,99 @@ export function dailyWrapDocs(args: string[]): void {
     });
 }
 
+/** 0235 R4: `note_scope`'s one opt-in value. Anything else — absent included — is today's path. */
+const XHS_NOTE_SCOPE_EPISODE = 'episode';
+
+/**
+ * 0235 R2: `①` — the circled digits ①…⑳ are contiguous from here, and the episode note attaches
+ * `XHS_MAX_CARDS` cards plus at most one cover, so no bare number can ever be needed.
+ */
+const CIRCLED_DIGIT_ONE = 0x2460;
+
+/** The attach-order marker of line `position` (0-based). */
+const markerFor = (position: number): string => String.fromCodePoint(CIRCLED_DIGIT_ONE + position);
+
+/**
+ * 0235 R2: split the agent's note body into its lead paragraph and its trailing hashtag run. The
+ * prompt asks for 3-5 hashtags at the end, so the run is read off the end of the body; a body
+ * without hashtags is entirely lead.
+ */
+function splitNoteBody(body: string): { lead: string; hashtags: string } {
+    const trimmed = body.trim();
+    const match = /(?:^|\s)(#\S+(?:\s+#\S+)*)\s*$/.exec(trimmed);
+    if (match === null) return { lead: trimmed, hashtags: '' };
+    return { lead: trimmed.slice(0, match.index).trimEnd(), hashtags: match[1] ?? '' };
+}
+
+/**
+ * 0235 R2: the episode note body — the agent's lead paragraph, then one numbered line per attached
+ * image in attach order, then the plan's hashtags. `cap` is the console's own note limit
+ * (`XHS_NOTE_BODY_MAX`): only the lead is trimmed to fit, so an image never loses its line. A body
+ * that overflows even without a lead fails loud rather than shipping a note the editor would cut.
+ */
+function episodeNoteBody(body: string, lines: string[], cap: number): string {
+    const { lead, hashtags } = splitNoteBody(body);
+    const tail = [lines.join('\n'), hashtags].filter((part) => part !== '').join('\n\n');
+    // `\n\n` joins the lead to the tail; a lead trimmed away drops the separator with it.
+    const budget = cap - tail.length - (lead === '' ? 0 : 2);
+    const head = budget >= lead.length ? lead : lead.slice(0, Math.max(budget, 0)).trimEnd();
+    const note = head === '' ? tail : `${head}\n\n${tail}`;
+    if (note.length > cap) {
+        failWith(
+            1,
+            `xhs render: episode note body is ${note.length} chars for ${lines.length} image lines — the cap is ${cap} and a line is never dropped`,
+        );
+    }
+    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(['。', '！', '？']);
+
+/**
+ * 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
  * are pinned here (never model-authored), so the series cannot drift from its preset. Card copy
  * is typeset by image-gen's composer; the provider prompt stays text-free (0181). Resume-safe:
  * a card whose recorded artifact is still on disk is not re-rendered — and not re-billed.
+ *
+ * `note_scope` (`episode`, 0235) opts into the episode note for voice2: the packaged set then also
+ * attaches the episode cover last, and the body is rebuilt as the lead paragraph plus one numbered
+ * line per attached image. Absent or any other value: the lead-item series and the agent's body are
+ * packaged verbatim (voice1's contract).
  */
 export function dailyXhsRender(args: string[]): void {
     const [
@@ -1425,9 +2119,12 @@ export function dailyXhsRender(args: string[]): void {
         provider = '',
         model = '',
         fallback = '',
+        noteScope = '',
     ] = args;
     const count = Number.parseInt(countArg, 10);
+    const episode = noteScope === XHS_NOTE_SCOPE_EPISODE;
     const planPath = join(workDir, '25-xhs', `${runDate}_18_xhs_plan.json`);
+    const coverPath = join(workDir, '23-cover', `${runDate}_07_cover_cover.png`);
     const cardsDir = join(workDir, '25-xhs', 'cards');
     const manifestPath = join(workDir, '25-xhs', 'cards.json');
     const contentPath = join(workDir, '25-xhs', 'content.json');
@@ -1439,6 +2136,13 @@ export function dailyXhsRender(args: string[]): void {
         sted('mkdir', cardsDir, () => mkdirSync(cardsDir, { recursive: true }));
         const images: Record<string, unknown>[] = [];
         const cards: Record<string, unknown>[] = [];
+        // 0235 R2: the numbered lines are a pure function of the plan and the cover, in attach order
+        // (cards in plan order, the cover last), so the note — and its cap — is settled before the
+        // first card is billed: an over-cap tail fails here with nothing rendered.
+        const withCover = episode && isFile(coverPath);
+        const lines = plan.cards.map((card, i) => `${markerFor(i)} ${card.copy}：${card.points[0] ?? ''}`);
+        if (withCover) lines.push(`${markerFor(lines.length)} 每日AI乱炖 ${runDate} 本期封面`);
+        const body = episode ? episodeNoteBody(plan.body, lines, XHS_BODY_CAP) : plan.body;
         for (const card of plan.cards) {
             const out = join(cardsDir, `card-${card.index}.json`);
             const promptPath = join(cardsDir, `card-${card.index}.prompt.txt`);
@@ -1471,17 +2175,45 @@ 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 });
+                if (result.status !== 0) {
+                    // 0251 R1: retry ONCE, only on a points[n] safe-area overflow where at least one
+                    // named point got shorter. The envelope is rewritten in the same shape and
+                    // image-gen is called once more; a second failure takes the resume line.
+                    let shortened = false;
+                    for (const n of xhsOverflowPoints(result.stderr, card) ?? []) {
+                        const point = card.points[n] ?? '';
+                        const next = shortenOverflowedPoint(point);
+                        if (next !== point) {
+                            card.points[n] = next;
+                            shortened = true;
+                        }
+                    }
+                    if (shortened) {
+                        (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'));
             }
@@ -1514,19 +2246,34 @@ export function dailyXhsRender(args: string[]): void {
                 promptPath,
                 imagePath,
                 illustrationPath,
+                ...(card.itemId === undefined ? {} : { itemId: card.itemId }),
                 status: 'rendered',
             });
         }
+        // 0235 R1: the episode cover closes the set — it is ultrawide, and image 1 (card 01) is what
+        // sets the note's grid ratio. It is `daily-cover`'s own artifact (no new image kind), and
+        // the set is ≤ XHS_MAX_CARDS + 1 = 11, inside `xhs-pub`'s XHS_IMAGE_MAX (18).
+        if (withCover) {
+            images.push({ path: resolve(coverPath) });
+        } else if (episode) {
+            console.log(
+                `xhs render: no episode cover at ${coverPath} — the note carries the ${cards.length} cards only`,
+            );
+        }
         sted('write', manifestPath, () => writeJsonText(manifestPath, { source: planPath, cards }));
         sted('write', contentPath, () =>
             writeJsonText(contentPath, {
                 title: plan.title,
-                body: plan.body,
+                body,
                 format: 'text',
                 metadata: { images, publishStatus: 'draft' },
             }),
         );
-        console.log(`xhs render: ${cards.length} cards packaged in card order (${contentPath})`);
+        console.log(
+            episode
+                ? `xhs render: ${images.length} images packaged in image order (${contentPath})`
+                : `xhs render: ${cards.length} cards packaged in card order (${contentPath})`,
+        );
     });
 }