@gobing-ai/knowledge-kit 0.1.14 → 0.1.15

package/dist/index.js

@@ -38526,10 +38526,12 @@ var init_bot = __esm(() => {
   CONTROL_CHARACTERS = /\p{Cc}/u;
   BotError = class BotError extends Error {
     code;
-    constructor(code, message) {
+    details;
+    constructor(code, message, details = {}) {
       super(message);
       this.name = "BotError";
       this.code = code;
+      this.details = details;
     }
   };
 });
@@ -38796,11 +38798,13 @@ __export(exports_browser, {
   captureSessionFacts: () => captureSessionFacts,
   checkChannelSession: () => checkChannelSession,
   chmod: () => chmod,
+  closeBotContext: () => closeBotContext,
   createExclusiveFile: () => createExclusiveFile,
   createKkBrowserLauncher: () => createKkBrowserLauncher,
   createShadowFinder: () => createShadowFinder,
   enterDelegatedLease: () => enterDelegatedLease,
   execBot: () => execBot,
+  execFailureDetail: () => execFailureDetail,
   expectOutcome: () => expectOutcome,
   fillCodeMirror: () => fillCodeMirror,
   findLeftoverTransaction: () => findLeftoverTransaction,
@@ -38814,11 +38818,13 @@ __export(exports_browser, {
   loginBot: () => loginBot,
   logoutBot: () => logoutBot,
   markdownToHtml: () => markdownToHtml,
+  missingBotProfile: () => missingBotProfile,
   mkdirExclusive: () => mkdirExclusive,
   normalizeBotDefaultUrl: () => normalizeBotDefaultUrl,
   normalizeSessionExpiry: () => normalizeSessionExpiry,
   normalizeSessionIdentity: () => normalizeSessionIdentity,
   openBot: () => openBot,
+  openBotPage: () => openBotPage,
   openChannelSession: () => openChannelSession,
   parseBotMetadata: () => parseBotMetadata,
   pasteHtml: () => pasteHtml,
@@ -38832,6 +38838,7 @@ __export(exports_browser, {
   rmdir: () => rmdir,
   runProfileCli: () => runProfileCli,
   uploadFile: () => uploadFile,
+  validateExecUrl: () => validateExecUrl,
   verifyLeaseHeld: () => verifyLeaseHeld,
   waitUntil: () => waitUntil
 });
@@ -39652,6 +39659,539 @@ var init_browser = __esm(() => {
   ];
 });
 
+// ../../packages/publish-harness/src/bot-collection.ts
+var exports_bot_collection = {};
+__export(exports_bot_collection, {
+  runBotCollection: () => runBotCollection
+});
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function usage(path) {
+  return new BotError("usage", `invalid collection plan: ${path}`);
+}
+function requireSafeId(value, path, seen) {
+  if (typeof value !== "string" || !SAFE_ID.test(value))
+    throw usage(`${path} must match [A-Za-z0-9][A-Za-z0-9_-]{0,63}`);
+  if (seen.has(value))
+    throw usage(`${path} duplicates an id already declared in this plan`);
+  seen.add(value);
+  return value;
+}
+function requireString(value, path) {
+  if (typeof value !== "string" || value.trim() === "")
+    throw usage(`${path} must be a non-empty string`);
+  return value;
+}
+function optionalString(value, path) {
+  return value === undefined ? undefined : requireString(value, path);
+}
+function optionalTimeout(value, path) {
+  return value === undefined ? undefined : requirePositiveInt(value, path);
+}
+function requirePositiveInt(value, path) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    throw usage(`${path} must be a positive integer`);
+  }
+  return value;
+}
+function requireHeaders(value, path) {
+  if (!isRecord3(value))
+    throw usage(`${path} must be an object of string header values`);
+  const headers = {};
+  for (const [name, headerValue] of Object.entries(value)) {
+    headers[name] = requireString(headerValue, `${path}.${name}`);
+  }
+  return headers;
+}
+function requireUrl(value, path) {
+  try {
+    return validateExecUrl(requireString(value, path));
+  } catch {
+    throw usage(`${path} must be an absolute http(s) URL without credentials`);
+  }
+}
+function normalizeOrigin(value, path) {
+  const raw = requireString(value, path);
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw usage(`${path} must be an absolute http(s) origin`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:" || parsed.origin !== raw) {
+    throw usage(`${path} must be an exact http(s) scheme/host/port origin`);
+  }
+  return parsed.origin;
+}
+function normalizePathPrefix(value, path) {
+  const prefix = requireString(value, path);
+  if (!prefix.startsWith("/") || prefix.includes("?") || prefix.includes("#")) {
+    throw usage(`${path} must be an absolute URL path without query or fragment`);
+  }
+  return prefix;
+}
+function normalizeStep(raw, path, seen) {
+  if (!isRecord3(raw))
+    throw usage(path);
+  const id = requireSafeId(raw.id, `${path}.id`, seen);
+  switch (raw.type) {
+    case "request": {
+      if (raw.data !== undefined && typeof raw.data !== "string")
+        throw usage(`${path}.data must be a string`);
+      if (raw.followRedirects !== undefined && typeof raw.followRedirects !== "boolean") {
+        throw usage(`${path}.followRedirects must be a boolean`);
+      }
+      return {
+        id,
+        type: "request",
+        url: requireUrl(raw.url, `${path}.url`),
+        ...raw.method === undefined ? {} : { method: requireString(raw.method, `${path}.method`) },
+        ...raw.headers === undefined ? {} : { headers: requireHeaders(raw.headers, `${path}.headers`) },
+        ...raw.data === undefined ? {} : { data: raw.data },
+        ...raw.followRedirects === undefined ? {} : { followRedirects: raw.followRedirects },
+        ...rawTimeout(raw.timeoutMs, path) ?? {}
+      };
+    }
+    case "navigate": {
+      const waitUntil = raw.waitUntil;
+      if (waitUntil !== undefined && !NAVIGATION_WAIT_UNTIL.includes(waitUntil)) {
+        throw usage(`${path}.waitUntil must be one of ${NAVIGATION_WAIT_UNTIL.join(", ")}`);
+      }
+      return {
+        id,
+        type: "navigate",
+        url: requireUrl(raw.url, `${path}.url`),
+        ...waitUntil === undefined ? {} : { waitUntil },
+        ...rawTimeout(raw.timeoutMs, path) ?? {}
+      };
+    }
+    case "wait":
+    case "click":
+      return {
+        id,
+        type: raw.type,
+        selector: requireString(raw.selector, `${path}.selector`),
+        ...rawTimeout(raw.timeoutMs, path) ?? {}
+      };
+    case "scroll": {
+      const deltaY = raw.deltaY;
+      if (typeof deltaY !== "number" || !Number.isFinite(deltaY) || deltaY === 0) {
+        throw usage(`${path}.deltaY must be a finite non-zero number`);
+      }
+      return { id, type: "scroll", deltaY, ...rawTimeout(raw.timeoutMs, path) ?? {} };
+    }
+    case "extract": {
+      if (raw.format !== "html" && raw.format !== "text")
+        throw usage(`${path}.format must be "html" or "text"`);
+      const selector = optionalString(raw.selector, `${path}.selector`);
+      return {
+        id,
+        type: "extract",
+        format: raw.format,
+        ...selector === undefined ? {} : { selector },
+        ...rawTimeout(raw.timeoutMs, path) ?? {}
+      };
+    }
+    default:
+      throw usage(`${path}.type must be request, navigate, wait, click, scroll or extract`);
+  }
+}
+function rawTimeout(value, path) {
+  const timeoutMs = optionalTimeout(value, `${path}.timeoutMs`);
+  return timeoutMs === undefined ? undefined : { timeoutMs };
+}
+function normalizePlan(plan) {
+  if (!isRecord3(plan))
+    throw usage("plan must be a JSON object");
+  if (!Array.isArray(plan.steps))
+    throw usage("plan.steps must be an array");
+  if (plan.responses !== undefined && !Array.isArray(plan.responses))
+    throw usage("plan.responses must be an array");
+  const seen = new Set;
+  const steps = plan.steps.map((step, index) => normalizeStep(step, `plan.steps[${index}]`, seen));
+  const responses = (plan.responses ?? []).map((raw, index) => {
+    const path = `plan.responses[${index}]`;
+    if (!isRecord3(raw))
+      throw usage(path);
+    return {
+      id: requireSafeId(raw.id, `${path}.id`, seen),
+      ...raw.origin === undefined ? {} : { origin: normalizeOrigin(raw.origin, `${path}.origin`) },
+      pathPrefix: normalizePathPrefix(raw.pathPrefix, `${path}.pathPrefix`)
+    };
+  });
+  const produces = steps.some((step) => step.type === "request" || step.type === "extract");
+  if (!produces && responses.length === 0) {
+    throw usage("plan declares no artifact source: add a request/extract step or a response capture");
+  }
+  let timeoutMs = DEFAULT_RUN_TIMEOUT_MS;
+  if (plan.timeoutMs !== undefined) {
+    timeoutMs = requirePositiveInt(plan.timeoutMs, "plan.timeoutMs");
+    if (timeoutMs > MAX_RUN_TIMEOUT_MS)
+      throw usage(`plan.timeoutMs must not exceed ${MAX_RUN_TIMEOUT_MS}`);
+  }
+  return { steps, responses, timeoutMs };
+}
+function safeUrl(input) {
+  try {
+    const parsed = new URL(input);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+      return;
+    return `${parsed.origin}${parsed.pathname}`;
+  } catch {
+    return;
+  }
+}
+function looksLikeAuthWall(url) {
+  if (url === undefined)
+    return false;
+  try {
+    return AUTH_PATH.test(new URL(url).pathname);
+  } catch {
+    return false;
+  }
+}
+function classifyStatus(status, stepIndex, stepId, what = "step") {
+  const details = {
+    ...stepIndex === undefined ? {} : { stepIndex },
+    stepId
+  };
+  if (status === 401 || status === 403) {
+    return new BotError("authentication", `${what} '${stepId}' hit an authentication wall (status ${status}) \u2014 ` + "run `kk bot login <url> --save <profileName>` to renew the session", details);
+  }
+  if (status >= 400) {
+    return new BotError("browser", `${what} '${stepId}' returned status ${status}`, details);
+  }
+  return;
+}
+function emptyFailure(id, what, stepIndex) {
+  return new BotError("empty", `${what} '${id}' produced no content`, {
+    ...stepIndex === undefined ? {} : { stepIndex },
+    stepId: id
+  });
+}
+async function readBody(response) {
+  return await response.body();
+}
+function stepTimeout(step, remaining, stepIndex) {
+  if (remaining <= 0) {
+    throw new BotError("browser", `step '${step.id}' exceeded the collection deadline`, {
+      stepIndex,
+      stepId: step.id
+    });
+  }
+  return Math.min(step.timeoutMs ?? DEFAULT_STEP_TIMEOUT_MS2, remaining);
+}
+function requestFailureDetail(error, step) {
+  let detail = execFailureDetail(error, step.url);
+  const secrets = [...Object.values(step.headers ?? {}), ...step.data === undefined ? [] : [step.data]];
+  for (const secret of secrets) {
+    if (secret.length > 0)
+      detail = detail.split(secret).join("<redacted>");
+  }
+  return detail.slice(0, 200);
+}
+async function runStep(step, index, context, page, timeoutMs) {
+  const details = { stepIndex: index, stepId: step.id };
+  switch (step.type) {
+    case "request": {
+      let response;
+      try {
+        response = await context.request.fetch(step.url, {
+          method: step.method ?? (step.data === undefined ? "GET" : "POST"),
+          ...step.headers === undefined ? {} : { headers: step.headers },
+          ...step.data === undefined ? {} : { data: Buffer.from(step.data, "utf8") },
+          failOnStatusCode: false,
+          ...step.followRedirects === true ? {} : { maxRedirects: 0 },
+          timeout: timeoutMs
+        });
+      } catch (error) {
+        throw new BotError("browser", `step '${step.id}' request failed (${requestFailureDetail(error, step)})`, details);
+      }
+      const status = response.status();
+      const wall = classifyStatus(status, index, step.id);
+      if (wall !== undefined)
+        throw wall;
+      let body;
+      try {
+        body = await readBody(response);
+      } catch {
+        throw new BotError("browser", `step '${step.id}' response body could not be read`, details);
+      }
+      const text = body.toString("utf8");
+      if (text.trim() === "")
+        throw emptyFailure(step.id, "step", index);
+      const requestUrl = safeUrl(step.url);
+      return {
+        result: {
+          index,
+          id: step.id,
+          type: step.type,
+          ...requestUrl === undefined ? {} : { url: requestUrl }
+        },
+        artifact: {
+          id: step.id,
+          kind: "request",
+          body: text,
+          status,
+          ...requestUrl === undefined ? {} : { url: requestUrl },
+          stepIndex: index
+        }
+      };
+    }
+    case "navigate": {
+      let status;
+      try {
+        const response = await page.goto(step.url, {
+          waitUntil: step.waitUntil ?? "load",
+          timeout: timeoutMs
+        });
+        status = response?.status();
+      } catch (error) {
+        throw new BotError("browser", `step '${step.id}' navigation failed (${execFailureDetail(error, step.url)})`, details);
+      }
+      const finalUrl = safeUrl(page.url()) ?? safeUrl(step.url);
+      if (looksLikeAuthWall(page.url())) {
+        throw new BotError("authentication", `step '${step.id}' landed on an authentication page \u2014 ` + "run `kk bot login <url> --save <profileName>` to renew the session", details);
+      }
+      if (status !== undefined) {
+        const wall = classifyStatus(status, index, step.id);
+        if (wall !== undefined)
+          throw wall;
+      }
+      return {
+        result: { index, id: step.id, type: step.type, ...finalUrl === undefined ? {} : { url: finalUrl } }
+      };
+    }
+    case "wait": {
+      try {
+        await page.waitForSelector(step.selector, { timeout: timeoutMs });
+      } catch {
+        throw new BotError("browser", `step '${step.id}' timed out waiting for its selector`, details);
+      }
+      return { result: { index, id: step.id, type: step.type } };
+    }
+    case "click": {
+      try {
+        await page.locator(step.selector).first().click({ timeout: timeoutMs });
+      } catch {
+        throw new BotError("browser", `step '${step.id}' could not click its selector`, details);
+      }
+      return { result: { index, id: step.id, type: step.type } };
+    }
+    case "scroll": {
+      try {
+        await page.evaluate(`window.scrollBy(0, ${JSON.stringify(step.deltaY)})`);
+      } catch {
+        throw new BotError("browser", `step '${step.id}' could not scroll the page`, details);
+      }
+      return { result: { index, id: step.id, type: step.type } };
+    }
+    case "extract": {
+      let text;
+      try {
+        const target = step.selector === undefined ? null : page.locator(step.selector).first();
+        text = await applyTimeout(step.format === "html" ? target === null ? page.content() : target.evaluate("(element) => element.outerHTML").then((value) => String(value)) : target === null ? page.evaluate('document.body ? document.body.innerText : ""').then((value) => String(value)) : target.innerText(), timeoutMs);
+      } catch {
+        throw new BotError("browser", `step '${step.id}' could not extract its content`, details);
+      }
+      if (text.trim() === "")
+        throw emptyFailure(step.id, "step", index);
+      const pageUrl = safeUrl(page.url());
+      return {
+        result: { index, id: step.id, type: step.type, ...pageUrl === undefined ? {} : { url: pageUrl } },
+        artifact: {
+          id: step.id,
+          kind: step.format,
+          body: text,
+          ...pageUrl === undefined ? {} : { url: pageUrl },
+          stepIndex: index
+        }
+      };
+    }
+  }
+}
+function enforceCaps(artifact, artifacts, aggregate) {
+  if (artifacts.length >= MAX_ARTIFACTS) {
+    throw new BotError("browser", `collection produced more than ${MAX_ARTIFACTS} artifacts`, {
+      ...artifact.stepIndex === undefined ? {} : { stepIndex: artifact.stepIndex },
+      stepId: artifact.id
+    });
+  }
+  const bytes = Buffer.byteLength(artifact.body, "utf8");
+  if (bytes > MAX_ARTIFACT_BYTES) {
+    throw new BotError("browser", `artifact '${artifact.id}' exceeds the per-artifact body cap`, {
+      ...artifact.stepIndex === undefined ? {} : { stepIndex: artifact.stepIndex },
+      stepId: artifact.id
+    });
+  }
+  const total = aggregate + bytes;
+  if (total > MAX_AGGREGATE_BYTES) {
+    throw new BotError("browser", `collection exceeded the aggregate body cap`, { stepId: artifact.id });
+  }
+  return total;
+}
+async function applyTimeout(promise, timeoutMs) {
+  let timer;
+  const expiry = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(new StepTimeoutError), timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, expiry]);
+  } finally {
+    if (timer !== undefined)
+      clearTimeout(timer);
+  }
+}
+async function waitWithin(promise, budgetMs) {
+  if (budgetMs <= 0)
+    return false;
+  let timer;
+  const expiry = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(false), budgetMs);
+  });
+  try {
+    return await Promise.race([promise.then(() => true), expiry]);
+  } finally {
+    if (timer !== undefined)
+      clearTimeout(timer);
+  }
+}
+async function runBotCollection(profileName, plan, options = {}) {
+  const normalized = normalizePlan(plan);
+  const name = assertSafeBotName(profileName);
+  const fileSystem = options.fileSystem ?? createNodeFileSystem();
+  const now = options.now ?? Date.now;
+  const deadline = now() + normalized.timeoutMs;
+  const profileDir = resolveBotProfileDir(name, { root: options.root });
+  if (lstat(profileDir) === null)
+    throw missingBotProfile(name, false);
+  const acquire = options.acquireLease ?? acquireProfileLease;
+  const lease = await acquire(profileDir, { leaseRoot: options.leaseRoot, fileSystem });
+  const captures = normalized.responses.map((declaration) => ({
+    declaration,
+    matches: [],
+    pending: [],
+    readFailures: 0
+  }));
+  let context;
+  try {
+    const launcher = options.launcher ?? createKkBrowserLauncher(undefined, { lease, physicalProfileDir: profileDir }, { leaseRoot: options.leaseRoot, fileSystem });
+    context = await launcher.launch({ profileDir, headless: true });
+    const activeContext = context;
+    if (captures.length > 0) {
+      activeContext.on("response", (response) => {
+        const raw = response.url();
+        let parsed;
+        try {
+          parsed = new URL(raw);
+        } catch {
+          return;
+        }
+        for (const state of captures) {
+          const { origin, pathPrefix } = state.declaration;
+          if (origin !== undefined && parsed.origin !== origin)
+            continue;
+          if (!parsed.pathname.startsWith(pathPrefix))
+            continue;
+          const status = response.status();
+          const failure = classifyStatus(status, undefined, state.declaration.id, "capture");
+          if (failure !== undefined) {
+            state.failure ??= failure;
+            continue;
+          }
+          state.pending.push(readBody(response).then((body) => {
+            state.matches.push({
+              status,
+              text: body.toString("utf8"),
+              url: `${parsed.origin}${parsed.pathname}`
+            });
+          }, () => {
+            state.readFailures += 1;
+          }));
+        }
+      });
+    }
+    const page = await openBotPage(activeContext);
+    const steps = [];
+    const artifacts = [];
+    let aggregate = 0;
+    for (const [index, step] of normalized.steps.entries()) {
+      const timeoutMs = stepTimeout(step, deadline - now(), index);
+      let outcome;
+      try {
+        outcome = await applyTimeout(runStep(step, index, activeContext, page, timeoutMs), timeoutMs);
+      } catch (error) {
+        if (error instanceof StepTimeoutError) {
+          throw new BotError("browser", `step '${step.id}' exceeded the collection deadline`, {
+            stepIndex: index,
+            stepId: step.id
+          });
+        }
+        throw error;
+      }
+      steps.push(outcome.result);
+      if (outcome.artifact !== undefined) {
+        aggregate = enforceCaps(outcome.artifact, artifacts, aggregate);
+        artifacts.push(outcome.artifact);
+      }
+    }
+    for (const state of captures) {
+      if (state.failure !== undefined)
+        throw state.failure;
+      const settled = await waitWithin(Promise.all(state.pending).then(() => {
+        return;
+      }), deadline - now());
+      if (!settled) {
+        throw new BotError("browser", `response capture '${state.declaration.id}' exceeded the collection deadline`, {
+          stepId: state.declaration.id
+        });
+      }
+      if (state.failure !== undefined)
+        throw state.failure;
+      const found = state.matches.filter((match) => match.text.trim() !== "");
+      if (found.length === 0 && state.readFailures > 0) {
+        throw new BotError("browser", `response capture '${state.declaration.id}' could not be read`, {
+          stepId: state.declaration.id
+        });
+      }
+      if (found.length === 0)
+        throw emptyFailure(state.declaration.id, "capture");
+      for (const match of found) {
+        const artifact = {
+          id: state.declaration.id,
+          kind: "response",
+          body: match.text,
+          status: match.status,
+          url: match.url
+        };
+        aggregate = enforceCaps(artifact, artifacts, aggregate);
+        artifacts.push(artifact);
+      }
+    }
+    return { steps, artifacts };
+  } finally {
+    await closeBotContext(context);
+    await Promise.allSettled(captures.flatMap((state) => state.pending));
+    await lease.release();
+  }
+}
+var DEFAULT_STEP_TIMEOUT_MS2 = 30000, DEFAULT_RUN_TIMEOUT_MS = 120000, MAX_RUN_TIMEOUT_MS = 600000, MAX_ARTIFACT_BYTES, MAX_AGGREGATE_BYTES, MAX_ARTIFACTS = 100, SAFE_ID, AUTH_PATH, NAVIGATION_WAIT_UNTIL, StepTimeoutError;
+var init_bot_collection = __esm(() => {
+  init_dist3();
+  init_bot();
+  init_bot_fs();
+  init_browser();
+  init_profile_lease();
+  MAX_ARTIFACT_BYTES = 5 * 1024 * 1024;
+  MAX_AGGREGATE_BYTES = 20 * 1024 * 1024;
+  SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+  AUTH_PATH = /(?:^|\/)(?:login|signin|sign-in|auth|sso)(?:\/|$)/i;
+  NAVIGATION_WAIT_UNTIL = ["load", "domcontentloaded", "networkidle"];
+  StepTimeoutError = class StepTimeoutError extends Error {
+  };
+});
+
 // ../../node_modules/.bun/@logtape+logtape@2.3.1/node_modules/@logtape/logtape/dist/util.node.js
 var exports_util_node = {};
 __export(exports_util_node, {
@@ -42103,11 +42643,11 @@ var PluginManifestSchemaBase = looseObject({
 });
 var PluginManifestSchema = PluginManifestSchemaBase.superRefine((manifest, ctx) => {
   if (manifest.browserSession !== undefined) {
-    if (manifest.kind !== "publish") {
+    if (manifest.kind !== "publish" && manifest.kind !== "ingestion") {
       ctx.addIssue({
         code: "custom",
         path: ["browserSession"],
-        message: `browserSession requires kind "publish", not "${manifest.kind}"`
+        message: `browserSession requires kind "publish" or "ingestion", not "${manifest.kind}"`
       });
     }
     if (manifest.check === undefined) {
@@ -48567,6 +49107,8 @@ function collectSetting2(value, previous) {
 }
 
 // src/commands/bot.ts
+import { join as join14 } from "path";
+init_dist3();
 init_commander();
 
 // src/bot-adapter.ts
@@ -48643,6 +49185,20 @@ function bindAdapterSession(candidate) {
   };
 }
 
+// src/bot-plan.ts
+function decodeBotPlan(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { ok: false, reason: "invalid-json" };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { ok: false, reason: "not-object" };
+  }
+  return { ok: true, plan: parsed };
+}
+
 // src/byte-output.ts
 import { readFileSync as readFileSync8, writeFileSync as writeFileSync5 } from "fs";
 function writeBytes(chunk) {
@@ -48661,7 +49217,10 @@ function writeFileBytes(path, bytes) {
 init_output2();
 var botHarness;
 function loadBotHarness() {
-  botHarness ??= Promise.resolve().then(() => (init_browser(), exports_browser));
+  botHarness ??= Promise.all([
+    Promise.resolve().then(() => (init_browser(), exports_browser)),
+    Promise.resolve().then(() => (init_bot_collection(), exports_bot_collection))
+  ]).then(([browser, collection]) => ({ ...browser, ...collection }));
   return botHarness;
 }
 async function runBotAction(load, action) {
@@ -48805,16 +49364,77 @@ function execHeaderBlock(status, statusText, headers) {
 
 `;
 }
+function parsePlanMaxTime(harness, value) {
+  const seconds = Number(value);
+  if (!Number.isFinite(seconds) || seconds <= 0 || seconds > 600) {
+    throw new harness.BotError("usage", "--max-time must be a positive number of seconds (up to 600)");
+  }
+  return Math.round(seconds * 1000);
+}
+async function readPlanFile(harness, planPath) {
+  let raw;
+  try {
+    raw = await createNodeFileSystem().readFile(planPath);
+  } catch {
+    throw new harness.BotError("usage", `could not read plan file '${planPath}'`);
+  }
+  const decoded = decodeBotPlan(raw);
+  if (!decoded.ok) {
+    throw new harness.BotError("usage", decoded.reason === "not-object" ? "plan must be a JSON object" : "plan file is not valid JSON");
+  }
+  return decoded.plan;
+}
+async function botPlanAction(load, name, planPath, options) {
+  await runBotAction(load, async (harness) => {
+    const plan = await readPlanFile(harness, planPath);
+    const timeoutMs = options.maxTime === undefined ? undefined : parsePlanMaxTime(harness, options.maxTime);
+    const result = await harness.runBotCollection(name, plan, {
+      ...timeoutMs === undefined ? {} : { timeoutMs }
+    });
+    if (options.output !== undefined) {
+      const fs = createNodeFileSystem();
+      await fs.ensureDir(options.output);
+      harness.chmod(options.output, 448);
+      const sanitizedArtifacts = [];
+      for (const [index, artifact] of result.artifacts.entries()) {
+        const safeName = `${String(index).padStart(2, "0")}-${artifact.id.replace(/[^A-Za-z0-9_-]/g, "-")}.txt`;
+        const filePath = join14(options.output, safeName);
+        await fs.writeFile(filePath, artifact.body);
+        harness.chmod(filePath, 384);
+        sanitizedArtifacts.push({
+          id: artifact.id,
+          kind: artifact.kind,
+          file: safeName,
+          ...artifact.status !== undefined ? { status: artifact.status } : {},
+          ...artifact.url !== undefined ? { url: artifact.url } : {},
+          ...artifact.stepIndex !== undefined ? { stepIndex: artifact.stepIndex } : {}
+        });
+      }
+      const summary = {
+        ok: true,
+        steps: result.steps,
+        artifacts: sanitizedArtifacts
+      };
+      const resultPath = join14(options.output, "result.json");
+      await fs.writeFile(resultPath, JSON.stringify(summary, null, 2));
+      harness.chmod(resultPath, 384);
+      consoleOutput.write(JSON.stringify(summary, null, 2));
+    } else {
+      consoleOutput.write(JSON.stringify({ ok: true, ...result }, null, 2));
+    }
+  });
+}
 function registerBotCommand(program, deps = {}) {
   const load = deps.load ?? loadBotHarness;
-  const bot = program.command("bot").description("Named local browser sessions (list, login, logout, open, exec)");
+  const bot = program.command("bot").description("Named local browser sessions (list, login, logout, open, exec, plan)");
   bot.command("list").description("List cached local bot profiles: name, cached, default URL, identity, last login, expires").action(() => botListAction(load));
   bot.command("login").description("Open a site headed and save it as a named bot session after terminal confirmation").argument("<url>", "Login URL to open (http/https; its query is never saved)").requiredOption("--save <name>", "Bot name matching [A-Za-z0-9][A-Za-z0-9_-]{0,63}").action((url, options) => botLoginAction(load, url, options));
   bot.command("logout").description("Remove a named bot's local profile and credentials (no server-side revocation)").argument("<name>", "Bot name").action((name) => botLogoutAction(load, name));
   bot.command("open").description("Open a named bot's saved page headed until the browser closes").argument("<name>", "Bot name").option("--login", "Reauthenticate first, then reopen the saved page for interaction").action((name, options) => botOpenAction(load, name, options));
   const exec = bot.command("exec").description("Send one request with a named bot's cached cookie session (curl option subset)").argument("<name>", "Bot name").argument("<url>", "Request URL (http/https, no credentials; sent as given, query kept)").option("-X, --request <method>", "HTTP method (default GET, or POST when -d is given)").option("-H, --header <header>", 'Request header "Name: value" (repeatable)', collectHeader).option("-d, --data <data>", "Request body: a literal, or @file read raw").option("-o, --output <file>", "Write the response body to a file instead of stdout").option("-i, --include", "Include the status line and response headers before the body (stdout or the -o file)").option("-L, --location", "Follow redirects (default: return the 3xx response as-is)").option("-f, --fail", "Exit 1 without the body when the status is 400 or above").option("-m, --max-time <seconds>", "Whole-request timeout in seconds (default: Playwright 30s)").action((name, url, options) => botExecAction(load, name, url, options));
+  const plan = bot.command("plan").description("Execute a declarative collection plan with a named bot session").argument("<name>", "Bot name").argument("<plan>", "Path to plan JSON file").option("-o, --output <dir>", "Directory to write captured artifact bodies (0600 mode)").option("-m, --max-time <seconds>", "Whole-run timeout in seconds (default: 120s, max: 600s)").action((name, planPath, options) => botPlanAction(load, name, planPath, options));
   bot.hook("preSubcommand", (_parent, subcommand) => {
-    if (subcommand === exec) {
+    if (subcommand === exec || subcommand === plan) {
       subcommand.exitOverride((error) => {
         throw error.exitCode === 1 ? new CommanderError(2, error.code, error.message) : error;
       });
@@ -48827,7 +49447,7 @@ init_commander();
 
 // src/fanin.ts
 import { tmpdir } from "os";
-import { isAbsolute as isAbsolute6, join as join14, resolve as resolve14 } from "path";
+import { isAbsolute as isAbsolute6, join as join15, resolve as resolve14 } from "path";
 init_dist3();
 init_dist();
 var DEFAULT_SOURCE_TIMEOUT_MS = 30 * 60 * 1000;
@@ -49023,7 +49643,7 @@ async function collectSourceDocs(discovery, source, timeoutMs) {
   if (!await fs.exists(entryPath)) {
     throw new Error(`Plugin entry script does not exist: ${entryPath}`);
   }
-  const outTmp = join14(tmpdir(), `kk-fanin-${source.plugin}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
+  const outTmp = join15(tmpdir(), `kk-fanin-${source.plugin}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
   try {
     const proc = await spawnPluginEntryAsync({
       entryPath,
@@ -49131,7 +49751,7 @@ async function runFanin(argv) {
 
 // src/fanout.ts
 import { tmpdir as tmpdir2 } from "os";
-import { isAbsolute as isAbsolute7, join as join15, resolve as resolve15 } from "path";
+import { isAbsolute as isAbsolute7, join as join16, resolve as resolve15 } from "path";
 init_dist3();
 init_dist();
 var EXIT_FAILURE = 1;
@@ -49419,7 +50039,7 @@ async function pluginDispatch(target, contentPath, discovery, targetTimeoutMs) {
   if (!await fs.exists(entryPath)) {
     throw new Error(`Plugin entry script does not exist: ${entryPath}`);
   }
-  const outTmp = join15(tmpdir2(), `kk-fanout-${target}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
+  const outTmp = join16(tmpdir2(), `kk-fanout-${target}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
   try {
     const proc = await spawnPluginEntryAsync({
       entryPath,
@@ -49632,7 +50252,7 @@ function registerExecutorCommand(program) {
 init_commander();
 
 // src/itc-candidates.ts
-import { join as join18 } from "path";
+import { join as join19 } from "path";
 init_dist3();
 init_dist();
 init_zod();
@@ -49805,19 +50425,19 @@ async function itcDecision(request, fs = createNodeFileSystem(), executor = new
 
 // src/itc-topic.ts
 import { createHash as createHash3 } from "crypto";
-import { join as join17, resolve as resolve17 } from "path";
+import { join as join18, resolve as resolve17 } from "path";
 init_dist3();
 init_dist();
 init_zod();
 
 // src/package-root.ts
 init_dist3();
-import { dirname as dirname11, join as join16, resolve as resolve16 } from "path";
+import { dirname as dirname11, join as join17, resolve as resolve16 } from "path";
 var SHIPPED_DIR = "plugins/kk";
 async function findPackageRoot(fs, start) {
   let dir = resolve16(start);
   for (;; ) {
-    if (await fs.exists(join16(dir, SHIPPED_DIR)))
+    if (await fs.exists(join17(dir, SHIPPED_DIR)))
       return dir;
     const parent = resolve16(dir, "..");
     if (parent === dir)
@@ -49873,7 +50493,7 @@ async function resolveTopicProfilePath(fs, topic, customPath) {
   if (customPath !== undefined && await fs.exists(customPath)) {
     return customPath;
   }
-  const candidate = join17(await resolvePackageRoot(fs), "plugins/kk/decisions/extract", `${topic}.yaml`);
+  const candidate = join18(await resolvePackageRoot(fs), "plugins/kk/decisions/extract", `${topic}.yaml`);
   if (await fs.exists(candidate))
     return candidate;
   throw new Error(`no profile for topic '${topic}': expected plugins/kk/decisions/extract/${topic}.yaml under the package root (cwd or script tree)`);
@@ -49943,9 +50563,9 @@ async function itcTopicExtract(request, fs = createNodeFileSystem()) {
     poolDigest,
     ...request.refreshRun?.runId ? { collectRunId: request.refreshRun.runId } : {}
   };
-  await fs.writeFile(join17(request.intakeDir, "topic-pool.json"), `${JSON.stringify(docs, null, 2)}
+  await fs.writeFile(join18(request.intakeDir, "topic-pool.json"), `${JSON.stringify(docs, null, 2)}
 `);
-  await fs.writeFile(join17(request.intakeDir, "topic-pool-manifest.json"), `${JSON.stringify(manifest, null, 2)}
+  await fs.writeFile(join18(request.intakeDir, "topic-pool-manifest.json"), `${JSON.stringify(manifest, null, 2)}
 `);
   return { count: docs.length, poolDigest };
 }
@@ -49968,9 +50588,9 @@ var ItcTopicValidateRequestSchema = object2({
   parentRunId: string2().min(1)
 });
 async function itcTopicValidate(request, fs = createNodeFileSystem()) {
-  const manifestPath = join17(request.intakeDir, "topic-pool-manifest.json");
-  const poolPath = join17(request.intakeDir, "topic-pool.json");
-  const candidatesPath = join17(request.intakeDir, "topic-candidates.json");
+  const manifestPath = join18(request.intakeDir, "topic-pool-manifest.json");
+  const poolPath = join18(request.intakeDir, "topic-pool.json");
+  const candidatesPath = join18(request.intakeDir, "topic-candidates.json");
   if (!await fs.exists(manifestPath) || !await fs.exists(poolPath)) {
     throw new Error(`topic pool artifacts not found in ${request.intakeDir}`);
   }
@@ -50014,7 +50634,7 @@ async function itcTopicValidate(request, fs = createNodeFileSystem()) {
       }
     }
   }
-  await fs.writeFile(join17(request.intakeDir, ".topic-candidates-valid"), `${new Date().toISOString()}
+  await fs.writeFile(join18(request.intakeDir, ".topic-candidates-valid"), `${new Date().toISOString()}
 `);
   return { valid: true };
 }
@@ -50027,9 +50647,9 @@ var ItcTopicSelectRequestSchema = object2({
 });
 async function itcTopicSelect(request, fs = createNodeFileSystem()) {
   await itcTopicValidate(request, fs);
-  const manifestPath = join17(request.intakeDir, "topic-pool-manifest.json");
-  const poolPath = join17(request.intakeDir, "topic-pool.json");
-  const candidatesPath = join17(request.intakeDir, "topic-candidates.json");
+  const manifestPath = join18(request.intakeDir, "topic-pool-manifest.json");
+  const poolPath = join18(request.intakeDir, "topic-pool.json");
+  const candidatesPath = join18(request.intakeDir, "topic-candidates.json");
   if (!await fs.exists(manifestPath) || !await fs.exists(poolPath) || !await fs.exists(candidatesPath)) {
     throw new Error(`intake artifacts missing in ${request.intakeDir}`);
   }
@@ -50042,7 +50662,7 @@ async function itcTopicSelect(request, fs = createNodeFileSystem()) {
   }
   const selectedDocSet = new Set(candidate.itemIds);
   const selectedDocs = poolDocs.filter((d) => selectedDocSet.has(d.id));
-  const selectedDocsPath = join17(request.intakeDir, "selected-docs.json");
+  const selectedDocsPath = join18(request.intakeDir, "selected-docs.json");
   await fs.writeFile(selectedDocsPath, `${JSON.stringify(selectedDocs, null, 2)}
 `);
   const chosenSource = {
@@ -50056,7 +50676,7 @@ async function itcTopicSelect(request, fs = createNodeFileSystem()) {
     itemIds: candidate.itemIds,
     selectedDocsPath
   };
-  await fs.writeFile(join17(request.intakeDir, "chosen-source.json"), `${JSON.stringify(chosenSource, null, 2)}
+  await fs.writeFile(join18(request.intakeDir, "chosen-source.json"), `${JSON.stringify(chosenSource, null, 2)}
 `);
   const storePath = await resolveStorePath(resolveKkConfigPath2(), request.dbPath);
   const store = await openStore({ path: storePath });
@@ -50095,7 +50715,7 @@ async function itcSelectionSettle(request, fs = createNodeFileSystem()) {
   const storePath = await resolveStorePath(resolveKkConfigPath2(), request.dbPath);
   if (request.outcome === "published") {
     let itemIds;
-    const chosenSourcePath = join17(request.intakeDir, "chosen-source.json");
+    const chosenSourcePath = join18(request.intakeDir, "chosen-source.json");
     if (await fs.exists(chosenSourcePath)) {
       try {
         const chosen = JSON.parse(await fs.readFile(chosenSourcePath));
@@ -50125,7 +50745,7 @@ async function itcSelectionSettle(request, fs = createNodeFileSystem()) {
       guidance: "reconcile status manually via kk store mark-published or kk store release"
     };
     await fs.ensureDir(request.intakeDir);
-    await fs.writeFile(join17(request.intakeDir, ".selection-reconcile.json"), `${JSON.stringify(reconcileInfo, null, 2)}
+    await fs.writeFile(join18(request.intakeDir, ".selection-reconcile.json"), `${JSON.stringify(reconcileInfo, null, 2)}
 `);
     return { settled: "retained", action: "reconcile_retained" };
   }
@@ -50210,7 +50830,7 @@ function buildTopicCandidates(pool) {
   return candidates;
 }
 async function runItcCandidates(options, fs = createNodeFileSystem(), executor) {
-  const intakeDir = options.intakeDir ?? join18(process.cwd(), ".itc-intake", options.parentRunId);
+  const intakeDir = options.intakeDir ?? join19(process.cwd(), ".itc-intake", options.parentRunId);
   const { count: poolCount } = await itcTopicExtract({
     schemaVersion: 1,
     parentRunId: options.parentRunId,
@@ -50221,13 +50841,13 @@ async function runItcCandidates(options, fs = createNodeFileSystem(), executor)
     ...options.limit ? { limit: options.limit } : {},
     ...options.dbPath ? { dbPath: options.dbPath } : {}
   }, fs);
-  const pool = array(DocSchema).parse(JSON.parse(await fs.readFile(join18(intakeDir, "topic-pool.json"))));
-  const manifest = JSON.parse(await fs.readFile(join18(intakeDir, "topic-pool-manifest.json")));
+  const pool = array(DocSchema).parse(JSON.parse(await fs.readFile(join19(intakeDir, "topic-pool.json"))));
+  const manifest = JSON.parse(await fs.readFile(join19(intakeDir, "topic-pool-manifest.json")));
   const candidates = buildTopicCandidates(pool);
   if (candidates.length === 0) {
     throw new Error(`no citable pool item carries a source URI: cannot build topic candidates from ${poolCount} items`);
   }
-  await fs.writeFile(join18(intakeDir, "topic-candidates.json"), `${JSON.stringify({
+  await fs.writeFile(join19(intakeDir, "topic-candidates.json"), `${JSON.stringify({
     schemaVersion: 1,
     parentRunId: options.parentRunId,
     poolDigest: manifest.poolDigest,
@@ -50239,8 +50859,8 @@ async function runItcCandidates(options, fs = createNodeFileSystem(), executor)
     parentRunId: options.parentRunId,
     decisionId: "kk-itc-topic-choice",
     candidates: candidates.map((c) => ({ id: c.id, title: c.title, description: c.reason })),
-    evidenceFiles: [join18(intakeDir, "topic-candidates.json")],
-    outPath: join18(intakeDir, "topic-decision.json")
+    evidenceFiles: [join19(intakeDir, "topic-candidates.json")],
+    outPath: join19(intakeDir, "topic-decision.json")
   }, fs, executor);
   for (const c of candidates) {
     echo(`${c.id} \u2014 ${c.title}`);
@@ -50686,14 +51306,14 @@ init_commander();
 
 // src/itc-stage.ts
 import { createHash as createHash7 } from "crypto";
-import { join as join22 } from "path";
+import { join as join23 } from "path";
 init_dist3();
 init_dist();
 
 // src/itc-config.ts
 init_dist3();
 import { createHash as createHash4 } from "crypto";
-import { dirname as dirname12, isAbsolute as isAbsolute8, join as join19, resolve as resolve20 } from "path";
+import { dirname as dirname12, isAbsolute as isAbsolute8, join as join20, resolve as resolve20 } from "path";
 
 class ItcConfigInvalidError extends Error {
   constructor(message) {
@@ -50762,7 +51382,7 @@ function expandHome3(value, homeDir) {
   if (value === "~")
     return homeDir;
   if (value.startsWith("~/"))
-    return join19(homeDir, value.slice(2));
+    return join20(homeDir, value.slice(2));
   return value;
 }
 function canonicalJson(value) {
@@ -50780,7 +51400,7 @@ function resolveItcConfigPath(env, homeDir) {
   const explicit = env.KK_CONFIG;
   if (explicit !== undefined && explicit.trim() !== "")
     return expandHome3(explicit.trim(), homeDir);
-  return join19(homeDir, ".config", "kk", "config.yaml");
+  return join20(homeDir, ".config", "kk", "config.yaml");
 }
 async function readItcConfigBlock(configPath, fs = createNodeFileSystem()) {
   if (!await fs.exists(configPath))
@@ -51124,18 +51744,18 @@ function resolveItcWorkspace(options, topic, input = {}) {
       dated: input.runDate !== undefined
     };
   }
-  const leaf = options.runDate !== null ? join19(slug, options.runDate) : slug;
-  return { workDir: join19(options.worksRoot, "kk-itc", leaf), topicName: slug, dated: options.runDate !== null };
+  const leaf = options.runDate !== null ? join20(slug, options.runDate) : slug;
+  return { workDir: join20(options.worksRoot, "kk-itc", leaf), topicName: slug, dated: options.runDate !== null };
 }
 async function writeItcOptionsSnapshot(workDir, options, fs = createNodeFileSystem()) {
-  const path = join19(workDir, "itc-options.json");
+  const path = join20(workDir, "itc-options.json");
   await fs.ensureDir(workDir);
   await fs.writeFile(path, `${JSON.stringify(options, null, 2)}
 `);
   return path;
 }
 async function verifyItcOptionsSnapshot(workDir, options, fs = createNodeFileSystem()) {
-  const path = join19(workDir, "itc-options.json");
+  const path = join20(workDir, "itc-options.json");
   if (!await fs.exists(path))
     return { ok: true };
   let saved;
@@ -51170,7 +51790,7 @@ async function verifyItcOptionsSnapshot(workDir, options, fs = createNodeFileSys
 
 // src/itc-plan.ts
 import { createHash as createHash5 } from "crypto";
-import { join as join20, resolve as resolve21 } from "path";
+import { join as join21, resolve as resolve21 } from "path";
 init_dist3();
 init_zod();
 var ItcTargetsOriginSchema = _enum2([
@@ -51218,7 +51838,7 @@ var SLUG_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 async function resolveDefaultPackageRoot(fs) {
   let dir = resolve21(process.cwd());
   for (;; ) {
-    if (await fs.exists(join20(dir, "plugins/kk/publish-presets")))
+    if (await fs.exists(join21(dir, "plugins/kk/publish-presets")))
       return dir;
     const parent = resolve21(dir, "..");
     if (parent === dir)
@@ -51376,7 +51996,7 @@ async function loadPublishPreset(slug, roots = {}, fs = createNodeFileSystem())
   return resolvePresetFromRoots(fs, slug.trim(), projectRoot, packageRoot);
 }
 async function hasCoverImage(fs, workDir) {
-  const dir = join20(workDir, "4-illustrations");
+  const dir = join21(workDir, "4-illustrations");
   if (!await fs.exists(dir))
     return false;
   try {
@@ -51387,7 +52007,7 @@ async function hasCoverImage(fs, workDir) {
   }
 }
 async function hasOrderedImages(fs, workDir) {
-  const path = join20(workDir, "4-publish", "content.json");
+  const path = join21(workDir, "4-publish", "content.json");
   if (!await fs.exists(path))
     return false;
   try {
@@ -51501,7 +52121,7 @@ async function buildItcPublishPlan(request, plugins, fs = createNodeFileSystem()
 
 // src/itc-publish.ts
 import { createHash as createHash6 } from "crypto";
-import { join as join21 } from "path";
+import { join as join22 } from "path";
 init_dist3();
 init_dist();
 init_zod();
@@ -51535,11 +52155,11 @@ var ItcReceiptSchema = object2({
   finishedAt: string2().optional()
 }).strict();
 async function findCover(fs, workDir) {
-  const dir = join21(workDir, "4-illustrations");
+  const dir = join22(workDir, "4-illustrations");
   if (!await fs.exists(dir))
     return;
   const cover = (await fs.readDir(dir)).find((file) => file.startsWith("cover."));
-  return cover ? join21(dir, cover) : undefined;
+  return cover ? join22(dir, cover) : undefined;
 }
 async function readFrontmatter(fs, path) {
   if (!await fs.exists(path))
@@ -51572,7 +52192,7 @@ async function itcMaterializePlan(args, fs = createNodeFileSystem()) {
   const snapshot = await readOptionsSnapshot(fs, workDir);
   const [targetsArg = "", sourceLocale = "", liveArg = "", presetArg = ""] = snapshot ? [snapshot.publishTargets, snapshot.sourceLocale, String(snapshot.publishLive), ""] : positional;
   const live = liveArg === "true";
-  const draftPath = join21(workDir, "3-draft-draft-article.md");
+  const draftPath = join22(workDir, "3-draft-draft-article.md");
   if (!await fs.exists(draftPath)) {
     echoError(`final draft not found: ${draftPath}`);
     return 1;
@@ -51592,10 +52212,10 @@ async function itcMaterializePlan(args, fs = createNodeFileSystem()) {
     return 1;
   }
   const content = { title, format: "markdown", body };
-  const outlinePath = join21(workDir, "2-outline", "outline-approved.md");
+  const outlinePath = join22(workDir, "2-outline", "outline-approved.md");
   if (await fs.exists(outlinePath))
     content.outline = (await fs.readFile(outlinePath)).trim();
-  const docsPath = join21(workDir, "docs.json");
+  const docsPath = join22(workDir, "docs.json");
   if (await fs.exists(docsPath)) {
     try {
       const docs = JSON.parse(await fs.readFile(docsPath));
@@ -51612,7 +52232,7 @@ async function itcMaterializePlan(args, fs = createNodeFileSystem()) {
   const cover = await findCover(fs, workDir);
   if (cover)
     metadata.coverImage = cover;
-  const brief = await readFrontmatter(fs, join21(workDir, "brief.md"));
+  const brief = await readFrontmatter(fs, join22(workDir, "brief.md"));
   if (brief.tags)
     metadata.tags = splitList(brief.tags);
   if (brief.keywords)
@@ -51620,9 +52240,9 @@ async function itcMaterializePlan(args, fs = createNodeFileSystem()) {
   if (brief.description)
     metadata.description = brief.description;
   content.metadata = metadata;
-  const publishDir = join21(workDir, "4-publish");
+  const publishDir = join22(workDir, "4-publish");
   await fs.ensureDir(publishDir);
-  await fs.writeFile(join21(publishDir, "content.json"), `${JSON.stringify(content, null, 2)}
+  await fs.writeFile(join22(publishDir, "content.json"), `${JSON.stringify(content, null, 2)}
 `);
   const fromLaunch = snapshot?.publishPresetSource === "launch" ? snapshot.publishPreset : null;
   const fromConfig = snapshot?.publishPresetSource === "config" ? snapshot.publishPreset : null;
@@ -51649,7 +52269,7 @@ async function itcMaterializePlan(args, fs = createNodeFileSystem()) {
           title: `${resolvedTargets.presetName}: ${resolvedTargets.targets.map((t) => t.plugin).join(", ")}`
         }
       ],
-      outPath: join21(workDir, "4-publish", "preset-decision.json")
+      outPath: join22(workDir, "4-publish", "preset-decision.json")
     }, fs);
     if (decision.value !== "suggested")
       resolvedTargets = { targets: [], origin: "none" };
@@ -51665,7 +52285,7 @@ async function itcMaterializePlan(args, fs = createNodeFileSystem()) {
       browser: [],
       targets: []
     };
-    await fs.writeFile(join21(publishDir, "publish-plan.json"), `${JSON.stringify(emptyPlan, null, 2)}
+    await fs.writeFile(join22(publishDir, "publish-plan.json"), `${JSON.stringify(emptyPlan, null, 2)}
 `);
     return 0;
   }
@@ -51682,7 +52302,7 @@ async function itcMaterializePlan(args, fs = createNodeFileSystem()) {
   };
   try {
     const plan = await buildItcPublishPlan(req, plugins, fs);
-    const planPath = join21(publishDir, "publish-plan.json");
+    const planPath = join22(publishDir, "publish-plan.json");
     await fs.writeFile(planPath, `${JSON.stringify(plan, null, 2)}
 `);
     await prepareTargetPayloads(fs, workDir, plan, plugins);
@@ -51693,13 +52313,13 @@ async function itcMaterializePlan(args, fs = createNodeFileSystem()) {
   }
 }
 async function readOptionsSnapshot(fs, workDir) {
-  const path = join21(workDir, "itc-options.json");
+  const path = join22(workDir, "itc-options.json");
   if (!await fs.exists(path))
     return;
   return JSON.parse(await fs.readFile(path));
 }
 async function prepareTargetPayloads(fs, workDir, plan, plugins) {
-  const publishDir = join21(workDir, "4-publish");
+  const publishDir = join22(workDir, "4-publish");
   if (!plan.targets || plan.targets.length === 0)
     return;
   const planned = new Set(plan.targets.map((t) => t.plugin));
@@ -51717,9 +52337,9 @@ async function prepareTargetPayloads(fs, workDir, plan, plugins) {
   for (const target of plan.targets) {
     const variantEntry = plan.variants[target.variant];
     const baseFile = variantEntry?.file ?? "content.json";
-    let basePath = join21(publishDir, baseFile);
+    let basePath = join22(publishDir, baseFile);
     if (!await fs.exists(basePath)) {
-      basePath = join21(publishDir, "content.json");
+      basePath = join22(publishDir, "content.json");
     }
     if (!await fs.exists(basePath))
       continue;
@@ -51736,7 +52356,7 @@ async function prepareTargetPayloads(fs, workDir, plan, plugins) {
       }
     };
     const targetFileName = `content.${target.plugin}.json`;
-    const targetFilePath = join21(publishDir, targetFileName);
+    const targetFilePath = join22(publishDir, targetFileName);
     const contentStr = `${JSON.stringify(isolatedContent, null, 2)}
 `;
     await fs.writeFile(targetFilePath, contentStr);
@@ -51744,7 +52364,7 @@ async function prepareTargetPayloads(fs, workDir, plan, plugins) {
     target.payloadPath = `4-publish/${targetFileName}`;
     target.payloadDigest = payloadDigest;
   }
-  await fs.writeFile(join21(publishDir, "publish-plan.json"), `${JSON.stringify(plan, null, 2)}
+  await fs.writeFile(join22(publishDir, "publish-plan.json"), `${JSON.stringify(plan, null, 2)}
 `);
 }
 async function probePlugin(plugin, executor = new NodeProcessExecutor) {
@@ -51779,7 +52399,7 @@ async function itcCheckTargets(args, fs = createNodeFileSystem(), executor = new
     echoError("usage: itc-check-targets <work_dir>");
     return 1;
   }
-  const planPath = join21(workDir, "4-publish/publish-plan.json");
+  const planPath = join22(workDir, "4-publish/publish-plan.json");
   if (!await fs.exists(planPath))
     return 0;
   const plan = JSON.parse(await fs.readFile(planPath));
@@ -51808,7 +52428,7 @@ async function sendRows(options) {
   const sameDigest = (priorDigest, digest) => priorDigest !== undefined && digest !== undefined && priorDigest === digest;
   for (const row of rows) {
     const startedAt = new Date().toISOString();
-    const targetReceiptPath = join21(receiptsDir, `${row.key}.json`);
+    const targetReceiptPath = join22(receiptsDir, `${row.key}.json`);
     let reattempt = false;
     let payloadPath = row.payloadPath;
     let preparedError;
@@ -51916,7 +52536,7 @@ async function sendRows(options) {
         await options.onReceipt(receipt);
       continue;
     }
-    const outPath = join21(publishDir, `fanout-result.${row.key}${retry ? ".retry" : ""}.json`);
+    const outPath = join22(publishDir, `fanout-result.${row.key}${retry ? ".retry" : ""}.json`);
     if (reattempt && await fs.exists(outPath))
       await fs.deleteFile(outPath);
     const fanoutArgs = [
@@ -51995,8 +52615,8 @@ async function itcSendTargets(args, fs = createNodeFileSystem(), dispatch = runF
     echoError("usage: itc-send-targets <work_dir> [--retry]");
     return 1;
   }
-  const publishDir = join21(workDir, "4-publish");
-  const planPath = join21(publishDir, "publish-plan.json");
+  const publishDir = join22(workDir, "4-publish");
+  const planPath = join22(publishDir, "publish-plan.json");
   if (!await fs.exists(planPath))
     return 0;
   const plan = JSON.parse(await fs.readFile(planPath));
@@ -52004,10 +52624,10 @@ async function itcSendTargets(args, fs = createNodeFileSystem(), dispatch = runF
     return 0;
   const parentRunId = (await readOptionsSnapshot(fs, workDir))?.parentRunId;
   if (!parentRunId) {
-    echoError(`itc-send-targets: ${join21(workDir, "itc-options.json")} has no parentRunId`);
+    echoError(`itc-send-targets: ${join22(workDir, "itc-options.json")} has no parentRunId`);
     return 1;
   }
-  const receiptsDir = join21(publishDir, "receipts");
+  const receiptsDir = join22(publishDir, "receipts");
   await fs.ensureDir(receiptsDir);
   const planRaw = await fs.readFile(planPath);
   const planDigest = createHash6("sha256").update(planRaw).digest("hex");
@@ -52016,7 +52636,7 @@ async function itcSendTargets(args, fs = createNodeFileSystem(), dispatch = runF
     plugin: target.plugin,
     profile: target.profile,
     mode: target.mode,
-    payloadPath: join21(workDir, target.payloadPath ?? `4-publish/content.${target.plugin}.json`),
+    payloadPath: join22(workDir, target.payloadPath ?? `4-publish/content.${target.plugin}.json`),
     transport: target.transport
   }));
   const outcome = await sendRows({
@@ -52040,12 +52660,12 @@ async function itcReconcileReceipts(args, fs = createNodeFileSystem()) {
     echoError("usage: itc-reconcile-receipts <work_dir>");
     return 1;
   }
-  const publishDir = join21(workDir, "4-publish");
-  const planPath = join21(publishDir, "publish-plan.json");
+  const publishDir = join22(workDir, "4-publish");
+  const planPath = join22(publishDir, "publish-plan.json");
   if (!await fs.exists(planPath))
     return 0;
   const plan = JSON.parse(await fs.readFile(planPath));
-  const chosenPath = join21(workDir, "chosen-source.json");
+  const chosenPath = join22(workDir, "chosen-source.json");
   const chosen = await fs.exists(chosenPath) ? JSON.parse(await fs.readFile(chosenPath)) : undefined;
   const settle = async (outcome) => {
     if (chosen === undefined)
@@ -52062,10 +52682,10 @@ async function itcReconcileReceipts(args, fs = createNodeFileSystem()) {
     await settle("author_only");
     return 0;
   }
-  const receiptsDir = join21(publishDir, "receipts");
+  const receiptsDir = join22(publishDir, "receipts");
   const receipts = [];
   for (const target of plan.targets) {
-    const rPath = join21(receiptsDir, `${target.plugin}.json`);
+    const rPath = join22(receiptsDir, `${target.plugin}.json`);
     if (!await fs.exists(rPath)) {
       echoError(`itc-reconcile-receipts: missing receipt for target '${target.plugin}'`);
       return 1;
@@ -52090,12 +52710,12 @@ async function itcExportSeo(args, fs = createNodeFileSystem()) {
     echoError("usage: itc-export-seo <work_dir> [mode]");
     return 1;
   }
-  const seoDir = join21(workDir, "seo");
+  const seoDir = join22(workDir, "seo");
   await fs.ensureDir(seoDir);
   if (mode === "off") {
-    await fs.writeFile(join21(seoDir, "prepublish-request.json"), `${JSON.stringify({ schemaVersion: 1, mode: "off", status: "not-assessed" }, null, 2)}
+    await fs.writeFile(join22(seoDir, "prepublish-request.json"), `${JSON.stringify({ schemaVersion: 1, mode: "off", status: "not-assessed" }, null, 2)}
 `);
-    await fs.writeFile(join21(seoDir, "published-pages.json"), `${JSON.stringify({ schemaVersion: 1, mode: "off", pages: [], status: "not-assessed" }, null, 2)}
+    await fs.writeFile(join22(seoDir, "published-pages.json"), `${JSON.stringify({ schemaVersion: 1, mode: "off", pages: [], status: "not-assessed" }, null, 2)}
 `);
     return 0;
   }
@@ -52105,14 +52725,14 @@ async function itcExportSeo(args, fs = createNodeFileSystem()) {
     status: "ready",
     draftFile: "3-draft-draft-article.md"
   };
-  await fs.writeFile(join21(seoDir, "prepublish-request.json"), `${JSON.stringify(prepublish, null, 2)}
+  await fs.writeFile(join22(seoDir, "prepublish-request.json"), `${JSON.stringify(prepublish, null, 2)}
 `);
-  const receiptsDir = join21(workDir, "4-publish/receipts");
+  const receiptsDir = join22(workDir, "4-publish/receipts");
   const verifiedPages = [];
   if (await fs.exists(receiptsDir)) {
     for (const file of (await fs.readDir(receiptsDir)).filter((f) => f.endsWith(".json"))) {
       try {
-        const r = JSON.parse(await fs.readFile(join21(receiptsDir, file)));
+        const r = JSON.parse(await fs.readFile(join22(receiptsDir, file)));
         if (r.mode === "live" && r.effect === "confirmed" && r.publicUrlVerified === true && r.url) {
           verifiedPages.push({ plugin: r.plugin, url: r.url });
         }
@@ -52126,7 +52746,7 @@ async function itcExportSeo(args, fs = createNodeFileSystem()) {
     pages: verifiedPages,
     ...verifiedPages.length === 0 ? { reason: "no verified public live URLs available" } : {}
   };
-  await fs.writeFile(join21(seoDir, "published-pages.json"), `${JSON.stringify(publishedPages, null, 2)}
+  await fs.writeFile(join22(seoDir, "published-pages.json"), `${JSON.stringify(publishedPages, null, 2)}
 `);
   return 0;
 }
@@ -52136,12 +52756,12 @@ async function itcReportSummary(args, fs = createNodeFileSystem()) {
     echoError("usage: itc-report-summary <work_dir> [max_revisions]");
     return 1;
   }
-  const reportDir = join21(workDir, "5-report");
+  const reportDir = join22(workDir, "5-report");
   await fs.ensureDir(reportDir);
   let verdict = "PASS";
   let confidence = null;
   let outcome = "done";
-  const verdictPath = join21(workDir, ".itc-verdict.json");
+  const verdictPath = join22(workDir, ".itc-verdict.json");
   const hasVerdict = await fs.exists(verdictPath);
   if (hasVerdict) {
     try {
@@ -52155,7 +52775,7 @@ async function itcReportSummary(args, fs = createNodeFileSystem()) {
     }
   }
   let revisions = 0;
-  const revPath = join21(workDir, ".auto-revise-count");
+  const revPath = join22(workDir, ".auto-revise-count");
   if (await fs.exists(revPath)) {
     try {
       revisions = Number((await fs.readFile(revPath)).trim()) || 0;
@@ -52163,12 +52783,12 @@ async function itcReportSummary(args, fs = createNodeFileSystem()) {
       revisions = 0;
     }
   }
-  const receiptsDir = join21(workDir, "4-publish/receipts");
+  const receiptsDir = join22(workDir, "4-publish/receipts");
   const receipts = [];
   if (await fs.exists(receiptsDir)) {
     for (const file of (await fs.readDir(receiptsDir)).filter((f) => f.endsWith(".json"))) {
       try {
-        const r = JSON.parse(await fs.readFile(join21(receiptsDir, file)));
+        const r = JSON.parse(await fs.readFile(join22(receiptsDir, file)));
         receipts.push(r);
       } catch {}
     }
@@ -52176,7 +52796,7 @@ async function itcReportSummary(args, fs = createNodeFileSystem()) {
   if (receipts.some((r) => r.status !== "succeeded")) {
     outcome = "failed";
   }
-  const planPath = join21(workDir, "4-publish/publish-plan.json");
+  const planPath = join22(workDir, "4-publish/publish-plan.json");
   let targetContract;
   if (await fs.exists(planPath)) {
     const planRaw = await fs.readFile(planPath);
@@ -52200,7 +52820,7 @@ async function itcReportSummary(args, fs = createNodeFileSystem()) {
     ...targetContract ? { targetContractFailure: targetContract } : {},
     maxRevisions: Number(maxRevisions) || 2
   };
-  await fs.writeFile(join21(reportDir, "report.json"), `${JSON.stringify(reportJson, null, 2)}
+  await fs.writeFile(join22(reportDir, "report.json"), `${JSON.stringify(reportJson, null, 2)}
 `);
   const md = [
     "# ITC Publication Run Report",
@@ -52218,7 +52838,7 @@ async function itcReportSummary(args, fs = createNodeFileSystem()) {
     ...receipts.map((r) => `- ${r.plugin} (${r.profile}): status=${r.status}, effect=${r.effect}`)
   ].join(`
 `);
-  await fs.writeFile(join21(reportDir, "report.md"), `${md}
+  await fs.writeFile(join22(reportDir, "report.md"), `${md}
 `);
   return 0;
 }
@@ -52231,13 +52851,13 @@ async function itcAuthorVerdict(args, fs = createNodeFileSystem()) {
   const auto = process.env.KK_ITC_AUTO === "true";
   const maxRevisions = Number(process.env.KK_ITC_MAX_REVISIONS ?? "2") || 2;
   const readCount = async (name) => {
-    const p = join21(workDir, name);
+    const p = join22(workDir, name);
     if (!await fs.exists(p))
       return 0;
     const n = Number((await fs.readFile(p)).trim());
     return Number.isFinite(n) ? n : 0;
   };
-  const verdictPath = join21(workDir, ".itc-verdict.json");
+  const verdictPath = join22(workDir, ".itc-verdict.json");
   let verdict = "";
   let confidence = "";
   if (await fs.exists(verdictPath)) {
@@ -52263,8 +52883,8 @@ async function itcAuthorVerdict(args, fs = createNodeFileSystem()) {
   } else {
     disposition = "fail";
   }
-  await fs.ensureDir(join21(workDir, ".itc"));
-  await fs.writeFile(join21(workDir, ".itc/disposition.txt"), `${disposition}
+  await fs.ensureDir(join22(workDir, ".itc"));
+  await fs.writeFile(join22(workDir, ".itc/disposition.txt"), `${disposition}
 `);
   return 0;
 }
@@ -52361,9 +52981,9 @@ async function runItcPublishPlan(args, fs) {
   try {
     const { plugins } = discoverAllPlugins();
     const plan = await buildItcPublishPlan(request, plugins, fs);
-    const outDir = join22(request.workDir, "4-publish");
+    const outDir = join23(request.workDir, "4-publish");
     await fs.ensureDir(outDir);
-    await fs.writeFile(join22(outDir, "publish-plan.json"), `${JSON.stringify(plan, null, 4)}
+    await fs.writeFile(join23(outDir, "publish-plan.json"), `${JSON.stringify(plan, null, 4)}
 `);
     return 0;
   } catch (err) {
@@ -52403,23 +53023,23 @@ async function runSlotDecision(args, fs) {
   }
   try {
     if (mode === "--topic") {
-      const candidatesPath = join22(dir, "topic-candidates.json");
+      const candidatesPath = join23(dir, "topic-candidates.json");
       const artifact = JSON.parse(await fs.readFile(candidatesPath));
       const result = await itcDecision({
         parentRunId,
         decisionId: "kk-itc-topic-choice",
         candidates: artifact.candidates.map((c) => ({ id: c.id, title: c.title, description: c.reason })),
         evidenceFiles: [candidatesPath],
-        outPath: join22(dir, "topic-decision.json")
+        outPath: join23(dir, "topic-decision.json")
       }, fs);
       echo(result.value);
       return 0;
     }
-    const outlineDir = join22(dir, "2-outline");
+    const outlineDir = join23(dir, "2-outline");
     const candidates = [];
     const evidenceFiles = [];
     for (const id of ["a", "b", "c"]) {
-      const file = join22(outlineDir, `outline-option-${id}.md`);
+      const file = join23(outlineDir, `outline-option-${id}.md`);
       if (!await fs.exists(file))
         continue;
       const heading = (await fs.readFile(file)).split(`
@@ -52429,18 +53049,18 @@ async function runSlotDecision(args, fs) {
     }
     if (candidates.length === 0)
       throw new Error(`no outline options in ${outlineDir}`);
-    evidenceFiles.push(join22(outlineDir, "outline-recommendation.json"));
+    evidenceFiles.push(join23(outlineDir, "outline-recommendation.json"));
     const result = await itcDecision({
       parentRunId,
       decisionId: "kk-itc-outline-choice",
       candidates,
       evidenceFiles,
-      outPath: join22(outlineDir, "outline-decision.json")
+      outPath: join23(outlineDir, "outline-decision.json")
     }, fs);
     const pick = result.value === "defer" ? "" : result.value;
     if (pick === "")
       echoError(`itc-decision: outline choice deferred to the operator: ${result.reason}`);
-    await fs.writeFile(join22(outlineDir, ".auto-pick"), pick);
+    await fs.writeFile(join23(outlineDir, ".auto-pick"), pick);
     return 0;
   } catch (err) {
     echoError(`itc-decision: ${err instanceof Error ? err.message : String(err)}`);
@@ -52453,7 +53073,7 @@ async function runItcAuthorComplete(args, fs) {
     echoError("usage: itc-author-complete <work_dir> <parentRunId> [reviewMode]");
     return 1;
   }
-  const draftPath = join22(workDir, "3-draft-draft-article.md");
+  const draftPath = join23(workDir, "3-draft-draft-article.md");
   if (!await fs.exists(draftPath)) {
     echoError(`itc-author-complete: draft not found: ${draftPath}`);
     return 1;
@@ -52464,7 +53084,7 @@ async function runItcAuthorComplete(args, fs) {
     return 1;
   }
   const draftDigest = createHash7("sha256").update(draftText).digest("hex");
-  const outlinePath = join22(workDir, "2-outline/outline-approved.md");
+  const outlinePath = join23(workDir, "2-outline/outline-approved.md");
   if (!await fs.exists(outlinePath)) {
     echoError(`itc-author-complete: approved outline not found: ${outlinePath}`);
     return 1;
@@ -52475,7 +53095,7 @@ async function runItcAuthorComplete(args, fs) {
     return 1;
   }
   const outlineDigest = createHash7("sha256").update(outlineText).digest("hex");
-  const verdictPath = join22(workDir, ".itc-verdict.json");
+  const verdictPath = join23(workDir, ".itc-verdict.json");
   let judgeDigest = null;
   let reviewMode = reviewModeArg === "manual" ? "manual" : "judged";
   if (await fs.exists(verdictPath)) {
@@ -52500,7 +53120,7 @@ async function runItcAuthorComplete(args, fs) {
   } else {
     reviewMode = "manual";
   }
-  const runPath = join22(workDir, ".itc/author-run.json");
+  const runPath = join23(workDir, ".itc/author-run.json");
   let childRunId = `${parentRunId}-author`;
   if (await fs.exists(runPath)) {
     try {
@@ -52519,9 +53139,9 @@ async function runItcAuthorComplete(args, fs) {
     reviewMode,
     status: "complete"
   };
-  const itcDir = join22(workDir, ".itc");
+  const itcDir = join23(workDir, ".itc");
   await fs.ensureDir(itcDir);
-  await fs.writeFile(join22(itcDir, "author-complete.json"), `${JSON.stringify(completeReceipt, null, 2)}
+  await fs.writeFile(join23(itcDir, "author-complete.json"), `${JSON.stringify(completeReceipt, null, 2)}
 `);
   return 0;
 }
@@ -52559,7 +53179,7 @@ async function runItcPrepare(args, fs) {
       echoError("itc-prepare: --chosen applies only to a --from-collect launch");
       return 1;
     }
-    const chosenPath = join22(intakeDir, "chosen-source.json");
+    const chosenPath = join23(intakeDir, "chosen-source.json");
     if (!await fs.exists(chosenPath)) {
       echoError(`itc-prepare: chosen source not found: ${chosenPath}`);
       return 1;
@@ -52595,9 +53215,9 @@ async function runItcPrepare(args, fs) {
         ["topic-pool-manifest.json", "topic-pool-manifest.json"]
       ];
       for (const [from, to] of copies) {
-        const src = join22(intakeDir, from);
+        const src = join23(intakeDir, from);
         if (await fs.exists(src))
-          await fs.writeFile(join22(workDir, to), await fs.readFile(src));
+          await fs.writeFile(join23(workDir, to), await fs.readFile(src));
       }
     }
   } catch (err) {
@@ -52613,7 +53233,7 @@ init_dist3();
 
 // src/publish-matrix.ts
 import { createHash as createHash8 } from "crypto";
-import { dirname as dirname13, join as join23, resolve as resolve22 } from "path";
+import { dirname as dirname13, join as join24, resolve as resolve22 } from "path";
 init_dist3();
 init_dist();
 init_zod();
@@ -52750,7 +53370,7 @@ function listValue(args, flag) {
 }
 async function appendEvent(fs, publishDir, event) {
   await fs.ensureDir(publishDir);
-  const path = join23(publishDir, "publish-events.jsonl");
+  const path = join24(publishDir, "publish-events.jsonl");
   const prior = await fs.exists(path) ? await fs.readFile(path) : "";
   await fs.writeFile(path, `${prior}${JSON.stringify({ at: new Date().toISOString(), ...event })}
 `);
@@ -52778,7 +53398,7 @@ async function runPublishMatrixValidate(args, deps = {}) {
   let candidate = raw === undefined || raw.trim() === "" ? undefined : raw;
   if (candidate === undefined) {
     source = "bundle.json";
-    const bundlePath = join23(workDir, "bundle.json");
+    const bundlePath = join24(workDir, "bundle.json");
     if (!await fs.exists(bundlePath)) {
       echoError(`publish-matrix-validate: no --run-date and no bundle at ${bundlePath} to derive one from`);
       return 1;
@@ -52799,8 +53419,8 @@ async function runPublishMatrixValidate(args, deps = {}) {
     echoError(`publish-matrix-validate: run date '${candidate}' (from ${source}) is not a valid calendar day (YYYY-MM-DD or YYYYMMDD)`);
     return 1;
   }
-  await fs.ensureDir(join23(workDir, "4-publish"));
-  await fs.writeFile(join23(workDir, "4-publish", "run-date.txt"), `${normalized}
+  await fs.ensureDir(join24(workDir, "4-publish"));
+  await fs.writeFile(join24(workDir, "4-publish", "run-date.txt"), `${normalized}
 `);
   echo(`run date ${normalized} (from ${source})`);
   return 0;
@@ -52810,7 +53430,7 @@ var LINK_SOURCES = [
   { placeholder: "{{podcast_url}}", plugin: "podcast-pub", receipt: "podcast" }
 ];
 async function readPlan(fs, workDir, window) {
-  const planPath = join23(workDir, "4-publish", `plan.${window}.json`);
+  const planPath = join24(workDir, "4-publish", `plan.${window}.json`);
   if (!await fs.exists(planPath)) {
     throw new Error(`no plan at ${planPath}; run publish-matrix-plan first`);
   }
@@ -52981,8 +53601,8 @@ async function composePlan(fs, input) {
       variantPath: entry.path,
       variantDigest: entry.sha256
     });
-    await fs.ensureDir(join23(input.workDir, "4-publish", "payloads"));
-    await fs.writeFile(join23(input.workDir, payloadRelative), payloadText);
+    await fs.ensureDir(join24(input.workDir, "4-publish", "payloads"));
+    await fs.writeFile(join24(input.workDir, payloadRelative), payloadText);
   }
   return {
     plan: {
@@ -53033,11 +53653,11 @@ async function planPublishMatrix(args, deps = {}) {
       dummy,
       ...deps.projectRoot ? { projectRoot: deps.projectRoot } : {}
     });
-    const publishDir = join23(workDir, "4-publish");
+    const publishDir = join24(workDir, "4-publish");
     await fs.ensureDir(publishDir);
     const planText = `${JSON.stringify(plan, null, 2)}
 `;
-    await fs.writeFile(join23(publishDir, `plan.${plan.window}.json`), planText);
+    await fs.writeFile(join24(publishDir, `plan.${plan.window}.json`), planText);
     const planDigest = createHash8("sha256").update(planText).digest("hex");
     for (const target of omitted) {
       const receipt = {
@@ -53055,8 +53675,8 @@ async function planPublishMatrix(args, deps = {}) {
         window: plan.window,
         ...target.mode === "dummy" ? { dummy: true } : {}
       };
-      await fs.ensureDir(join23(publishDir, "receipts"));
-      await fs.writeFile(join23(publishDir, "receipts", `${target.id}.json`), `${JSON.stringify(receipt, null, 2)}
+      await fs.ensureDir(join24(publishDir, "receipts"));
+      await fs.writeFile(join24(publishDir, "receipts", `${target.id}.json`), `${JSON.stringify(receipt, null, 2)}
 `);
       await appendEvent(fs, publishDir, {
         event: "omitted",
@@ -53138,9 +53758,9 @@ async function checkPublishMatrix(args, deps = {}) {
         echoError(`publish-matrix-check: channel probe for '${name}' refused: ${probe.detail ?? "unknown"}`);
       }
     }
-    const publishDir = join23(workDir, "4-publish");
+    const publishDir = join24(workDir, "4-publish");
     await fs.ensureDir(publishDir);
-    await fs.writeFile(join23(publishDir, outFile), `${JSON.stringify({ schemaVersion: 1, window: label, plugins: probes }, null, 2)}
+    await fs.writeFile(join24(publishDir, outFile), `${JSON.stringify({ schemaVersion: 1, window: label, plugins: probes }, null, 2)}
 `);
     echo(names.length === 0 ? "no probes" : `${probes.length} probe(s) recorded for ${label}`);
     return 0;
@@ -53168,7 +53788,7 @@ async function runPublishMatrixClassify(args, deps = {}) {
     echoError(`publish-matrix-classify: unknown window '${windowArg}'`);
     return 1;
   }
-  const publishDir = join23(workDir, "4-publish");
+  const publishDir = join24(workDir, "4-publish");
   let plan;
   try {
     plan = await readPlan(fs, workDir, parsedWindow.data);
@@ -53183,7 +53803,7 @@ async function runPublishMatrixClassify(args, deps = {}) {
     echoError(`publish-matrix-classify: ${err instanceof Error ? err.message : String(err)}`);
     await fs.ensureDir(publishDir);
     const noneDate = runDate ?? await (async () => {
-      const stampPath = join23(publishDir, "run-date.txt");
+      const stampPath = join24(publishDir, "run-date.txt");
       if (!await fs.exists(stampPath))
         return;
       return normalizeRunDate((await fs.readFile(stampPath)).trim());
@@ -53198,16 +53818,16 @@ async function runPublishMatrixClassify(args, deps = {}) {
       excluded: [],
       rows: []
     };
-    await fs.writeFile(join23(publishDir, `outcome.${parsedWindow.data}.json`), `${JSON.stringify(none, null, 2)}
+    await fs.writeFile(join24(publishDir, `outcome.${parsedWindow.data}.json`), `${JSON.stringify(none, null, 2)}
 `);
-    await fs.writeFile(join23(publishDir, `publish-status.${parsedWindow.data}.txt`), `none
+    await fs.writeFile(join24(publishDir, `publish-status.${parsedWindow.data}.txt`), `none
 `);
-    await fs.writeFile(join23(workDir, "publish-classify.summary.txt"), `${JSON.stringify({ status: "none", published: 0, targets: 0 })}
+    await fs.writeFile(join24(workDir, "publish-classify.summary.txt"), `${JSON.stringify({ status: "none", published: 0, targets: 0 })}
 `);
     return 0;
   }
   if (runDate === undefined) {
-    const stampPath = join23(publishDir, "run-date.txt");
+    const stampPath = join24(publishDir, "run-date.txt");
     const stamp = await fs.exists(stampPath) ? normalizeRunDate((await fs.readFile(stampPath)).trim()) : undefined;
     if (stamp === undefined) {
       echoError("publish-matrix-classify: plan has no runDate and no usable --run-date/run-date.txt was provided");
@@ -53215,27 +53835,27 @@ async function runPublishMatrixClassify(args, deps = {}) {
     }
     runDate = stamp;
   }
-  const receiptsDir = join23(publishDir, "receipts");
+  const receiptsDir = join24(publishDir, "receipts");
   const receipts = [];
   if (await fs.exists(receiptsDir)) {
     for (const name of await fs.readDir(receiptsDir)) {
       if (!name.endsWith(".json"))
         continue;
       try {
-        receipts.push(JSON.parse(await fs.readFile(join23(receiptsDir, name))));
+        receipts.push(JSON.parse(await fs.readFile(join24(receiptsDir, name))));
       } catch {}
     }
   }
   const outcome = classifyPublishMatrix(plan, receipts, runDate);
   await fs.ensureDir(publishDir);
-  await fs.writeFile(join23(publishDir, `outcome.${outcome.window}.json`), `${JSON.stringify(outcome, null, 2)}
+  await fs.writeFile(join24(publishDir, `outcome.${outcome.window}.json`), `${JSON.stringify(outcome, null, 2)}
 `);
-  await fs.writeFile(join23(publishDir, `publish-status.${outcome.window}.txt`), `${outcome.status}
+  await fs.writeFile(join24(publishDir, `publish-status.${outcome.window}.txt`), `${outcome.status}
 `);
-  await fs.writeFile(join23(workDir, "publish-classify.summary.txt"), `${JSON.stringify({ status: outcome.status, published: outcome.published, targets: outcome.targets })}
+  await fs.writeFile(join24(workDir, "publish-classify.summary.txt"), `${JSON.stringify({ status: outcome.status, published: outcome.published, targets: outcome.targets })}
 `);
   if (outcome.window === "after-generate") {
-    const legacyDir = join23(workDir, "31-publish");
+    const legacyDir = join24(workDir, "31-publish");
     for (const source of LEGACY_RESULT_FILES) {
       const row = plan.rows.find((candidate) => candidate.plugin === source.plugin && candidate.tier === 0);
       if (row === undefined || row.mode === "dummy")
@@ -53247,7 +53867,7 @@ async function runPublishMatrixClassify(args, deps = {}) {
       if (!await fs.exists(aggregate))
         continue;
       await fs.ensureDir(legacyDir);
-      await fs.writeFile(join23(legacyDir, `${runDate.replaceAll("-", "")}${source.file}`), await fs.readFile(aggregate));
+      await fs.writeFile(join24(legacyDir, `${runDate.replaceAll("-", "")}${source.file}`), await fs.readFile(aggregate));
     }
   }
   echo(outcome.status);
@@ -53269,7 +53889,7 @@ async function runPublishMatrixSettle(args, deps = {}) {
     echoError(`publish-matrix-settle: unknown window '${windowArg}'`);
     return 1;
   }
-  const publishDir = join23(workDir, "4-publish");
+  const publishDir = join24(workDir, "4-publish");
   let plan;
   try {
     plan = await readPlan(fs, workDir, parsedWindow.data);
@@ -53278,9 +53898,9 @@ async function runPublishMatrixSettle(args, deps = {}) {
     return 1;
   }
   const parentRunId = plan.parentRunId;
-  const receiptsDir = join23(publishDir, "receipts");
+  const receiptsDir = join24(publishDir, "receipts");
   const receiptFor = async (id) => {
-    const path = join23(receiptsDir, `${id}.json`);
+    const path = join24(receiptsDir, `${id}.json`);
     if (!await fs.exists(path))
       return;
     try {
@@ -53332,7 +53952,7 @@ async function runPublishMatrixSettle(args, deps = {}) {
     unresolved
   };
   await fs.ensureDir(publishDir);
-  const settlementPath = join23(publishDir, `settlement.${parsedWindow.data}.json`);
+  const settlementPath = join24(publishDir, `settlement.${parsedWindow.data}.json`);
   if (unresolved.length > 0) {
     await fs.writeFile(settlementPath, `${JSON.stringify(settlement, null, 2)}
 `);
@@ -53398,7 +54018,7 @@ async function writeDummyReceipt(fs, row, context) {
   };
 }
 async function readSucceeded(fs, receiptsDir, id) {
-  const path = join23(receiptsDir, `${id}.json`);
+  const path = join24(receiptsDir, `${id}.json`);
   if (!await fs.exists(path))
     return false;
   try {
@@ -53415,7 +54035,7 @@ async function readLinkMap(fs, publishDir, plan) {
   const planPaths = (await fs.exists(publishDir) ? await fs.readDir(publishDir) : []).filter((name) => /^plan\..*\.json$/.test(name));
   for (const name of planPaths) {
     try {
-      const candidate = JSON.parse(await fs.readFile(join23(publishDir, name)));
+      const candidate = JSON.parse(await fs.readFile(join24(publishDir, name)));
       if (candidate.parentRunId !== plan.parentRunId)
         continue;
       for (const row of candidate.rows) {
@@ -53428,7 +54048,7 @@ async function readLinkMap(fs, publishDir, plan) {
     const entry = tierZero.find((candidate) => candidate.plugin === source.plugin);
     if (entry === undefined)
       continue;
-    const path = join23(publishDir, "receipts", `${entry.rowId}.json`);
+    const path = join24(publishDir, "receipts", `${entry.rowId}.json`);
     if (!await fs.exists(path))
       continue;
     try {
@@ -53471,17 +54091,17 @@ async function sendPublishMatrix(args, deps = {}) {
   }
   try {
     const plan = await readPlan(fs, workDir, parsedWindow.data);
-    const publishDir = join23(workDir, "4-publish");
-    const receiptsDir = join23(publishDir, "receipts");
+    const publishDir = join24(workDir, "4-publish");
+    const receiptsDir = join24(publishDir, "receipts");
     await fs.ensureDir(receiptsDir);
-    const planDigest = createHash8("sha256").update(await fs.readFile(join23(publishDir, `plan.${plan.window}.json`))).digest("hex");
+    const planDigest = createHash8("sha256").update(await fs.readFile(join24(publishDir, `plan.${plan.window}.json`))).digest("hex");
     const succeededAlready = (id) => readSucceeded(fs, receiptsDir, id);
     const tiers = [...new Set(plan.rows.map((row) => row.tier))].sort((a, b) => a - b);
     const pending = onlyTier === undefined ? plan.rows : plan.rows.filter((row) => row.tier === onlyTier);
     for (const row of pending) {
       if (row.mode === "dummy")
         continue;
-      const payloadPath = join23(workDir, row.payloadPath);
+      const payloadPath = join24(workDir, row.payloadPath);
       const payloadRaw = await fs.exists(payloadPath) ? await fs.readFile(payloadPath) : null;
       if (payloadRaw === null) {
         throw new Error(`payload missing for '${row.id}': ${payloadPath}; re-run publish-matrix-plan`);
@@ -53491,7 +54111,7 @@ async function sendPublishMatrix(args, deps = {}) {
         throw new Error(`payload for '${row.id}' changed after the plan was frozen (reviewed ${row.payloadDigest}, on disk ${payloadActual}); re-run publish-matrix-plan`);
       }
       if (row.variantPath !== undefined && row.variantDigest !== undefined) {
-        const variantPath = join23(workDir, row.variantPath);
+        const variantPath = join24(workDir, row.variantPath);
         const variantRaw = await fs.exists(variantPath) ? await fs.readFile(variantPath) : null;
         if (variantRaw === null) {
           throw new Error(`variant source missing for '${row.id}': ${variantPath}; re-run publish-matrix-plan`);
@@ -53525,7 +54145,7 @@ async function sendPublishMatrix(args, deps = {}) {
         plugin: row.plugin,
         profile: row.profile ?? "article",
         mode: row.mode,
-        payloadPath: join23(workDir, row.payloadPath),
+        payloadPath: join24(workDir, row.payloadPath),
         transport: "fanout",
         receiptExtras: { target: row.id, window: plan.window }
       }));
@@ -53555,7 +54175,7 @@ async function sendPublishMatrix(args, deps = {}) {
           if (LINK_SOURCES.some((source) => resolved.includes(source.placeholder))) {
             return { error: "unresolved-link" };
           }
-          const resolvedPath = join23(workDir, "4-publish", "payloads", `content.${row.key}.resolved.json`);
+          const resolvedPath = join24(workDir, "4-publish", "payloads", `content.${row.key}.resolved.json`);
           await fs.writeFile(resolvedPath, resolved);
           return { payloadPath: resolvedPath };
         },
@@ -53627,16 +54247,16 @@ async function runPublishMatrixRssGate(args, deps = {}) {
     echoError("usage: publish-matrix-rss-gate <work_dir> [--date <YYYY-MM-DD|YYYYMMDD>] [--feed <url>]");
     return 1;
   }
-  const publishDir = join23(workDir, "4-publish");
+  const publishDir = join24(workDir, "4-publish");
   let date = dateRaw !== undefined && dateRaw.trim() !== "" ? normalizeRunDate(dateRaw) : undefined;
   if (dateRaw !== undefined && dateRaw.trim() !== "" && date === undefined) {
     echoError(`publish-matrix-rss-gate: '${dateRaw}' is not a valid calendar day (YYYY-MM-DD or YYYYMMDD)`);
     return 1;
   }
   let guid = "";
-  const receiptsDir = join23(publishDir, "receipts");
+  const receiptsDir = join24(publishDir, "receipts");
   for (const planWindow of ["after-generate", "cn-peak"]) {
-    const planPath = join23(publishDir, `plan.${planWindow}.json`);
+    const planPath = join24(publishDir, `plan.${planWindow}.json`);
     if (!await fs.exists(planPath))
       continue;
     const plan = JSON.parse(await fs.readFile(planPath));
@@ -53652,7 +54272,7 @@ async function runPublishMatrixRssGate(args, deps = {}) {
     for (const row of plan.rows) {
       if (row.plugin !== "podcast-pub")
         continue;
-      const receiptPath = join23(receiptsDir, `${row.id}.json`);
+      const receiptPath = join24(receiptsDir, `${row.id}.json`);
       if (!await fs.exists(receiptPath))
         continue;
       const receipt = JSON.parse(await fs.readFile(receiptPath));
@@ -53661,7 +54281,7 @@ async function runPublishMatrixRssGate(args, deps = {}) {
     }
   }
   if (date === undefined) {
-    const stampPath = join23(publishDir, "run-date.txt");
+    const stampPath = join24(publishDir, "run-date.txt");
     const stamp = await fs.exists(stampPath) ? normalizeRunDate((await fs.readFile(stampPath)).trim()) : undefined;
     if (stamp === undefined) {
       echoError("publish-matrix-rss-gate: no usable --date and no run-date.txt/plan.runDate to derive one from");
@@ -53671,7 +54291,7 @@ async function runPublishMatrixRssGate(args, deps = {}) {
   }
   const write = async (result) => {
     await fs.ensureDir(publishDir);
-    await fs.writeFile(join23(publishDir, "rss-gate.json"), `${JSON.stringify(result, null, 2)}
+    await fs.writeFile(join24(publishDir, "rss-gate.json"), `${JSON.stringify(result, null, 2)}
 `);
     await appendEvent(fs, publishDir, {
       event: result.hit ? "gate-hit" : "gate-miss",
@@ -53687,9 +54307,9 @@ async function runPublishMatrixRssGate(args, deps = {}) {
         reason: `feed ${result.feedUrl} has no episode for ${result.date} (${result.reason})`,
         evidence: ["4-publish/rss-gate.json", ...result.detail === undefined ? [] : [result.detail]]
       };
-      await fs.writeFile(join23(publishDir, "incident.json"), `${JSON.stringify(incident, null, 2)}
+      await fs.writeFile(join24(publishDir, "incident.json"), `${JSON.stringify(incident, null, 2)}
 `);
-      await fs.writeFile(join23(publishDir, "incident.md"), [
+      await fs.writeFile(join24(publishDir, "incident.md"), [
         `# Overseas window missed \u2014 ${result.date}`,
         "",
         `The podcast feed \`${result.feedUrl}\` does not carry the ${result.date} episode (${result.reason}).`,
@@ -53828,7 +54448,7 @@ async function runPublishMatrixBundle(args, deps = {}) {
     echoError("usage: publish-matrix-bundle <work_dir> --run-date <YYYY-MM-DD> --run-id <voice3 run id> [--preset <slug>]");
     return 1;
   }
-  const variantsDir = join23(workDir, "30-variants");
+  const variantsDir = join24(workDir, "30-variants");
   if (!await fs.exists(variantsDir)) {
     echoError(`publish-matrix-bundle: no variants at ${variantsDir}; run daily-bundle-variants first`);
     return 1;
@@ -53840,7 +54460,7 @@ async function runPublishMatrixBundle(args, deps = {}) {
     const variants = {};
     for (const file of entries) {
       const key = file.replace(/\.content\.json$/, "").replaceAll("_", ":");
-      const raw = await fs.readFile(join23(variantsDir, file));
+      const raw = await fs.readFile(join24(variantsDir, file));
       const parsed = ContentSchema.safeParse(JSON.parse(raw));
       if (!parsed.success) {
         throw new Error(`variant '${key}' is not valid Content: ${parsed.error.message}`);
@@ -53864,7 +54484,7 @@ async function runPublishMatrixBundle(args, deps = {}) {
       }
     }
     const articleTitle = await readVariantTitle(fs, workDir, variants);
-    const safetyPath = join23(workDir, "4-safety-variants", "safety.json");
+    const safetyPath = join24(workDir, "4-safety-variants", "safety.json");
     let safety;
     if (await fs.exists(safetyPath)) {
       const safetyParsed = BundleSafetySchema.safeParse(JSON.parse(await fs.readFile(safetyPath)));
@@ -53885,7 +54505,7 @@ async function runPublishMatrixBundle(args, deps = {}) {
       ...safety !== undefined ? { safety } : {}
     };
     const validated = BundleSchema.parse(bundle);
-    const bundlePath = join23(workDir, "bundle.json");
+    const bundlePath = join24(workDir, "bundle.json");
     if (await fs.exists(bundlePath)) {
       try {
         const prior = BundleSchema.parse(JSON.parse(await fs.readFile(bundlePath)));
@@ -53912,7 +54532,7 @@ async function readVariantTitle(fs, workDir, variants) {
     if (entry === undefined)
       continue;
     try {
-      const parsed = ContentSchema.parse(JSON.parse(await fs.readFile(join23(workDir, entry.path))));
+      const parsed = ContentSchema.parse(JSON.parse(await fs.readFile(join24(workDir, entry.path))));
       if (parsed.title !== undefined && parsed.title.trim() !== "")
         return parsed.title.trim();
     } catch {}
@@ -53982,7 +54602,7 @@ function registerStageCommand(program) {
 }
 
 // src/commands/store.ts
-import { dirname as dirname14, join as join25, resolve as resolve24 } from "path";
+import { dirname as dirname14, join as join26, resolve as resolve24 } from "path";
 init_dist3();
 init_commander();
 
@@ -53990,7 +54610,7 @@ init_commander();
 init_dist3();
 import { randomUUID as randomUUID2 } from "crypto";
 import { tmpdir as tmpdir3 } from "os";
-import { join as join24, resolve as resolve23 } from "path";
+import { join as join25, resolve as resolve23 } from "path";
 var STORE_CATALOG_PATH_REL = "plugins/kk/decisions/kk-items.yaml";
 var SPUR_CONFIG_PATH_REL = ".spur/config.yaml";
 var EVIDENCE_MAX_CHARS = 2000;
@@ -54019,7 +54639,7 @@ async function loadInjectedHub() {
 }
 async function readDecisionRouting(projectRoot, fs = createNodeFileSystem()) {
   const catalogPath = await resolveCatalogPath(projectRoot, fs);
-  const configPath = join24(projectRoot, SPUR_CONFIG_PATH_REL);
+  const configPath = join25(projectRoot, SPUR_CONFIG_PATH_REL);
   if (!await fs.exists(configPath))
     return { catalogPath, routing: { makers: {} } };
   let parsed;
@@ -54103,8 +54723,8 @@ function createBufferedDecisionFetch(inner = fetch) {
 var bufferedDecisionFetch = createBufferedDecisionFetch();
 function runDecisionSubprocess(decisionId, input, maker, fs = createNodeFileSystem()) {
   const command = process.env.KK_SPUR_BIN ?? "spur";
-  const scratch = join24(tmpdir3(), `kk-decision-${randomUUID2()}`);
-  const evidencePath = join24(scratch, "evidence.md");
+  const scratch = join25(tmpdir3(), `kk-decision-${randomUUID2()}`);
+  const evidencePath = join25(scratch, "evidence.md");
   try {
     fs.writeFile(evidencePath, input.body);
     const args = [
@@ -54340,8 +54960,8 @@ async function readAnnotations(fs, outputPath) {
 async function heuristicAnnotations(fs, scratch, runId, items) {
   if (items.length === 0)
     return new Map;
-  const inputPath = join25(scratch, "label-input.json");
-  const outputPath = join25(scratch, "label-out.json");
+  const inputPath = join26(scratch, "label-input.json");
+  const outputPath = join26(scratch, "label-out.json");
   await fs.ensureDir(scratch);
   const docs = items.map((item) => ({
     id: item.id,
@@ -54692,7 +55312,7 @@ async function labelAction(options) {
     const mode = parseLabelMode(options.mode);
     const configPath = resolveKkConfigPath();
     const dbPath = await resolveStorePath(configPath, options.db);
-    const scratch = join25(dirname14(plan.kind === "new-ids" ? plan.newIds : dbPath), LABEL_SCRATCH_DIR);
+    const scratch = join26(dirname14(plan.kind === "new-ids" ? plan.newIds : dbPath), LABEL_SCRATCH_DIR);
     const store = await openStore({ path: dbPath });
     const catalogVersion = await readCatalogVersion(fs);
     const labels = (await readStoreConfig(configPath)).labels;