@app-vitals/agent-runtime 0.0.1 → 0.1.1

package/cron-handler.ts

@@ -0,0 +1,750 @@
+/**
+ * Agent cron request handler.
+ *
+ * Receives a cron payload, runs the prompt through Claude, and posts the
+ * result to Slack. Extracted as a pure function with injected deps for
+ * testability.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import type { WebClient } from "@slack/web-api";
+import {
+  ClaudeRunError,
+  type ClaudeRunResult,
+  ClaudeTimeoutError,
+  type EarlySessionIdCallback,
+  type ModelUsage,
+  type ProgressCallback,
+  type TokenUsage,
+} from "./claude.ts";
+import { type Clock, SystemClock } from "./clock.ts";
+import type { RunContextStamp } from "./context-stamp.ts";
+import { markCronRunFailureReported } from "./cron-failure-reporter.ts";
+import type {
+  ContextBaselineEntry,
+  CronRunReporter,
+  ModelBreakdownEntry,
+  SkillUsageEntry,
+} from "./cron-run-reporter.ts";
+import { markdownToSlack } from "./format.ts";
+import { parseMarkers } from "./markers.ts";
+import type { RunTelemetry } from "./run-telemetry.ts";
+import { dispatchMarkers, type SynthesizeSpeechFn } from "./slack.ts";
+import { buildSpawnEnv } from "./spawn-env.ts";
+import type { VoiceConfig } from "./voice.ts";
+
+/**
+ * Optional per-run measurement folded into the token payload: the stream
+ * telemetry (`run-telemetry.ts`) and the always-loaded-context stamp
+ * (`context-stamp.ts`). Both are additive — a caller that passes neither
+ * gets exactly the pre-existing payload shape.
+ */
+export interface TokenPayloadExtras {
+  telemetry?: RunTelemetry;
+  contextStamp?: RunContextStamp;
+}
+
+export function buildTokenPayload(
+  usage: TokenUsage | undefined,
+  modelUsage: ModelUsage | undefined,
+  extras?: TokenPayloadExtras,
+): {
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheReadTokens?: number;
+  cacheCreationTokens?: number;
+  modelBreakdown?: ModelBreakdownEntry[];
+  contextBaseline?: ContextBaselineEntry;
+  turns?: number;
+  toolCalls?: number;
+  skillUsage?: SkillUsageEntry[];
+  contextFingerprint?: string;
+  pluginVersion?: string;
+  claudeCodeVersion?: string;
+} {
+  // Build per-model breakdown when modelUsage has entries
+  let modelBreakdown: ModelBreakdownEntry[] | undefined;
+  if (modelUsage && Object.keys(modelUsage).length > 0) {
+    modelBreakdown = Object.entries(modelUsage).map(([model, mu]) => ({
+      model,
+      inputTokens: mu.inputTokens,
+      outputTokens: mu.outputTokens,
+      cacheReadTokens: mu.cacheReadInputTokens,
+      cacheCreationTokens: mu.cacheCreationInputTokens,
+      costUsd: mu.costUSD,
+    }));
+  }
+
+  const telemetry = extras?.telemetry;
+  const stamp = extras?.contextStamp;
+  const firstTurn = telemetry?.firstTurn;
+
+  return {
+    inputTokens: usage?.input_tokens,
+    outputTokens: usage?.output_tokens,
+    cacheReadTokens: usage?.cache_read_input_tokens,
+    cacheCreationTokens: usage?.cache_creation_input_tokens,
+    ...(modelBreakdown !== undefined && { modelBreakdown }),
+    ...(firstTurn !== undefined && {
+      contextBaseline: {
+        model: firstTurn.model,
+        contextTokens: firstTurn.contextTokens,
+        inputTokens: firstTurn.inputTokens,
+        cacheCreationTokens: firstTurn.cacheCreationTokens,
+        cacheReadTokens: firstTurn.cacheReadTokens,
+      },
+    }),
+    ...(telemetry !== undefined && {
+      turns: telemetry.turns,
+      toolCalls: telemetry.toolCalls,
+    }),
+    ...(telemetry !== undefined &&
+      telemetry.skillUsage.length > 0 && { skillUsage: telemetry.skillUsage }),
+    ...(stamp !== undefined && {
+      contextFingerprint: stamp.contextFingerprint,
+    }),
+    ...(stamp?.pluginVersion != null && { pluginVersion: stamp.pluginVersion }),
+    ...(stamp?.claudeCodeVersion != null && {
+      claudeCodeVersion: stamp.claudeCodeVersion,
+    }),
+  };
+}
+
+/**
+ * The claude runner — sends a one-shot cron-dispatched message. The optional
+ * second `onProgress` param (CSU-1.1) is fired as each new assistant turn
+ * completes, with a fresh accumulated per-model usage snapshot — wired to
+ * cronRunReporter.recordProgress (debounced) inside handleCronRequest so
+ * token totals survive an agent-process kill mid-run, not just a clean
+ * completion. Mirrors loop-orchestrator.ts's runner signature (CSU-3.1).
+ */
+type ClaudeRunner = (
+  message: string,
+  onProgress?: ProgressCallback,
+  extraEnv?: Record<string, string>,
+  onEarlySessionId?: EarlySessionIdCallback,
+) => Promise<ClaudeRunResult>;
+
+/**
+ * Debounce window for onProgress → cronRunReporter.recordProgress pushes
+ * within a single dispatch. A chatty run can fire onProgress on every
+ * assistant turn; without this, each turn would PATCH the admin API,
+ * hammering it on long multi-turn runs. A push that fires less than this
+ * many ms after the last one that actually went through is skipped — the
+ * next progress snapshot (or the final completeRun) carries the up-to-date
+ * totals instead. Mirrors loop-orchestrator.ts's PROGRESS_PUSH_DEBOUNCE_MS
+ * (CSU-3.1).
+ */
+const PROGRESS_PUSH_DEBOUNCE_MS = 5000;
+
+/**
+ * Format a cron-dispatched message with a `[Cron job: <jobId>]` tag and the
+ * current time. The tag is what a downstream time-tracking integration's
+ * session-merging logic keys off of to exclude unattended/automated cron
+ * work from a user's continuous work session view — so every runner() call
+ * originating from a cron dispatch (including shipwright-loop's per-phase
+ * dispatches) must be wrapped through this helper.
+ */
+export function formatCronMessage(jobId: string, prompt: string): string {
+  const now = new Date().toLocaleString("en-US", {
+    timeZone: "America/Los_Angeles",
+  });
+  return `[Cron job: ${jobId}] Current time: ${now}\n\n${prompt}`;
+}
+
+interface CronRequest {
+  jobId: string;
+  prompt: string;
+  channel?: string;
+  user?: string;
+  silent?: boolean;
+  preCheck?: string;
+}
+
+export interface CronHandlerDeps {
+  /**
+   * Slack client, or `undefined` on a chat-only agent (no Slack credentials).
+   * When absent, a job with a channel/user delivery target still runs and is
+   * recorded as completed — the delivery step is skipped, not failed.
+   */
+  slack: WebClient | undefined;
+  runner: ClaudeRunner;
+  formatter?: (text: string) => string;
+  /** Called after a successful post so the caller can track the thread. */
+  onPost?: (channel: string, ts: string) => void;
+  /** Called after a successful post when a sessionId is available. */
+  onSession?: (
+    channel: string,
+    ts: string,
+    sessionId: string,
+  ) => void | Promise<void>;
+  /** Optional speech synthesis — if absent, [speak:] markers are skipped. */
+  synthesizeSpeechFn?: SynthesizeSpeechFn;
+  voiceConfig?: VoiceConfig;
+  /** Workspace root — used to resolve relative preCheck scripts and root the run. */
+  workspace?: string;
+  /** Plugin cache dir — overridable for testing. */
+  pluginCacheDir?: string;
+  pluginManifestPath?: string;
+  alertsChannel?: string;
+  /** Reports cron run outcomes to the admin API (fire-and-forget). */
+  cronRunReporter?: CronRunReporter;
+  /** The agent's own ID — used to construct the reporter URL. */
+  agentId?: string;
+  /** Clock for deterministic time in tests. Defaults to SystemClock(). */
+  clock?: Clock;
+  /**
+   * Reads the always-loaded-context stamp (workspace CLAUDE.md + rules +
+   * plugin version fingerprint, see context-stamp.ts) once per run, so the
+   * run row can be grouped by what the model was given. Optional: when
+   * absent, runs are reported without a fingerprint.
+   */
+  contextStamp?: () => RunContextStamp | null;
+  /**
+   * The default GitHub org (pinned installation, else lowest installation id),
+   * or null when unknown. Cron jobs carry no repo, so this is the owner hint
+   * (SHIPWRIGHT_GH_OWNER) their spawn gets (GOR-1.3).
+   */
+  getDefaultOwner?: () => string | null;
+  /**
+   * Spawner used to run the preCheck script. Defaults to the real
+   * Bun.spawn — overridable in tests to inject a fake process instead of
+   * spawning ~15 real bun child processes per test run (CPS-1.1).
+   */
+  spawner?: typeof Bun.spawn;
+}
+
+export async function handleCronRequest(
+  req: CronRequest,
+  deps: CronHandlerDeps,
+): Promise<void> {
+  const { jobId, channel, user, silent } = req;
+  let { prompt } = req;
+  const {
+    slack,
+    runner,
+    formatter = markdownToSlack,
+    onPost,
+    onSession,
+    synthesizeSpeechFn,
+    voiceConfig,
+    workspace,
+    pluginCacheDir,
+    pluginManifestPath = join(
+      homedir(),
+      ".claude",
+      "plugins",
+      "installed_plugins.json",
+    ),
+    cronRunReporter,
+    agentId: _agentId,
+    clock = SystemClock(),
+    contextStamp,
+    getDefaultOwner,
+    spawner = Bun.spawn,
+  } = deps;
+
+  const startedAt = clock.now();
+
+  if (!prompt) {
+    throw new ValidationError("missing required field: prompt");
+  }
+  if (!silent && !channel && !user) {
+    throw new ValidationError(
+      "missing delivery target: provide channel or user (or set silent=true)",
+    );
+  }
+
+  // CREATE run at start (before preCheck)
+  const runId = cronRunReporter
+    ? await cronRunReporter.createRun(jobId, startedAt)
+    : null;
+
+  if (req.preCheck) {
+    const isRelative =
+      req.preCheck.startsWith("./") || req.preCheck.startsWith("../");
+    const isFilePath = isRelative || req.preCheck.startsWith("/");
+
+    let scriptPath: string | undefined;
+
+    if (isFilePath) {
+      if (isRelative && workspace === undefined) {
+        console.warn(
+          `[agent:cron] preCheck is a relative path but no workspace is set — skipping job "${jobId}"`,
+        );
+        await cronRunReporter?.skipRun(
+          jobId,
+          runId,
+          clock.now(),
+          "preCheck:not-found",
+        );
+        return;
+      }
+      const candidate = isRelative
+        ? resolve(workspace as string, req.preCheck)
+        : req.preCheck;
+      if (existsSync(candidate)) scriptPath = candidate;
+    } else {
+      const [plugin, script] = req.preCheck.split(":");
+
+      if (pluginCacheDir) {
+        const candidate = join(pluginCacheDir, plugin, "scripts", script);
+        if (existsSync(candidate)) scriptPath = candidate;
+      } else {
+        try {
+          const manifest = JSON.parse(
+            readFileSync(pluginManifestPath, "utf-8"),
+          ) as {
+            version: number;
+            plugins: Record<string, Array<{ installPath?: string }>>;
+          };
+          const entry = Object.entries(manifest.plugins).find(([k]) =>
+            k.startsWith(`${plugin}@`),
+          );
+          const installPath = entry?.[1]?.[0]?.installPath;
+          if (installPath) {
+            const candidate = join(installPath, "scripts", script);
+            if (existsSync(candidate)) scriptPath = candidate;
+          }
+        } catch (err) {
+          console.warn(
+            `[agent:cron] failed to read installed_plugins.json: ${String(err)}`,
+          );
+        }
+      }
+    }
+
+    if (!scriptPath) {
+      console.warn(
+        `[agent:cron] preCheck script not found for "${req.preCheck}" — skipping job "${jobId}"`,
+      );
+      await cronRunReporter?.skipRun(
+        jobId,
+        runId,
+        clock.now(),
+        "preCheck:not-found",
+      );
+      return;
+    }
+
+    // Run the preCheck from the workspace, not the agent's cwd (/app). Plugin
+    // preChecks resolve state relative to process.cwd() — e.g. check-dev-task.ts
+    // queries the hosted task-store HTTP API (via check-helpers.ts) using
+    // SHIPWRIGHT_TASK_STORE_URL/TOKEN, and other prechecks read workspace-relative
+    // files like `state/agent-policy.md`. Without this the cwd roots at /app and
+    // workspace-relative reads fail. Mirrors the claude run, which is already
+    // rooted at the workspace.
+    const checkProc = spawner(["bun", scriptPath], {
+      ...(workspace ? { cwd: workspace } : {}),
+      // env: process.env is required — Bun.spawn otherwise snapshots env at Bun
+      // startup and misses runtime mutations from config-sync (index.ts does
+      // applyEnvToProcess(bundle.env) every 60s). Without this, a
+      // preCheck reads boot-time credentials — e.g. a rotated
+      // SHIPWRIGHT_TASK_STORE_TOKEN — and fails (401) until the pod restarts.
+      // Mirrors setup.ts defaultExec, which documents the same gotcha.
+      env: process.env,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [checkOutput, checkStderr] = await Promise.all([
+      new Response(checkProc.stdout).text(),
+      new Response(checkProc.stderr).text(),
+    ]);
+    const checkExitCode = await checkProc.exited;
+    const output = checkOutput.trim();
+
+    if (checkExitCode >= 2) {
+      const detail = checkStderr.trim();
+      console.error(
+        `[agent:cron] preCheck for job "${jobId}" crashed (exit ${checkExitCode})${detail ? `: ${detail}` : ""} — session suppressed`,
+      );
+      if (deps.alertsChannel && deps.slack) {
+        try {
+          await deps.slack.chat.postMessage({
+            channel: deps.alertsChannel,
+            text: `[cron] preCheck for \`${jobId}\` crashed (exit ${checkExitCode}) — session suppressed${detail ? `\n\`\`\`\n${detail}\n\`\`\`` : ""}`,
+          });
+        } catch (alertErr) {
+          console.error(
+            "[agent:cron] failed to post preCheck alert:",
+            alertErr,
+          );
+        }
+      }
+      await cronRunReporter?.skipRun(
+        jobId,
+        runId,
+        clock.now(),
+        "preCheck:crash",
+        { error: detail || undefined },
+      );
+      return;
+    }
+
+    if (checkExitCode !== 0 || !output) {
+      console.log(
+        `[agent:cron] preCheck returned no work for job "${jobId}" — skipping tick`,
+      );
+      await cronRunReporter?.skipRun(
+        jobId,
+        runId,
+        clock.now(),
+        "preCheck:no-output",
+      );
+      return;
+    }
+
+    prompt = output;
+  }
+
+  const message = formatCronMessage(jobId, prompt);
+
+  console.log(`[agent:cron] running job "${jobId}"`);
+
+  // Resolve SLACK_CHANNEL_ID for the runner's extraEnv (STC-1.3), so
+  // slack-say inside the run knows which channel to address. A channel job
+  // uses its channel directly. A DM job resolves (and caches) the DM channel
+  // here, before the run, so the post-run delivery step below can reuse the
+  // same id instead of opening the DM twice. Resolution is best-effort — a
+  // missing channel id or a conversations.open rejection is logged and
+  // swallowed, never allowed to block the run. A silent job (job-level
+  // `silent`, not the [silent] response marker, which isn't known yet) never
+  // delivers, so DM resolution is skipped for it entirely. SLACK_THREAD_TS is
+  // never set here — cron runs have no parent thread to reply into.
+  let extraEnv: Record<string, string> | undefined;
+  let resolvedDmChannel: string | undefined;
+  if (channel) {
+    extraEnv = { SLACK_CHANNEL_ID: channel };
+  } else if (user && slack && !silent) {
+    try {
+      const dmResult = await slack.conversations.open({ users: user });
+      const dmChannel = dmResult.channel?.id;
+      if (dmChannel) {
+        resolvedDmChannel = dmChannel;
+        extraEnv = { SLACK_CHANNEL_ID: dmChannel };
+      } else {
+        console.warn(
+          `[agent:cron] job "${jobId}" could not resolve a DM channel id for user ${user} — running without SLACK_CHANNEL_ID`,
+        );
+      }
+    } catch (err) {
+      console.warn(
+        `[agent:cron] job "${jobId}" failed to open DM for user ${user}: ${String(err)} — running without SLACK_CHANNEL_ID`,
+      );
+    }
+  }
+
+  // GOR-1.3: a cron has no repo, so its spawn carries the default org as the
+  // gh owner hint (merged with SLACK_CHANNEL_ID). Warns once if none resolves.
+  extraEnv = buildSpawnEnv({
+    kind: "cron",
+    id: jobId,
+    owner: getDefaultOwner?.(),
+    extraEnv,
+  });
+
+  // ── Runner scope ─────────────────────────────────────────────────────────
+  // Errors here record a genuine failure and re-throw so the caller sees them.
+  let usage: TokenUsage | undefined;
+  let modelUsage: ModelUsage | undefined;
+  let result: string;
+  let sessionId: string | undefined;
+  let telemetry: RunTelemetry | undefined;
+  // Stamp the always-loaded context once, before the run, so a concurrent
+  // workspace edit mid-run can't make the fingerprint disagree with what
+  // this run's first turn actually loaded. Fail-soft: a reader error just
+  // leaves the run unstamped.
+  let stamp: RunContextStamp | undefined;
+  try {
+    stamp = contextStamp?.() ?? undefined;
+  } catch (err) {
+    console.warn(
+      `[agent:cron] job "${jobId}" context stamp failed: ${String(err)} — running unstamped`,
+    );
+  }
+  const extras = (t: RunTelemetry | undefined): TokenPayloadExtras => ({
+    telemetry: t,
+    contextStamp: stamp,
+  });
+
+  // Progress push (CSU-3.2): fired as each new assistant turn completes so
+  // token totals survive an agent-process OOM/deploy-kill mid-run, not just
+  // a clean completion. Debounced against PROGRESS_PUSH_DEBOUNCE_MS (via the
+  // injected clock, not Date.now(), to stay deterministic under FixedClock)
+  // to avoid hammering the admin API on a chatty multi-turn run.
+  // recordProgress is fire-and-forget per its own doc comment — a rejection
+  // must not crash the run, so it's caught and swallowed. Mirrors
+  // loop-orchestrator.ts's onProgress wiring (CSU-3.1).
+  let lastProgressPushAt: number | undefined;
+  const onProgress: ProgressCallback = (progressModelUsage) => {
+    const { modelBreakdown } = buildTokenPayload(undefined, progressModelUsage);
+    if (!modelBreakdown || modelBreakdown.length === 0) return;
+
+    const now = clock.now();
+    const nowMs = now.getTime();
+    if (
+      lastProgressPushAt !== undefined &&
+      nowMs - lastProgressPushAt < PROGRESS_PUSH_DEBOUNCE_MS
+    ) {
+      return;
+    }
+    lastProgressPushAt = nowMs;
+
+    cronRunReporter
+      ?.recordProgress(jobId, runId, modelBreakdown, now)
+      .catch((err) => {
+        console.warn(
+          `[agent:cron] recordProgress failed for run ${runId}: ${String(err)} — swallowing`,
+        );
+      });
+  };
+
+  // Early session-id push (CES-1.1): fired as soon as the CLI's leading
+  // system/init stream-json line arrives, well before the run finishes — so
+  // the cron-run log has a sessionId for manual inspection even if the run
+  // never reaches a terminal state (crash, kill, timeout). Fire-and-forget
+  // per recordSessionId's own doc comment — a rejection must not crash the
+  // run, so it's caught and swallowed. Mirrors loop-orchestrator.ts's
+  // onEarlySessionId wiring and this file's own onProgress/recordProgress
+  // pattern just above.
+  const onEarlySessionId: EarlySessionIdCallback = (sid) => {
+    cronRunReporter?.recordSessionId(jobId, runId, sid).catch((err) => {
+      console.warn(
+        `[agent:cron] recordSessionId failed for run ${runId}: ${String(err)} — swallowing`,
+      );
+    });
+  };
+
+  try {
+    const runResult = await runner(
+      message,
+      onProgress,
+      extraEnv,
+      onEarlySessionId,
+    );
+    if (runResult.streamIncomplete) {
+      // Clean process exit, but the stream never emitted a terminal `result`
+      // event — treat this the same as a genuine failure rather than letting
+      // an empty response masquerade as a completed run (see CSU-1.1 review).
+      throw new ClaudeRunError(
+        "claude stream ended without a terminal result event",
+        undefined,
+        "stream incomplete — no terminal result event",
+        runResult.sessionId,
+        runResult.modelUsage,
+        runResult.telemetry,
+      );
+    }
+    usage = runResult.usage;
+    modelUsage = runResult.modelUsage;
+    result = runResult.result;
+    sessionId = runResult.sessionId;
+    telemetry = runResult.telemetry;
+  } catch (err) {
+    // Partial-usage-on-failure (CSU-3.2): a ClaudeTimeoutError carries
+    // whatever per-model usage was accumulated before the process was
+    // killed — attach it as modelBreakdown so a timed-out run's tokens
+    // aren't dropped entirely (the direct fix for "unknown model" on
+    // timed-out cron runs). Scoped narrowly to ClaudeTimeoutError's
+    // `partialModelUsage` field, not ClaudeRunError's differently-named
+    // `modelUsage` field — any other error (including ClaudeRunError) falls
+    // back to { error } only, unchanged. Mirrors loop-orchestrator.ts's
+    // catch-path handling (CSU-3.1).
+    // Telemetry (first-turn baseline, counts, attribution) rides along on
+    // both error types' `partialTelemetry` — it's additive and never changes
+    // which error paths forward token totals.
+    const partialTelemetry =
+      err instanceof ClaudeTimeoutError || err instanceof ClaudeRunError
+        ? err.partialTelemetry
+        : undefined;
+    const tokenPayload =
+      err instanceof ClaudeTimeoutError
+        ? buildTokenPayload(
+            undefined,
+            err.partialModelUsage,
+            extras(partialTelemetry),
+          )
+        : partialTelemetry !== undefined
+          ? buildTokenPayload(undefined, undefined, extras(partialTelemetry))
+          : undefined;
+
+    // sessionId (CSI-2.2): only ClaudeRunError/ClaudeTimeoutError (CSI-1.1)
+    // carry a sessionId field — a timed-out or failed run may still have
+    // captured one off the leading system/init stream-json line before the
+    // failure. Any other error type has no such field, so this is undefined.
+    const failureSessionId =
+      err instanceof ClaudeRunError || err instanceof ClaudeTimeoutError
+        ? err.sessionId
+        : undefined;
+
+    await cronRunReporter?.completeRun(jobId, runId, clock.now(), "failed", {
+      error: err instanceof Error ? err.message : String(err),
+      ...tokenPayload,
+      sessionId: failureSessionId,
+    });
+    markCronRunFailureReported(err);
+    throw err;
+  }
+
+  // ── Post-run scope ───────────────────────────────────────────────────────
+  // Slack delivery errors must NOT corrupt the run record with outcome='failed'
+  // when Claude completed successfully — they are logged and re-thrown, but the
+  // run is already recorded as 'completed' (with full token/cost data) before
+  // any Slack call is attempted.
+  const { cleaned, markers } = parseMarkers(result);
+  const isSilentMarker = markers.some((m) => m.type === "silent");
+
+  if (silent) {
+    console.log(`[agent:cron] job "${jobId}" completed (silent — no post)`);
+    await cronRunReporter?.completeRun(jobId, runId, clock.now(), "completed", {
+      ...buildTokenPayload(usage, modelUsage, extras(telemetry)),
+      sessionId,
+    });
+    return;
+  }
+  const isDmOnly = !!user && !channel;
+  if (isSilentMarker && !isDmOnly) {
+    // [silent] marker suppresses channel posts (and channel-wins-over-user posts)
+    // DMs always get a reply — [silent] is ignored when routing to a DM
+    console.log(`[agent:cron] job "${jobId}" completed (silent — no post)`);
+    await cronRunReporter?.completeRun(jobId, runId, clock.now(), "completed", {
+      ...buildTokenPayload(usage, modelUsage, extras(telemetry)),
+      sessionId,
+    });
+    return;
+  }
+
+  // Chat-only agent: the job produced output but there is no Slack client to
+  // deliver it with. Record the run as completed — the work happened — and skip
+  // delivery rather than throwing invalid_auth on the first postMessage.
+  if (!slack) {
+    console.warn(
+      `[agent:cron] job "${jobId}" completed but Slack is not configured — delivery skipped (set SLACK_BOT_TOKEN + SLACK_APP_TOKEN, or mark the job silent)`,
+    );
+    await cronRunReporter?.completeRun(jobId, runId, clock.now(), "completed", {
+      ...buildTokenPayload(usage, modelUsage, extras(telemetry)),
+      sessionId,
+    });
+    return;
+  }
+
+  const formatted = formatter(cleaned);
+  // Slack rejects chat.postMessage with `no_text` on blank text (e.g. output
+  // that was only [react:]/[upload:] markers). Skip the text post but still
+  // dispatch markers that don't need a posted message.
+  const hasText = formatted.trim() !== "";
+  if (!hasText) {
+    console.warn(
+      `[agent:cron] job "${jobId}" produced empty text after marker stripping — skipping text post`,
+    );
+  }
+
+  if (channel) {
+    if (user) {
+      console.warn(
+        `[agent:cron] job "${jobId}" has both channel and user — posting to channel`,
+      );
+    }
+
+    // Record completion before Slack delivery — a Slack error must not
+    // overwrite a successful run with outcome='failed'.
+    await cronRunReporter?.completeRun(jobId, runId, clock.now(), "completed", {
+      ...buildTokenPayload(usage, modelUsage, extras(telemetry)),
+      sessionId,
+    });
+
+    // The run is already recorded as "completed" above — any error from here
+    // on (postMessage, dispatchMarkers) must be tagged before rethrowing so
+    // index.ts's outer catch doesn't create a duplicate "failed" row for a
+    // tick that already completed successfully.
+    try {
+      const postResult = hasText
+        ? await slack.chat.postMessage({ channel, text: formatted })
+        : undefined;
+      if (postResult) {
+        console.log(`[agent:cron] job "${jobId}" posted to channel ${channel}`);
+      }
+      if (postResult?.ts) {
+        onPost?.(channel, postResult.ts);
+        if (onSession && sessionId)
+          await onSession(channel, postResult.ts, sessionId);
+      } else if (postResult) {
+        console.warn(
+          `[agent:cron] job "${jobId}" postMessage returned no ts — react markers will be skipped`,
+        );
+      }
+      await dispatchMarkers(markers, {
+        client: slack,
+        channel,
+        postedTs: postResult?.ts,
+        synthesizeSpeechFn,
+        voiceConfig,
+        postedText: formatted,
+      });
+    } catch (err) {
+      markCronRunFailureReported(err);
+      throw err;
+    }
+  } else if (user) {
+    // Record completion before any Slack calls — conversations.open can also
+    // fail (network error or null channel), and we must not leave the
+    // AgentCronRun row permanently open if it does.
+    await cronRunReporter?.completeRun(jobId, runId, clock.now(), "completed", {
+      ...buildTokenPayload(usage, modelUsage, extras(telemetry)),
+      sessionId,
+    });
+
+    // The run is already recorded as "completed" above — any error from here
+    // on (conversations.open, postMessage, dispatchMarkers) must be tagged
+    // before rethrowing so index.ts's outer catch doesn't create a duplicate
+    // "failed" row for a tick that already completed successfully.
+    try {
+      // Reuse the DM channel resolved before the run (STC-1.3) so the DM is
+      // opened at most once per dispatch. If pre-resolution didn't happen or
+      // failed (silent job, no slack client, or conversations.open error),
+      // fall back to opening it here, same as before.
+      const dmChannel =
+        resolvedDmChannel ??
+        (await slack.conversations.open({ users: user })).channel?.id;
+      if (!dmChannel) {
+        throw new Error(`[agent:cron] could not open DM for user ${user}`);
+      }
+
+      const dmPostResult = hasText
+        ? await slack.chat.postMessage({ channel: dmChannel, text: formatted })
+        : undefined;
+      if (dmPostResult) {
+        console.log(`[agent:cron] job "${jobId}" posted DM to user ${user}`);
+      }
+      if (dmPostResult?.ts) {
+        onPost?.(dmChannel, dmPostResult.ts);
+        if (onSession && sessionId)
+          await onSession(dmChannel, dmPostResult.ts, sessionId);
+      } else if (dmPostResult) {
+        console.warn(
+          `[agent:cron] job "${jobId}" DM postMessage returned no ts — react markers will be skipped`,
+        );
+      }
+      await dispatchMarkers(markers, {
+        client: slack,
+        channel: dmChannel,
+        postedTs: dmPostResult?.ts,
+        synthesizeSpeechFn,
+        voiceConfig,
+        postedText: formatted,
+      });
+    } catch (err) {
+      markCronRunFailureReported(err);
+      throw err;
+    }
+  }
+}
+
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ValidationError";
+  }
+}