@gobing-ai/knowledge-kit 0.0.18 → 0.0.19

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
     },
     "plugins": [
         {
-            "version": "0.0.18",
+            "version": "0.0.19",
             "name": "kk",
             "source": "./plugins/kk",
             "description": "knowledge-kit — a set of toolkit for knowledge management"

package/dist/index.js

@@ -26420,24 +26420,38 @@ function spawnPluginEntry(opts) {
     stderr: proc.stderr.toString().trim()
   };
 }
-function killProcessTree(pid) {
+var KILL_TREE_SETTLE_MS = 100;
+function listChildren(pid) {
   let stdout;
   try {
     stdout = Bun.spawnSync(["pgrep", "-P", String(pid)]).stdout.toString();
   } catch {
     stdout = "";
   }
-  for (const line of stdout.trim().split(`
-`)) {
-    const child = Number(line);
-    if (Number.isInteger(child) && child > 0) {
-      killProcessTree(child);
-    }
+  return stdout.trim().split(`
+`).map(Number).filter((child) => Number.isInteger(child) && child > 0);
+}
+function killSubtree(pid) {
+  for (const child of listChildren(pid)) {
+    killSubtree(child);
   }
   try {
     process.kill(pid, "SIGKILL");
   } catch {}
 }
+async function killProcessTree(pid) {
+  const sweep = () => {
+    for (const child of listChildren(pid)) {
+      killSubtree(child);
+    }
+  };
+  sweep();
+  await Bun.sleep(KILL_TREE_SETTLE_MS);
+  sweep();
+  try {
+    process.kill(pid, "SIGKILL");
+  } catch {}
+}
 async function spawnPluginEntryAsync(opts) {
   let timedOut = false;
   let timer;
@@ -27445,6 +27459,46 @@ function registerPluginCommand(program2) {
   registerStatusVerb(plugins, "doctor", "Alias for `plugin status` (deprecated)", true);
 }
 
+// src/stage.ts
+import { spawnSync } from "child_process";
+import { existsSync as existsSync5, realpathSync as realpathSync3 } from "fs";
+import { dirname as dirname3, join as join5, resolve as resolve6 } from "path";
+var STAGES_REL = "plugins/kk/scripts/kk-workflow-stages.ts";
+function resolveStagesScript(argv1 = process.argv[1]) {
+  let fromPkg = "";
+  if (argv1) {
+    try {
+      fromPkg = join5(dirname3(dirname3(realpathSync3(argv1))), STAGES_REL);
+    } catch {
+      fromPkg = "";
+    }
+  }
+  if (fromPkg && existsSync5(fromPkg))
+    return fromPkg;
+  const fromCwd = resolve6(STAGES_REL);
+  if (existsSync5(fromCwd))
+    return fromCwd;
+  throw new Error(`kk-workflow-stages.ts not found at ${fromPkg || STAGES_REL} \u2014 install or refresh the kk package (bun link in a checkout)`);
+}
+function runStage(args, execPath = process.execPath, argv1) {
+  const script = resolveStagesScript(argv1);
+  const res = spawnSync(execPath, [script, ...args], { stdio: "inherit" });
+  if (res.error) {
+    throw new Error(`failed to spawn stage runner at ${script}: ${res.error.message}`);
+  }
+  return res.status ?? 1;
+}
+
+// src/commands/stage.ts
+function registerStageCommand(program2) {
+  program2.command("stage").description("Run a kk-workflow-stages.ts stage (workflow orchestration steps)").argument("<args...>", "Stage name followed by its positional arguments").allowUnknownOption(true).action((args) => {
+    const code = runStage(args);
+    if (code !== 0) {
+      throw new CommanderError(code, "kk.stage.failed", `stage failed with exit code ${code}`);
+    }
+  });
+}
+
 // src/config.ts
 import { readFileSync as readFileSync4 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
@@ -27460,6 +27514,7 @@ function createProgram() {
   const program2 = new Command().name(CLI_CONFIG.binaryName).description("knowledge-kit CLI").version(CLI_CONFIG.binaryVersion).option("-v, --verbose", "enable verbose diagnostics");
   registerExecutorCommand(program2);
   registerPluginCommand(program2);
+  registerStageCommand(program2);
   return program2;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/knowledge-kit",
-    "version": "0.0.18",
+    "version": "0.0.19",
     "description": "An ingest → create → publish content pipeline CLI (Bun).",
     "repository": {
         "type": "git",

package/plugins/generations/voice-gen/dist/index.js

@@ -21744,7 +21744,7 @@ function findProjectRoot(startDir) {
 var init_file_system_node = () => {};
 
 // ../../plugins/generations/voice-gen/src/index.ts
-import { basename, dirname as dirname2, extname, join, resolve } from "path";
+import { basename, dirname as dirname2, extname, join as join2, resolve } from "path";
 import { parseArgs } from "util";
 
 // ../../packages/kk-core/src/kinds.ts
@@ -22413,6 +22413,60 @@ function createVoiceboxClient(options = {}) {
   };
 }
 
+// ../../plugins/generations/voice-gen/src/voicebox-server.ts
+import { spawn as nodeSpawn } from "child_process";
+import { existsSync as existsSync2, openSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var BOOT_WAIT_MS = 30000;
+var POLL_MS = 500;
+var LOG_PATH = "/tmp/voicebox-server.log";
+async function probeVoiceboxHealth(url2, customFetch) {
+  try {
+    return (await customFetch(`${url2}/health`)).ok;
+  } catch {
+    return false;
+  }
+}
+async function ensureVoiceboxRunning(options = {}) {
+  const rawUrl = options.url ?? process.env.VOICEBOX_URL ?? "http://127.0.0.1:17493";
+  const customFetch = options.fetch ?? fetch;
+  const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const customSpawn = options.spawn ?? nodeSpawn;
+  if (await probeVoiceboxHealth(rawUrl, customFetch)) {
+    return;
+  }
+  const url2 = new URL(rawUrl);
+  const local = ["127.0.0.1", "localhost", "::1"].includes(url2.hostname);
+  if (!local) {
+    throw new Error(`voice-gen: Voicebox not reachable at ${rawUrl} \u2014 auto-start only applies to local URLs; is the remote server up? (fix VOICEBOX_URL)`);
+  }
+  const serverBin = options.serverBin ?? process.env.VOICEBOX_SERVER_BIN ?? "/Applications/Voicebox.app/Contents/MacOS/voicebox-server";
+  if (!existsSync2(serverBin)) {
+    throw new Error(`voice-gen: Voicebox not reachable at ${rawUrl} and VOICEBOX_SERVER_BIN is missing (${serverBin}) \u2014 start Voicebox.app or set VOICEBOX_SERVER_BIN`);
+  }
+  const dataDir = options.dataDir ?? process.env.VOICEBOX_DATA_DIR ?? join(homedir(), "Library/Application Support/sh.voicebox.app");
+  const logPath = options.logPath ?? LOG_PATH;
+  const port = url2.port === "" ? 17493 : Number(url2.port);
+  echoError(`voice-gen: Voicebox not reachable at ${rawUrl} \u2014 auto-starting ${serverBin} (log: ${logPath})`);
+  const child = customSpawn(serverBin, ["--port", String(port), "--data-dir", dataDir], {
+    detached: true,
+    stdio: ["ignore", "ignore", openSync(logPath, "a")]
+  });
+  child.unref?.();
+  const bootWaitMs = options.bootWaitMs ?? BOOT_WAIT_MS;
+  const pollMs = options.pollMs ?? POLL_MS;
+  const deadline = Date.now() + bootWaitMs;
+  while (Date.now() < deadline) {
+    await sleep(pollMs);
+    if (await probeVoiceboxHealth(rawUrl, customFetch)) {
+      echoError(`voice-gen: Voicebox ready at ${rawUrl}`);
+      return;
+    }
+  }
+  throw new Error(`voice-gen: Voicebox did not become healthy at ${rawUrl} within ${bootWaitMs}ms of auto-start \u2014 check ${logPath}`);
+}
+
 // ../../plugins/generations/voice-gen/src/voicescript.ts
 var VOICEBOX_TEXT_MAX = 50000;
 var VOICEBOX_INSTRUCT_MAX = 500;
@@ -22821,8 +22875,8 @@ async function processGeneratorIO(inputPath, outputPath, clientOverride, transco
   const fs = createNodeFileSystem();
   const outDir = dirname2(outputPath);
   const outStem = basename(outputPath, extname(outputPath));
-  const audioPath = resolve(join(outDir, `${outStem}.wav`));
-  const mp3Path = resolve(join(outDir, `${outStem}.mp3`));
+  const audioPath = resolve(join2(outDir, `${outStem}.wav`));
+  const mp3Path = resolve(join2(outDir, `${outStem}.mp3`));
   const wantMp3 = isMp3Requested();
   await fs.deleteFile(outputPath);
   await fs.deleteFile(audioPath);
@@ -22840,6 +22894,9 @@ async function processGeneratorIO(inputPath, outputPath, clientOverride, transco
     return;
   }
   const client = clientOverride ?? createVoiceboxClient();
+  if (!clientOverride) {
+    await ensureVoiceboxRunning();
+  }
   try {
     await client.health();
     const envDefaultProfile = process.env.VOICEBOX_DEFAULT_PROFILE;

package/plugins/generations/voice-gen/src/index.ts

@@ -7,6 +7,7 @@ import { applySpeed, concatWavs } from './concat';
 import { isMp3Requested, type Mp3Transcoder, transcodeWavToMp3 } from './mp3';
 import { auditVoiceSegments, detectLoudnessDip, TRANSCRIPTION_FIDELITY_FLOOR, transcriptionFidelity } from './qc';
 import { createVoiceboxClient, type VoiceboxClient, type VoiceboxGenerateBody } from './voicebox-client';
+import { ensureVoiceboxRunning } from './voicebox-server';
 import {
     mergeVoiceScripts,
     parseDocToVoiceScript,
@@ -71,6 +72,13 @@ export async function processGeneratorIO(
 
     const client = clientOverride ?? createVoiceboxClient();
 
+    // Auto-start the local server when it is down — only on the default client path;
+    // tests inject clientOverride and skip the spawn entirely. With vdriver=ominivoice
+    // (the default) this plugin never runs, so no server is needed at all.
+    if (!clientOverride) {
+        await ensureVoiceboxRunning();
+    }
+
     try {
         // 1. Health check
         await client.health();

package/plugins/generations/voice-gen/src/voicebox-server.ts

@@ -0,0 +1,91 @@
+import { type ChildProcess, spawn as nodeSpawn } from 'node:child_process';
+import { existsSync, openSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { echoError } from '@gobing-ai/ts-utils';
+
+/** Boot wait / poll cadence for a freshly spawned local server (Voicebox cold start ≈ 2-5s). */
+const BOOT_WAIT_MS = 30_000;
+const POLL_MS = 500;
+const LOG_PATH = '/tmp/voicebox-server.log';
+
+export interface VoiceboxServerOptions {
+    url?: string;
+    serverBin?: string;
+    dataDir?: string;
+    logPath?: string;
+    bootWaitMs?: number;
+    pollMs?: number;
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    spawn?: typeof nodeSpawn;
+}
+
+async function probeVoiceboxHealth(url: string, customFetch: typeof fetch): Promise<boolean> {
+    try {
+        return (await customFetch(`${url}/health`)).ok;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Ensure a local Voicebox server is reachable: probe `/health`, and when it is down and the
+ * URL points at this machine, spawn the app's server binary detached (stderr appended to the
+ * log file, survives plugin exit) and poll until healthy — fail loud otherwise. Remote URLs
+ * and a missing binary are configuration errors, not auto-start candidates.
+ */
+export async function ensureVoiceboxRunning(options: VoiceboxServerOptions = {}): Promise<void> {
+    const rawUrl = options.url ?? process.env.VOICEBOX_URL ?? 'http://127.0.0.1:17493';
+    const customFetch = options.fetch ?? fetch;
+    const sleep = options.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+    const customSpawn = options.spawn ?? nodeSpawn;
+
+    if (await probeVoiceboxHealth(rawUrl, customFetch)) {
+        return;
+    }
+
+    const url = new URL(rawUrl);
+    const local = ['127.0.0.1', 'localhost', '::1'].includes(url.hostname);
+    if (!local) {
+        throw new Error(
+            `voice-gen: Voicebox not reachable at ${rawUrl} — auto-start only applies to local URLs; is the remote server up? (fix VOICEBOX_URL)`,
+        );
+    }
+    const serverBin =
+        options.serverBin ??
+        process.env.VOICEBOX_SERVER_BIN ??
+        '/Applications/Voicebox.app/Contents/MacOS/voicebox-server';
+    if (!existsSync(serverBin)) {
+        throw new Error(
+            `voice-gen: Voicebox not reachable at ${rawUrl} and VOICEBOX_SERVER_BIN is missing (${serverBin}) — start Voicebox.app or set VOICEBOX_SERVER_BIN`,
+        );
+    }
+    const dataDir =
+        options.dataDir ??
+        process.env.VOICEBOX_DATA_DIR ??
+        join(homedir(), 'Library/Application Support/sh.voicebox.app');
+    const logPath = options.logPath ?? LOG_PATH;
+    const port = url.port === '' ? 17493 : Number(url.port);
+
+    echoError(`voice-gen: Voicebox not reachable at ${rawUrl} — auto-starting ${serverBin} (log: ${logPath})`);
+    const child: ChildProcess = customSpawn(serverBin, ['--port', String(port), '--data-dir', dataDir], {
+        detached: true,
+        stdio: ['ignore', 'ignore', openSync(logPath, 'a')],
+    });
+    child.unref?.();
+
+    const bootWaitMs = options.bootWaitMs ?? BOOT_WAIT_MS;
+    const pollMs = options.pollMs ?? POLL_MS;
+    const deadline = Date.now() + bootWaitMs;
+    while (Date.now() < deadline) {
+        await sleep(pollMs);
+        if (await probeVoiceboxHealth(rawUrl, customFetch)) {
+            echoError(`voice-gen: Voicebox ready at ${rawUrl}`);
+            return;
+        }
+    }
+    throw new Error(
+        `voice-gen: Voicebox did not become healthy at ${rawUrl} within ${bootWaitMs}ms of auto-start — check ${logPath}`,
+    );
+}

package/plugins/kk/commands/workflow-run.md

@@ -246,15 +246,19 @@ spur workflow run "$dest" --vars \
 
 ### Profile `kk-daily-ai-voice`
 
-Bind vars: `work_dir`, `publish_enabled`, `last30days_enabled`, `skip_review`, `plugins_path`
-(empty → ADR-012 default discovery), `agent`. `$dest` resolves like solo-podcast. The run is
-topicless — no `topic`/`input_file`/`fixture` vars. `run_date` is computed by the `prepare`
-state and written to `$work_dir/run-date.txt`. The `review` state pauses the run for operator
-approval of the VoiceScript; resume with `spur workflow continue [run-id]`.
+Bind vars: `work_dir`, `run_date`, `publish_enabled`, `last30days_enabled`, `skip_review`,
+`plugins_path` (empty → ADR-012 default discovery), `agent`. `$dest` resolves like solo-podcast.
+The run is topicless — no `topic`/`input_file`/`fixture` vars. `run_date` is optional: empty →
+today (manual path), or a dashed/digits date for backfills (headless cron path). `daily-prepare`
+derives the digits-only stamp from it and composes `work_dir` when empty:
+`$works_dir/kk-daily-ai-voice/<yyyymmdd>`; an explicit `work_dir` wins. Either way the effective
+workspace lands in the anchor `.spur/runs/kk-daily-ai-voice/work-dir.txt` and the stamp in
+`$work_dir/run-date.txt`. The `review` state pauses the run for operator approval of the
+VoiceScript; resume with `spur workflow continue [run-id]`.
 
 ```bash
 spur workflow run "$dest" --vars \
-  "{\"work_dir\":\"$work_dir\",\"publish_enabled\":\"$PUBLISH\",\"last30days_enabled\":\"$L30D\",\"skip_review\":\"$SKIP_REVIEW\",\"plugins_path\":\"\",\"agent\":\"$AGENT\"}"
+  "{\"work_dir\":\"$work_dir\",\"run_date\":\"\",\"publish_enabled\":\"$PUBLISH\",\"last30days_enabled\":\"$L30D\",\"skip_review\":\"$SKIP_REVIEW\",\"plugins_path\":\"\",\"agent\":\"$AGENT\"}"
 ```
 
 ## 6. Report

package/plugins/kk/plugin.json

@@ -1,5 +1,5 @@
 {
     "name": "kk",
-    "version": "0.0.18",
+    "version": "0.0.19",
     "description": "knowledge-kit Claude Code plugin: skills, commands, subagents, hooks, and rules"
 }

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

@@ -23,11 +23,13 @@
  * The YAML prelude resolves this file as `$pkg/plugins/kk/scripts/kk-workflow-stages.ts` where `pkg`
  * comes from `realpath "$(command -v kk)"` (the installed package root), and falls back to the
  * cwd-relative `plugins/kk/scripts/kk-workflow-stages.ts` when that copy is absent — the checkout
- * tier kk-storm-research's render has always relied on, preserved on purpose.
+ * tier kk-storm-research's render has always relied on, preserved on purpose. The daily-voice
+ * workflow reaches the same script through `kk stage` (apps/cli/src/stage.ts), which applies the
+ * same two resolution tiers in TypeScript.
  *
- * SYNC: plugins/kk/workflows/{kk-solo-podcast,kk-itc,kk-storm-research,kk-daily-ai-voice}.yaml shell
- * this script. Keep message substrings stable — apps/cli/tests/kk-workflow-stages.test.ts and the
- * four workflow static tests match them.
+ * SYNC: plugins/kk/workflows/{kk-solo-podcast,kk-itc,kk-storm-research}.yaml shell this script
+ * (kk-daily-ai-voice goes through `kk stage`). Keep message substrings stable —
+ * apps/cli/tests/kk-workflow-stages.test.ts and the four workflow static tests match them.
  */
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
@@ -43,6 +45,7 @@ import {
     unlinkSync,
     writeFileSync,
 } from 'node:fs';
+import { homedir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 
 const SCRIPTS_DIR = import.meta.dir;
@@ -534,15 +537,29 @@ function dailyPrepare(args: string[]): void {
         last30daysEnabled = '',
         topic = '',
         horizonHours = '',
+        runDateArg = '',
     ] = args;
-    const workDir = resolve(workDirArg);
-    timed(workDirArg, 'prepare', () => {
-        if (!workDirArg) failWith(1, 'missing required variable: work_dir');
+    // Empty work_dir composes the real workspace from the operator's works_dir
+    // (workflow-run.md §2 precedence: KK_WORKS_DIR > config works_dir > ~/.config/kk/works):
+    //   $works_dir/kk-daily-ai-voice/<stamp>
+    // The stamp is digits-only (dashes stripped from the caller's run_date, else today) so a
+    // resumed/retried run whose persisted run_date var already carries the digits-only
+    // run-date.txt value re-derives the same directory.
+    const dirDate = runDateArg ? runDateArg.replaceAll('-', '') : formatRunDate();
+    const workDir = resolve(workDirArg || join(resolveWorksDir(), 'kk-daily-ai-voice', dirDate));
+    timed(workDir, 'prepare', () => {
         for (const dir of DAILY_DIRS)
             sted('mkdir', join(workDir, dir), () => mkdirSync(join(workDir, dir), { recursive: true }));
         sted('write', join(workDir, 'run-date.txt'), () =>
-            writeFileSync(join(workDir, 'run-date.txt'), `${formatRunDate()}\n`),
+            writeFileSync(join(workDir, 'run-date.txt'), `${dirDate}\n`),
         );
+        // Anchor for the workflow: shell actions cannot set vars, so the YAML reads the
+        // effective work_dir back into vars.work_dir from this cwd-relative file.
+        const anchorDir = join('.spur', 'runs', 'kk-daily-ai-voice');
+        sted('write', join(anchorDir, 'work-dir.txt'), () => {
+            mkdirSync(anchorDir, { recursive: true });
+            writeFileSync(join(anchorDir, 'work-dir.txt'), `${workDir}\n`);
+        });
         sted('write', join(workDir, '1-ingest/source.json'), () =>
             writeJsonText(join(workDir, '1-ingest/source.json'), {
                 limit: Number(limit),
@@ -572,6 +589,35 @@ function formatRunDate(): string {
     return `${now.getFullYear()}${month}${day}`;
 }
 
+/** Expand the `~/` and `$HOME/` prefixes the config examples use. */
+function expandHome(p: string): string {
+    if (p.startsWith('~/')) return join(homedir(), p.slice(2));
+    if (p.startsWith('$HOME/')) return join(homedir(), p.slice('$HOME/'.length));
+    return p;
+}
+
+/**
+ * works_dir for composed daily workspaces — workflow-run.md §2 precedence:
+ * KK_WORKS_DIR env > config works_dir > compiled default ~/.config/kk/works.
+ * Unreadable/unparseable config falls through to the default (pluginEnvFromConfig
+ * tolerates the same), never fails the run.
+ */
+function resolveWorksDir(): string {
+    const fromEnv = process.env.KK_WORKS_DIR;
+    if (fromEnv) return fromEnv;
+    const configPath = process.env.KK_CONFIG || join(homedir(), '.config/kk/config.yaml');
+    if (existsSync(configPath)) {
+        try {
+            const parsed = Bun.YAML.parse(readFileSync(configPath, 'utf-8')) as Record<string, unknown> | null;
+            const worksDir = parsed !== null && typeof parsed === 'object' ? parsed.works_dir : undefined;
+            if (typeof worksDir === 'string' && worksDir !== '') return expandHome(worksDir);
+        } catch {
+            // fall through to the compiled default
+        }
+    }
+    return join(homedir(), '.config/kk/works');
+}
+
 function dailyCollectFacts(args: string[]): void {
     const [workDir = '', runDate = '', pluginsPath = ''] = args;
     const content = join(workDir, '2-facts', `${runDate}_02_collect_content.json`);
@@ -780,7 +826,9 @@ function dailyArticle(args: string[]): void {
             {
                 env: {
                     ARTICLE_DATE: runDate,
-                    ...(isFile(proseBody) ? { ARTICLE_BODY_FILE: proseBody } : {}),
+                    // Plugin entries run with cwd = plugin dir (invoke.ts), so relative
+                    // paths in env must be resolved or the plugin sees ENOENT.
+                    ...(isFile(proseBody) ? { ARTICLE_BODY_FILE: resolve(proseBody) } : {}),
                 },
             },
         );

package/plugins/kk/workflows/kk-daily-ai-voice.yaml

@@ -35,6 +35,9 @@ vars:
   plan_translate_enabled: "true"
   article_write_enabled: "true"
   plugins_path: ""
+  # Projected by the publish state from 3-publish/<run_date>_17_publish_publish-status.txt;
+  # guards test this var instead of cat-ing the file (state at decision time).
+  publish_status: ""
   last30days_topic: "AI news"
   horizon_hours: "24"
   publish_enabled: "false"
@@ -62,13 +65,18 @@ states:
     onEnter:
       - kind: shell
         options:
+          # run_date (dashed or digits; the job worker expands $(date +%F) before spur sees the
+          # JSON — var values reach non-shell steps verbatim) only names the workspace:
+          # daily-prepare composes the real dir as works_dir/kk-daily-ai-voice/<stamp> when
+          # work_dir is empty and always writes the effective work_dir to the cwd-relative
+          # anchor below. Shell actions cannot set vars, so the reads project it (then the
+          # digits-only stamp) into vars before any later state interpolates them.
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-prepare "${vars.work_dir}" "${vars.limit}" "${vars.cursor}" "${vars.state_file}" "${vars.last30days_enabled}" "${vars.last30days_topic}" "${vars.horizon_hours}"
+            kk stage daily-prepare "${vars.work_dir}" "${vars.limit}" "${vars.cursor}" "${vars.state_file}" "${vars.last30days_enabled}" "${vars.last30days_topic}" "${vars.horizon_hours}" "${vars.run_date}"
+      - kind: file.read.into-var
+        options:
+          path: .spur/runs/kk-daily-ai-voice/work-dir.txt
+          var: work_dir
       - kind: file.read.into-var
         options:
           path: ${vars.work_dir}/run-date.txt
@@ -89,12 +97,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-collect-facts "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}"
+            kk stage daily-collect-facts "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}"
 
   - id: plan
     description: "Score/dedup/select + annotate the blended Doc[] into the episode plan (episode-plan-gen; annotate rides inside planEpisode)"
@@ -102,12 +105,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-plan "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.plan_max_items}"
+            kk stage daily-plan "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.plan_max_items}"
 
   - id: quality-control-content
     description: "Content QC: filter the plan's annotated candidates by category allowlist + score thresholds (episode-plan-gen --mode filter); zero candidates route to done-no-content"
@@ -115,12 +113,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-qc-content "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.qc_categories}" "${vars.qc_min_quality}" "${vars.qc_min_importance}" "${vars.qc_min_urgency}" "${vars.qc_min_impact}"
+            kk stage daily-qc-content "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.qc_categories}" "${vars.qc_min_quality}" "${vars.qc_min_importance}" "${vars.qc_min_urgency}" "${vars.qc_min_impact}"
 
   - id: plan-translate
     description: "Translate needsTranslation plan items into the output plan.json via agent.run"
@@ -162,12 +155,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-article "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}"
+            kk stage daily-article "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}"
 
   - id: cover
     description: "Generate the article cover image via the kk:image-authoring skill (agent.run)"
@@ -186,12 +174,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-cover-normalize "${vars.work_dir}" "${vars.run_date}"
+            kk stage daily-cover-normalize "${vars.work_dir}" "${vars.run_date}"
 
   - id: script
     description: "Compile the episode plan Doc[] into structured broadcast VoiceScript YAML Content"
@@ -199,12 +182,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-script "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.language}" "${vars.title}" "${vars.voice_profile}"
+            kk stage daily-script "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.language}" "${vars.title}" "${vars.voice_profile}"
 
   - id: review
     description: "Operator reviews the generated news script before speech synthesis"
@@ -221,12 +199,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-wrap-docs "${vars.work_dir}" "${vars.run_date}" "${vars.voice_profile}"
+            kk stage daily-wrap-docs "${vars.work_dir}" "${vars.run_date}" "${vars.voice_profile}"
 
   - id: generate
     description: "Invoke voice driver plugin (vdriver var: ominivoice -> omni-voice-gen, voicebox -> voice-gen) to generate audio"
@@ -234,12 +207,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            OMNIVOICE_SPEED=1.06 bun "$st" daily-generate "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.transcode_mp3}" "${vars.vdriver}"
+            OMNIVOICE_SPEED=1.06 kk stage daily-generate "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.transcode_mp3}" "${vars.vdriver}"
 
   - id: intro-music
     description: "Prepend the 8s intro sting (intro_music var; empty = skip) to the generated wav, update duration/audioPath"
@@ -247,12 +215,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-intro "${vars.work_dir}" "${vars.run_date}" "${vars.intro_music}"
+            kk stage daily-intro "${vars.work_dir}" "${vars.run_date}" "${vars.intro_music}"
 
   - id: quality-control
     description: "Verify audio quality, speech rate, and silence/repetition QC metrics"
@@ -260,12 +223,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-quality-report "${vars.work_dir}" "${vars.run_date}"
+            kk stage daily-quality-report "${vars.work_dir}" "${vars.run_date}"
 
   - id: publish-prep
     description: "Merge article Content with audio (podcast assembly facts ride the content options channel for podcast-pub's absorbed assembly; runDate kept for surfdash slug)"
@@ -273,12 +231,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-publish-prep "${vars.work_dir}" "${vars.run_date}"
+            kk stage daily-publish-prep "${vars.work_dir}" "${vars.run_date}"
 
   - id: publish-surfdash
     description: "Publish the merged Content to surfdash (single target); result lands in result.json — surfdash publishes first so show-notes can link the article (task 0118 seam reorder)"
@@ -286,12 +239,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-publish-surfdash "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}"
+            kk stage daily-publish-surfdash "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}"
 
   - id: show-notes
     description: "Render timeline show notes from the episode plan (podcast-pub show-notes op, briefMode; article URL from the surfdash result postPath — surfdash failure degrades to legacy full-body layout)"
@@ -299,12 +247,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-show-notes "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.title}"
+            kk stage daily-show-notes "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.title}"
 
   - id: publish-podcast
     description: "Publish the episode to podcast-pub with the rendered show notes (metadata.showNotes carries the brief/timeline markdown; map.ts falls back to content.body when absent — task 0118 R3)"
@@ -312,12 +255,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-publish-podcast "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}"
+            kk stage daily-publish-podcast "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}"
 
   - id: publish
     description: "Classify the sequenced surfdash → podcast outcomes full|partial|none into publish-status.txt (exit 0 in all three — routing is transition-owned; task 0118: per-target classification over the merged result.json)"
@@ -325,12 +263,11 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-publish-classify "${vars.work_dir}" "${vars.run_date}"
+            kk stage daily-publish-classify "${vars.work_dir}" "${vars.run_date}"
+      - kind: file.read.into-var
+        options:
+          path: ${vars.work_dir}/3-publish/${vars.run_date}_17_publish_publish-status.txt
+          var: publish_status
 
   - id: patch-surfdash
     description: "20260917 #4/#6 — patch published surfdash posts: podcast cover URL into image/og_image frontmatter + podcast cross-link (zh/en/ja), commit+push"
@@ -338,12 +275,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-patch-surfdash "${vars.work_dir}" "${vars.run_date}" "${vars.surfdash_root}"
+            kk stage daily-patch-surfdash "${vars.work_dir}" "${vars.run_date}" "${vars.surfdash_root}"
 
   - id: publish-partial
     description: "Partial publish — at least one target published, at least one failed; echo warning, write a .spur/run marker, preserve result.json for --retry-from, continue to done (task 0118: surfdash failure = no-URL fallback notes; podcast failure = its own partial)"
@@ -351,12 +283,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-publish-partial "${vars.work_dir}" "${vars.run_date}"
+            kk stage daily-publish-partial "${vars.work_dir}" "${vars.run_date}"
 
   - id: run-report
     description: "Assemble the per-run report (scores+aggregates+rejected counts+step timing) from existing artifacts — news-report-gen; output-only, never throws; 0117"
@@ -364,12 +291,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-run-report "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.qc_min_quality}" "${vars.qc_min_importance}" "${vars.qc_min_urgency}" "${vars.qc_min_impact}"
+            kk stage daily-run-report "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.qc_min_quality}" "${vars.qc_min_importance}" "${vars.qc_min_urgency}" "${vars.qc_min_impact}"
 
   - id: translate
     description: "Locales — surfdash-pub scaffolds en/ja drafts (deterministic, plugin-owned), agent translates both, sync into the surfdash CMS"
@@ -377,12 +299,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-translate-localize "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}"
+            kk stage daily-translate-localize "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}"
       - kind: file.read.into-var
         options:
           path: ${vars.work_dir}/3-publish/${vars.run_date}_20_translate-localize_en-post-path.txt
@@ -405,12 +322,7 @@ states:
       - kind: shell
         options:
           command: >-
-            kbin="$(command -v kk 2>/dev/null)";
-            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
-            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
-            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
-            bun "$st" daily-translate-sync "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.work_dir}/3-publish/${vars.run_date}_20_translate-localize_zh-post-path.txt"
+            kk stage daily-translate-sync "${vars.work_dir}" "${vars.run_date}" "${vars.plugins_path}" "${vars.work_dir}/3-publish/${vars.run_date}_20_translate-localize_zh-post-path.txt"
 
   - id: done
     description: "Terminal — Daily AI news pipeline completed (collect → QC'd plan → article/cover/script/voice → publish/locales)"
@@ -623,7 +535,7 @@ transitions:
     guard:
       kind: shell
       options:
-        command: 'test "$(cat "${vars.work_dir}/3-publish/${vars.run_date}_17_publish_publish-status.txt")" = "partial"'
+        command: 'test "${vars.publish_status}" = "partial"'
 
   - from: publish
     to: failed
@@ -631,7 +543,7 @@ transitions:
     guard:
       kind: shell
       options:
-        command: 'test "$(cat "${vars.work_dir}/3-publish/${vars.run_date}_17_publish_publish-status.txt")" = "none"'
+        command: 'test "${vars.publish_status}" = "none"'
 
   - from: publish-partial
     to: run-report
@@ -645,7 +557,7 @@ transitions:
     guard:
       kind: shell
       options:
-        command: 'test "$(cat "${vars.work_dir}/3-publish/${vars.run_date}_17_publish_publish-status.txt")" = "full"'
+        command: 'test "${vars.publish_status}" = "full"'
 
   - from: run-report
     to: done
@@ -653,7 +565,7 @@ transitions:
     guard:
       kind: shell
       options:
-        command: 'test "$(cat "${vars.work_dir}/3-publish/${vars.run_date}_17_publish_publish-status.txt")" = "partial"'
+        command: 'test "${vars.publish_status}" = "partial"'
 
   - from: translate
     to: done