@gobing-ai/knowledge-kit 0.1.10 → 0.1.12

package/plugins/kk/publish-presets/daily-ai-voice-migration.json

@@ -0,0 +1,146 @@
+{
+    "schemaVersion": 1,
+    "name": "daily-ai-voice-migration",
+    "targets": [
+        {
+            "id": "surfdash.article",
+            "plugin": "surfdash-pub",
+            "operation": "post",
+            "variant": "article",
+            "tier": 0,
+            "window": "after-generate",
+            "mode": "draft",
+            "required": true
+        },
+        {
+            "id": "podcast.episode",
+            "plugin": "podcast-pub",
+            "operation": "episode",
+            "variant": "episode",
+            "tier": 0,
+            "window": "after-generate",
+            "mode": "draft",
+            "required": true
+        },
+        {
+            "id": "wechatmp.podcast",
+            "plugin": "wechatmp-pub",
+            "operation": "播客",
+            "variant": "episode",
+            "tier": 1,
+            "window": "after-generate",
+            "mode": "draft"
+        },
+        {
+            "id": "xhs.podcast",
+            "plugin": "xhs-pub",
+            "operation": "发播客",
+            "variant": "episode",
+            "tier": 1,
+            "window": "after-generate",
+            "mode": "draft"
+        },
+        {
+            "id": "wechatmp.article",
+            "plugin": "wechatmp-pub",
+            "operation": "文章",
+            "variant": "article",
+            "tier": 2,
+            "window": "after-generate",
+            "mode": "draft",
+            "options": {
+                "collection": "每日AI资讯"
+            }
+        },
+        {
+            "id": "xhs.article",
+            "plugin": "xhs-pub",
+            "operation": "写长文",
+            "variant": "article",
+            "tier": 2,
+            "window": "after-generate",
+            "mode": "dummy"
+        },
+        {
+            "id": "xhs.cards",
+            "plugin": "xhs-pub",
+            "operation": "上传图文",
+            "variant": "cards",
+            "tier": 3,
+            "window": "after-generate",
+            "mode": "off"
+        },
+        {
+            "id": "weibo.article",
+            "plugin": "weibo-pub",
+            "operation": "article",
+            "variant": "article",
+            "tier": 2,
+            "window": "cn-peak",
+            "mode": "draft"
+        },
+        {
+            "id": "x.article",
+            "plugin": "x-pub",
+            "operation": "article",
+            "variant": "article",
+            "tier": 2,
+            "window": "cn-peak",
+            "mode": "draft"
+        },
+        {
+            "id": "x.post",
+            "plugin": "x-pub",
+            "operation": "post",
+            "variant": "social:x",
+            "tier": 3,
+            "window": "overseas-rss",
+            "mode": "dummy"
+        },
+        {
+            "id": "weibo.post",
+            "plugin": "weibo-pub",
+            "operation": "post",
+            "variant": "social:weibo",
+            "tier": 3,
+            "window": "overseas-rss",
+            "mode": "dummy"
+        },
+        {
+            "id": "threads.post",
+            "plugin": "threads-pub",
+            "operation": "post",
+            "variant": "social:threads",
+            "tier": 3,
+            "window": "overseas-rss",
+            "mode": "dummy"
+        },
+        {
+            "id": "linkedin.post",
+            "plugin": "linkedin-pub",
+            "operation": "post",
+            "variant": "social:linkedin",
+            "tier": 3,
+            "window": "overseas-rss",
+            "mode": "dummy"
+        },
+        {
+            "id": "shipinhao.cards",
+            "plugin": "shipinhao-pub",
+            "operation": "图文",
+            "variant": "cards",
+            "tier": 3,
+            "window": "overseas-rss",
+            "mode": "off"
+        },
+        {
+            "id": "threads.images",
+            "plugin": "threads-pub",
+            "operation": "post-images",
+            "variant": "cards",
+            "tier": 3,
+            "window": "overseas-rss",
+            "mode": "off"
+        }
+    ]
+}

package/plugins/kk/publish-presets/daily-ai-voice.json

@@ -85,7 +85,7 @@
             "variant": "social:x",
             "tier": 3,
             "window": "overseas-rss",
-            "mode": "draft"
+            "mode": "dummy"
         },
         {
             "plugin": "weibo-pub",
@@ -93,7 +93,7 @@
             "variant": "social:weibo",
             "tier": 3,
             "window": "overseas-rss",
-            "mode": "draft"
+            "mode": "dummy"
         },
         {
             "plugin": "threads-pub",
@@ -101,7 +101,15 @@
             "variant": "social:threads",
             "tier": 3,
             "window": "overseas-rss",
-            "mode": "draft"
+            "mode": "dummy"
+        },
+        {
+            "plugin": "linkedin-pub",
+            "operation": "post",
+            "variant": "social:linkedin",
+            "tier": 3,
+            "window": "overseas-rss",
+            "mode": "dummy"
         },
         {
             "plugin": "shipinhao-pub",

package/plugins/kk/schedules/kk-collect.grok-bot.md.tmpl

@@ -0,0 +1,69 @@
+# kk-collect — Grok Bot cloud routine
+
+Rendered by `kk schedule render kk-collect --platform grok-bot --bot {{bot}} [--tz {{tz}}] [--cron {{cron}}]`;
+kk never creates the routine. **Operator action:** paste this definition into the Grok Bot's routine
+editor (https://docs.x.ai/grok-bot/skills-routines-and-automations) and create it there.
+
+The cloud boundary is ADR-044 (`docs/00_ADR.md`): `kk.db` never leaves the Mac — this routine runs
+store-free, browser-free work only, and pushes its output to the `kk-cloud-sync` branch for the Mac
+to import.
+
+## Owner Bot
+
+{{bot}}
+
+## Schedule
+
+`{{cron}}` in `{{tz}}` (the routine's schedule must match this expression and timezone).
+
+## Inputs
+
+- The Bot needs `kk` and `spur` (sp-bot-bootstrap) in its checkout, plus the three source plugins'
+  credentials (`aihot`, `last30days`, `horizon`) provided as Bot secrets.
+- Push access to the `kk-cloud-sync` branch (the Bot's GitHub connector).
+- The fan-in source list below is copied from `plugins/kk/workflows/kk-collect.yaml:116-121` —
+  update the rendered routine whenever that file's source list changes (drift hazard).
+
+## Steps
+
+1. `stamp="$(date -u +%Y%m%dT%H%MZ)"` (UTC, `YYYYMMDDTHHMMZ` — the kk-collect stamp format).
+2. `kk stage collect-prepare "$stamp" 10 "AI news" 6` — the store-free prefix: writes only
+   `.works/kk-collect/<stamp>` and `.spur/runs/kk-collect/*`, touching no database.
+3. Fan-in the three sources (no `kk store` — the output file IS the artifact):
+   ```bash
+   work_dir="$(cat .spur/runs/kk-collect/work-dir.txt)"
+   kk executor fan-in \
+     --source "aihot-ingest:${work_dir}/10-ingest/source.json" \
+     --source "last30days-ingest:${work_dir}/10-ingest/last30days.json" \
+     --source "horizon-ingest:${work_dir}/10-ingest/horizon.json" \
+     --source-timeout-override "horizon-ingest:2700000" \
+     --out "sync/kk-collect/$stamp.json"
+   ```
+4. Commit `sync/kk-collect/$stamp.json` and push it to the `kk-cloud-sync` branch.
+
+## Expected result
+
+`sync/kk-collect/<stamp>.json` on `kk-cloud-sync`, a blended `Doc[]` from the three sources, with
+`<stamp>` equal to the run's UTC minute stamp.
+
+## Approval boundary
+
+Collect only — the routine never runs `kk store`, `kk store label`, a generator or a publisher, and
+it never installs anything itself; creating the routine in the Grok Bot is an explicit operator
+action. Publishing stays Mac-local under ADR-022's live-publish consent gate.
+
+## Missing / stale (ADR-044)
+
+| Situation | Behavior |
+| --------- | -------- |
+| Inputs or credentials missing at run time | print `no-content: <reason>` and exit with no side effects — in particular, no empty artifact is committed |
+| Artifact older than 26 h when the Mac imports | the Mac's `kk store ingest` ignores it (logged) |
+| Same artifact seen again | imported at most once — idempotent by the `cloud-<stamp>` run id |
+
+## Mac import
+
+```bash
+git fetch origin kk-cloud-sync
+git show origin/kk-cloud-sync:sync/kk-collect/<stamp>.json > /tmp/kk-collect-cloud.json
+kk store ingest --run cloud-<stamp> --in /tmp/kk-collect-cloud.json
+```

package/plugins/kk/schedules/kk-daily-ai-voice3.cron.tmpl

@@ -0,0 +1,18 @@
+# kk-daily-ai-voice3 — shadow generation run (task 0334 R1/R6).
+#
+# 04:30 America/Los_Angeles, the same cadence as the voice2 daily run it shadows. The entry is
+# defined in the zone the machine already runs in, so it needs no DST adjustment.
+#
+# Shadow posture is baked into the launch: `auto_publish` stays false, so this entry only
+# prepares, researches and generates — it publishes NOTHING on its own. The nested publish3
+# window runs only when an operator launch flips `publish_window` away from `after-generate`
+# (rehearsal flags in docs/design/kk-daily-ai-voice3.md). The workspace namespace stays
+# kk-daily-ai-voice2 (voice3 prepares under it) until the operator's cutover changes it.
+#
+# Rendered by `kk schedule render kk-daily-ai-voice3 --platform cron --repo <checkout>`;
+# kk never edits the operator's crontab. MERGE, never replace:
+#
+#     crontab -l > /tmp/kk-voice3.cron 2>/dev/null || :
+#     kk schedule render kk-daily-ai-voice3 --platform cron --repo "$PWD" >> /tmp/kk-voice3.cron
+#     crontab /tmp/kk-voice3.cron
+30 4 * * * cd {{repo}} && mkdir -p .works/kk-daily-ai-voice3 && PATH="{{home}}/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin" TZ=America/Los_Angeles spur workflow run plugins/kk/workflows/kk-daily-ai-voice3.yaml --vars '{"auto_publish":"false"}' >> {{repo}}/.works/kk-daily-ai-voice3/generation.log 2>&1

package/plugins/kk/schedules/kk-daily-publish3-cn-peak.cron.tmpl

@@ -1,4 +1,4 @@
-# kk-daily-publish3-cn-peak — domestic live window (task 0323 R5).
+# kk-daily-publish3-cn-peak — domestic live window (tasks 0323 R5, 0334 R1-R3).
 #
 # Fires at 17:00 local because the audience window is 09:00 Asia/Shanghai and launchd/cron
 # intervals follow the MACHINE's zone; the first node (`publish-matrix-wait-until 09:00
@@ -6,7 +6,17 @@
 # so the entry never needs editing twice a year.
 #
 # `live_channels` is baked in: this installed line IS the operator's ADR-022 consent for a live
-# send. Nothing in the workflow or the preset can produce `live` on its own.
+# send. Nothing in the workflow or the preset can produce `live` on its own. The window is
+# consent-scoped to tokens with a cn-peak row (weibo-pub, x-pub — both draft). Every live launch
+# stops at the `send-confirm` gate and waits for the operator's manual resume; the entry never
+# delivers unattended.
+#
+# The launch goes through plugins/kk/scripts/voice3-publish-window.ts (task 0334): a crontab
+# command ends at the first UNESCAPED percent sign, so inline `date +%F` shell silently truncates
+# the entry — the launcher owns the LA date math, resolves the GENERATION bundle from the
+# effective works root (never the publish3 output directory), refuses a missing/mismatched
+# bundle, validates the token list against the preset's cn-peak rows, and only then execs spur.
+# The rehearsal pins the shipped default preset; change it at cutover.
 #
 # Rendered by `kk schedule render kk-daily-publish3-cn-peak --platform cron --repo <checkout>`;
 # kk never edits the operator's crontab. MERGE, never replace:
@@ -15,6 +25,6 @@
 #     kk schedule render kk-daily-publish3-cn-peak --platform cron --repo "$PWD" >> /tmp/kk-cn-peak.cron
 #     crontab /tmp/kk-cn-peak.cron
 #
-# `run_date` is computed at tick time in America/Los_Angeles: a run that starts at 17:00 PDT is
-# still "today" for the day dir the 04:30 generation wrote.
-0 17 * * * cd {{repo}} && mkdir -p .works/kk-daily-publish3 && PATH="{{home}}/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin" TZ=America/Los_Angeles spur workflow run plugins/kk/workflows/kk-daily-publish3.yaml --vars "{\"work_dir\":\"{{repo}}/.works/kk-daily-publish3/$(TZ=America/Los_Angeles date +%Y%m%d)\",\"run_date\":\"$(TZ=America/Los_Angeles date +%F)\",\"window\":\"cn-peak\",\"live_channels\":\"wechatmp-pub,xhs-pub,weibo-pub,x-pub\"}" >> {{repo}}/.works/kk-daily-publish3/cn-peak.log 2>&1
+# `run_date` is computed at tick time in America/Los_Angeles by the launcher: a run that starts
+# at 17:00 PDT is still "today" for the day dir the 04:30 generation wrote.
+0 17 * * * cd {{repo}} && mkdir -p .works/kk-daily-publish3 && PATH="{{home}}/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin" TZ=America/Los_Angeles bun {{repo}}/plugins/kk/scripts/voice3-publish-window.ts --window cn-peak --preset daily-ai-voice --live-channels weibo-pub,x-pub >> {{repo}}/.works/kk-daily-publish3/cn-peak.log 2>&1

package/plugins/kk/schedules/kk-daily-publish3-overseas.cron.tmpl

@@ -1,17 +1,22 @@
-# kk-daily-publish3-overseas — overseas window behind the podcast RSS gate (task 0323 R5).
+# kk-daily-publish3-overseas — overseas window behind the podcast RSS gate (tasks 0323 R5, 0334 R1-R2).
 #
 # 07:00 America/Los_Angeles, which needs no DST adjustment: the entry is defined in the zone the
 # machine already runs in. The gated date is the PREVIOUS day, because the observed episodes land
-# 13:43–15:22 PDT (after this tick) — `run_date` is therefore yesterday's date, not today's.
+# 13:43–15:22 PDT (after this tick) — the launcher derives yesterday's LA date for `run_date`.
 #
 # The gate decides whether anything publishes: a miss cancels the overseas targets and runs
-# `diagnose` + the tier-0-only repair. This line carries no `live_channels`; the overseas channels
+# `diagnose` + the tier-0-only repair. This line carries no live consent; the overseas channels
 # in the shipped preset are `draft`, so a live overseas post stays an operator launch.
 #
+# plugins/kk/scripts/voice3-publish-window.ts (task 0334) owns the date math because a crontab
+# command ends at the first UNESCAPED percent sign — the old inline `date -v-1d +%Y%m%d` shell
+# truncated silently. The launcher resolves the GENERATION bundle (voice2 namespace, effective
+# works root) and refuses a missing/mismatched bundle before any spur process starts.
+#
 # Rendered by `kk schedule render kk-daily-publish3-overseas --platform cron --repo <checkout>`;
 # kk never edits the operator's crontab. MERGE, never replace:
 #
 #     crontab -l > /tmp/kk-overseas.cron 2>/dev/null || :
 #     kk schedule render kk-daily-publish3-overseas --platform cron --repo "$PWD" >> /tmp/kk-overseas.cron
 #     crontab /tmp/kk-overseas.cron
-0 7 * * * cd {{repo}} && mkdir -p .works/kk-daily-publish3 && PATH="{{home}}/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin" TZ=America/Los_Angeles spur workflow run plugins/kk/workflows/kk-daily-publish3.yaml --vars "{\"work_dir\":\"{{repo}}/.works/kk-daily-publish3/$(TZ=America/Los_Angeles date -v-1d +%Y%m%d 2>/dev/null || TZ=America/Los_Angeles date -d yesterday +%Y%m%d)\",\"run_date\":\"$(TZ=America/Los_Angeles date -v-1d +%F 2>/dev/null || TZ=America/Los_Angeles date -d yesterday +%F)\",\"window\":\"overseas-rss\"}" >> {{repo}}/.works/kk-daily-publish3/overseas.log 2>&1
+0 7 * * * cd {{repo}} && mkdir -p .works/kk-daily-publish3 && PATH="{{home}}/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin" TZ=America/Los_Angeles bun {{repo}}/plugins/kk/scripts/voice3-publish-window.ts --window overseas-rss >> {{repo}}/.works/kk-daily-publish3/overseas.log 2>&1

package/plugins/kk/scripts/daily-scheduled-run.ts

@@ -0,0 +1,298 @@
+#!/usr/bin/env bun
+/** Supervise one scheduled daily run and persist its terminal outcome even after a deadline. */
+import { spawn, spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+
+const { values } = parseArgs({
+    options: {
+        repo: { type: 'string', default: process.cwd() },
+        'works-dir': { type: 'string' },
+        'run-id': { type: 'string' },
+        'timeout-ms': { type: 'string', default: '13500000' },
+        receipt: { type: 'string' },
+        agent: { type: 'string', default: 'inline' },
+        'retry-agent': { type: 'string', default: 'claude' },
+        'required-channels': { type: 'string', default: 'wechat,locales,cms-resync' },
+        'wechat-live': { type: 'boolean', default: false },
+    },
+});
+const timeoutMs = Number(values['timeout-ms']);
+if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+    console.error('daily-scheduled-run: --timeout-ms must be a positive integer');
+    process.exit(2);
+}
+const repo = resolve(values.repo);
+const now = new Date();
+const stamp = `${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, '0')}${String(now.getDate()).padStart(2, '0')}`;
+const runId = values['run-id'] ?? `daily-ai-voice-${stamp}-${now.getTime()}`;
+const workDir = join(resolve(values['works-dir'] ?? join(repo, '.works')), 'kk-daily-ai-voice2', stamp);
+const receiptPath = resolve(values.receipt ?? join(workDir, 'schedule-receipt.json'));
+const startedAt = now.toISOString();
+mkdirSync(dirname(receiptPath), { recursive: true });
+const vars = {
+    publish_enabled: 'true',
+    skip_review: 'true',
+    agent: values.agent,
+    agent_retry: values['retry-agent'],
+    wechat_live: values['wechat-live'] === true ? 'true' : 'false',
+    work_dir: workDir,
+    run_date: stamp,
+};
+writeFileSync(receiptPath, JSON.stringify({ runId, startedAt, status: 'running', workDir }, null, 2));
+let interrupted = false;
+let timedOut = false;
+let spawnError = '';
+let forceKill: ReturnType<typeof setTimeout> | undefined;
+const child = spawn(
+    'spur',
+    [
+        '--no-logo',
+        'workflow',
+        'run',
+        'plugins/kk/workflows/kk-daily-ai-voice2.yaml',
+        '--run-id',
+        runId,
+        '--vars',
+        JSON.stringify(vars),
+        '--quiet',
+    ],
+    { cwd: repo, detached: true, stdio: 'inherit' },
+);
+
+const ownedPids = new Set<number>();
+/** Snapshot descendants before the root exits, including workers that created their own groups. */
+function rememberDescendants(): void {
+    if (child.pid === undefined) return;
+    ownedPids.add(child.pid);
+    const snapshot = spawnSync('ps', ['-axo', 'pid=,ppid='], { encoding: 'utf-8', timeout: 5000 });
+    const rows = snapshot.stdout
+        .trim()
+        .split('\n')
+        .map((line) => line.trim().split(/\s+/).map(Number));
+    const descendants = new Set([child.pid]);
+    let added = true;
+    while (added) {
+        added = false;
+        for (const [pid, parent] of rows) {
+            if (pid !== undefined && parent !== undefined && descendants.has(parent) && !descendants.has(pid)) {
+                descendants.add(pid);
+                added = true;
+            }
+        }
+    }
+    for (const pid of descendants) ownedPids.add(pid);
+}
+
+/** Stop only the recorded owned tree; process-group signals also catch late same-group forks. */
+function signalOwned(signal: NodeJS.Signals): void {
+    if (child.pid === undefined) return;
+    rememberDescendants();
+    for (const pid of [...ownedPids].reverse()) {
+        try {
+            process.kill(-pid, signal);
+        } catch {}
+        try {
+            process.kill(pid, signal);
+        } catch {}
+    }
+}
+
+function terminate(): void {
+    signalOwned('SIGTERM');
+    if (forceKill === undefined) {
+        forceKill = setTimeout(() => {
+            signalOwned('SIGKILL');
+        }, 300);
+    }
+}
+const onSignal = (): void => {
+    interrupted = true;
+    terminate();
+};
+process.once('SIGTERM', onSignal);
+process.once('SIGINT', onSignal);
+const deadline = setTimeout(() => {
+    timedOut = true;
+    terminate();
+}, timeoutMs);
+const exitCode = await new Promise<number>((done) => {
+    child.once('error', (error) => {
+        spawnError = error.message;
+        done(1);
+    });
+    child.once('close', (code) => done(code ?? 1));
+});
+clearTimeout(deadline);
+if (forceKill !== undefined) clearTimeout(forceKill);
+// A killed shell can leave owned descendants that ignore TERM. Always finish the group before
+// recording a terminal outcome; no detached grandchild may continue to publish after a timeout.
+if (child.pid !== undefined && (timedOut || interrupted || exitCode !== 0)) {
+    terminate();
+    await Bun.sleep(300);
+    signalOwned('SIGKILL');
+    await Bun.sleep(100);
+}
+const workflowStatus = timedOut ? 'timed-out' : interrupted ? 'interrupted' : exitCode === 0 ? 'done' : 'failed';
+const primaryPublishStatus = readOptional(join(workDir, '31-publish', `${stamp}_17_publish_publish-status.txt`));
+const runSummary = readOptional(join(workDir, 'run-report.summary.txt'));
+const cleanup: { command: string; exitCode: number | null }[] = [];
+let reservationRecovery: { status: string; reason: string; released?: number } = {
+    status: 'retained',
+    reason: 'workflow completed; publication settlement owns its reservations',
+};
+if (workflowStatus !== 'done' || runSummary?.startsWith('no-content:')) {
+    // The caller gives the nested safety run this exact id. Unknown/already-terminal ids are
+    // harmless cleanup failures; they never override the original workflow failure.
+    if (workflowStatus !== 'done') {
+        for (const id of [`${runId}-safety`, runId]) {
+            const result = spawnSync('spur', ['workflow', 'cancel', id, '--json'], {
+                cwd: repo,
+                encoding: 'utf-8',
+                timeout: 20000,
+            });
+            cleanup.push({ command: `spur workflow cancel ${id}`, exitCode: result.status });
+        }
+    }
+    // Only a complete trace proving no channel send began permits recycling reservations. A
+    // missing receipt alone is insufficient: a remote send may have succeeded before it crashed.
+    const trace = spawnSync('spur', ['workflow', 'trace', runId, '--json'], {
+        cwd: repo,
+        encoding: 'utf-8',
+        timeout: 20000,
+    });
+    reservationRecovery = { status: 'retained', reason: 'publication state could not be established' };
+    try {
+        const parsed = JSON.parse(trace.stdout) as {
+            run?: { runId?: string; workflowName?: string; status?: string; startedAt?: string };
+            events?: { kind?: string; node?: string; status?: string }[];
+        };
+        const sendNodes = new Set([
+            'publish-surfdash',
+            'publish-podcast',
+            'xhs-publish',
+            'wechat-publish',
+            'translate-localize',
+            'translate',
+            'translate-retry',
+            'translate-sync',
+            'publish-classify',
+        ]);
+        const validTrace =
+            trace.status === 0 &&
+            parsed.run?.runId === runId &&
+            parsed.run?.workflowName === 'kk-daily-ai-voice2' &&
+            parsed.run?.status === (workflowStatus === 'done' ? 'done' : 'failed') &&
+            Date.parse(parsed.run.startedAt ?? '') >= Date.parse(startedAt) - 1000 &&
+            Date.parse(parsed.run.startedAt ?? '') <= Date.now() &&
+            Array.isArray(parsed.events) &&
+            parsed.events.length > 0;
+        const sendStarted = parsed.events?.some(
+            (event) => event.kind === 'action' && sendNodes.has(event.node ?? '') && event.status !== 'skipped',
+        );
+        if (validTrace && !sendStarted) {
+            // Cancellation is durable before reuse. Require a second stable snapshot after the
+            // owned processes are gone, so an in-flight or partially finalized row cannot pass.
+            await Bun.sleep(200);
+            const secondTrace = spawnSync('spur', ['workflow', 'trace', runId, '--json'], {
+                cwd: repo,
+                encoding: 'utf-8',
+                timeout: 20000,
+            });
+            const second = JSON.parse(secondTrace.stdout) as typeof parsed;
+            if (
+                secondTrace.status !== 0 ||
+                JSON.stringify(second.run) !== JSON.stringify(parsed.run) ||
+                JSON.stringify(second.events) !== JSON.stringify(parsed.events)
+            ) {
+                throw new Error('failed-run trace is not stable after cancellation');
+            }
+            const release = spawnSync('kk', ['store', 'release', '--topic', 'ai-news', '--run', runId], {
+                cwd: repo,
+                encoding: 'utf-8',
+                timeout: 20000,
+            });
+            cleanup.push({ command: 'kk store release (verified pre-publication failure)', exitCode: release.status });
+            const result = release.status === 0 ? (JSON.parse(release.stdout) as { released?: unknown }) : null;
+            reservationRecovery =
+                result !== null && typeof result.released === 'number'
+                    ? { status: 'released', reason: 'trace proves no channel send began', released: result.released }
+                    : { status: 'retained', reason: 'reservation release did not produce a valid receipt' };
+        } else if (sendStarted) {
+            reservationRecovery = { status: 'retained', reason: 'a channel send began; preserve uncertain delivery' };
+        }
+    } catch {
+        // Unreadable/truncated evidence or an unexpected CLI shape must never cause reuse of a
+        // potentially aired story. Keep the reservation and the original failure visible.
+    }
+}
+const ledger = spawnSync('kk', ['ledger', 'sync', '--workflow', 'kk-daily-ai-voice2', '--work-dir', workDir], {
+    cwd: repo,
+    encoding: 'utf-8',
+    timeout: 20000,
+});
+cleanup.push({ command: 'kk ledger sync', exitCode: ledger.status });
+function readOptional(path: string): string | null {
+    try {
+        return readFileSync(path, 'utf-8').trim();
+    } catch {
+        return null;
+    }
+}
+const requiredChannels = values['required-channels']
+    .split(',')
+    .map((channel) => channel.trim())
+    .filter(Boolean);
+let channelCompleteness: { channel: string; state: string; detail?: string }[] = [];
+try {
+    const parsed = JSON.parse(
+        readOptional(join(workDir, '31-publish', `${stamp}_17_publish_completeness.json`)) ?? 'null',
+    ) as { rows?: unknown } | null;
+    if (Array.isArray(parsed?.rows)) {
+        channelCompleteness = parsed.rows.filter(
+            (row): row is { channel: string; state: string; detail?: string } =>
+                row !== null &&
+                typeof row === 'object' &&
+                typeof row.channel === 'string' &&
+                typeof row.state === 'string',
+        );
+    }
+} catch {}
+const missingRequiredChannels = requiredChannels.filter((channel) => {
+    const rows = channelCompleteness.filter((row) => row.channel === channel);
+    return rows.length !== 1 || rows[0]?.state !== 'done';
+});
+// A terminal green workflow can mean "no content" or failed delivery. Make that observable to
+// the scheduler instead of equating the workflow's process exit with a published edition.
+const status =
+    workflowStatus !== 'done'
+        ? workflowStatus
+        : runSummary?.startsWith('no-content:')
+          ? 'no-content'
+          : primaryPublishStatus === 'full' && missingRequiredChannels.length === 0
+            ? 'done'
+            : 'incomplete';
+const receipt = {
+    runId,
+    startedAt,
+    completedAt: new Date().toISOString(),
+    status,
+    exitCode: timedOut ? 124 : interrupted ? 143 : exitCode !== 0 ? exitCode : status === 'done' ? 0 : 4,
+    workDir,
+    timeoutMs,
+    agent: values.agent,
+    retryAgent: values['retry-agent'],
+    error: spawnError || null,
+    primaryPublishStatus,
+    channelCompleteness,
+    missingRequiredChannels,
+    runSummary,
+    reservationRecovery,
+    cleanup,
+};
+writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+console.log(JSON.stringify(receipt));
+process.removeListener('SIGTERM', onSignal);
+process.removeListener('SIGINT', onSignal);
+process.exit(receipt.exitCode);