fullstackgtm 0.44.0 → 0.46.0

package/src/runReport.ts

@@ -8,6 +8,7 @@
  * pure added value for users who granted it.
  */
 import { getCredential } from "./credentials.ts";
+import type { ProgressListener, ProgressSnapshot } from "./progress.ts";
 
 type RunEvent = { ts: number; type: string; detail?: string };
 
@@ -61,6 +62,16 @@ export function reportEvent(type: string, detail?: string): void {
   events.push({ ts: Date.now(), type, detail });
 }
 
+// FNV-1a — the stable-id hash used across the package (see backfill.ts).
+function fnv1a(value: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < value.length; i += 1) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
 // Setup/inspection verbs aren't interesting as "runs" — skip the noise.
 const SKIP_COMMANDS = new Set([
   "login",
@@ -74,6 +85,144 @@ const SKIP_COMMANDS = new Set([
   "-v",
 ]);
 
+/** The stable per-invocation identity flushRunReport and heartbeats share. */
+function runIdentity(
+  args: string[],
+  startedAt: number,
+): { command: string; clientRunId: string } | null {
+  const command = args[0];
+  if (!command || SKIP_COMMANDS.has(command)) return null;
+  const sub = args[1] && !args[1].startsWith("-") ? ` ${args[1]}` : "";
+  const full = `${command}${sub}`;
+  return { command: full, clientRunId: `run_${fnv1a(`${full}:${startedAt}:${process.pid}`)}` };
+}
+
+// ── Live progress streaming ─────────────────────────────────────────────────
+// While a long command runs, a paired CLI streams heartbeats to the hosted
+// app: POST /api/cli/run with the SAME clientRunId the final flushRunReport
+// will use, status "in_progress", and the progress emitter's snapshot. The
+// server upserts by clientRunId, so the terminal flush simply wins. Same
+// invariants as flushRunReport: opt-in (paired only), fire-and-forget,
+// time-capped, never affects the command's outcome or output.
+
+const HEARTBEAT_INTERVAL_MS = 5000;
+/** No heartbeat before the run is ~this old — fast commands never stream. */
+const HEARTBEAT_MIN_RUN_MS = 5000;
+const HEARTBEAT_TIMEOUT_MS = 2000;
+
+type RunContext = { command: string; clientRunId: string; startedAt: number };
+
+let runContext: RunContext | null = null;
+let lastHeartbeatAt = 0;
+// Broker credential resolved once per run (undefined = not looked up yet;
+// null = looked up, not paired).
+let heartbeatBroker: { baseUrl: string; accessToken: string } | null | undefined;
+let inflightHeartbeat: AbortController | null = null;
+
+/**
+ * Arm heartbeat streaming for this invocation. Call once from the entry point
+ * (alongside capturing `startedAt`); without it, progress listeners from
+ * `progressReporter()` are inert. Safe to call for any command — skip-listed
+ * commands simply never stream.
+ */
+export function beginRunReport(args: string[], startedAt: number): void {
+  lastHeartbeatAt = 0;
+  heartbeatBroker = undefined;
+  inflightHeartbeat = null;
+  const identity = runIdentity(args, startedAt);
+  runContext = identity ? { ...identity, startedAt } : null;
+}
+
+/**
+ * A ProgressListener that streams the run's progress snapshot to the paired
+ * hosted app. Verbs compose it with their local renderer:
+ *
+ *   createProgressEmitter(composeListeners(renderer.listener, progressReporter()))
+ *
+ * Throttled to one POST per ~5s, first no earlier than ~5s into the run,
+ * 2s-capped and fire-and-forget. Privacy: stage names and counts only — notes
+ * must stay generic ("batch 4/12"); CRM field values never leave the machine.
+ */
+export function progressReporter(
+  overrides: {
+    now?: () => number;
+    intervalMs?: number;
+    minRunMs?: number;
+    fetchImpl?: typeof fetch;
+  } = {},
+): ProgressListener {
+  const now = overrides.now ?? Date.now;
+  const intervalMs = overrides.intervalMs ?? HEARTBEAT_INTERVAL_MS;
+  const minRunMs = overrides.minRunMs ?? HEARTBEAT_MIN_RUN_MS;
+  const fetchImpl = overrides.fetchImpl ?? fetch;
+  return (_event, snapshot) => {
+    try {
+      if (!runContext) return;
+      const at = now();
+      if (at - runContext.startedAt < minRunMs) return;
+      if (at - lastHeartbeatAt < intervalMs) return;
+      if (heartbeatBroker === undefined) {
+        const broker = getCredential("broker");
+        heartbeatBroker =
+          broker?.baseUrl && broker.accessToken
+            ? { baseUrl: broker.baseUrl.replace(/\/+$/, ""), accessToken: broker.accessToken }
+            : null; // opt-in: only when paired
+      }
+      if (!heartbeatBroker) return;
+      lastHeartbeatAt = at;
+      sendHeartbeat(fetchImpl, heartbeatBroker, runContext, snapshot, at);
+    } catch {
+      // Observability is best-effort; never affect the command.
+    }
+  };
+}
+
+function sendHeartbeat(
+  fetchImpl: typeof fetch,
+  broker: { baseUrl: string; accessToken: string },
+  context: RunContext,
+  snapshot: ProgressSnapshot,
+  at: number,
+): void {
+  // One heartbeat in flight at a time: a stalled POST is superseded, and the
+  // terminal flush aborts any straggler so it can never delay process exit.
+  inflightHeartbeat?.abort();
+  const controller = new AbortController();
+  inflightHeartbeat = controller;
+  const timer = setTimeout(() => controller.abort(), HEARTBEAT_TIMEOUT_MS);
+  (timer as { unref?: () => void }).unref?.();
+  void fetchImpl(`${broker.baseUrl}/api/cli/run`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${broker.accessToken}`, "Content-Type": "application/json" },
+    body: JSON.stringify({
+      command: context.command,
+      clientRunId: context.clientRunId,
+      status: "in_progress",
+      startedAt: context.startedAt,
+      finishedAt: at,
+      durationMs: at - context.startedAt,
+      progress: {
+        // Stage names + counts only — never CRM field values.
+        stage: snapshot.stage,
+        stageIndex: snapshot.stageIndex,
+        stageCount: snapshot.stageCount,
+        itemsDone: snapshot.itemsDone,
+        itemsTotal: snapshot.itemsTotal,
+        note: snapshot.note,
+        heartbeatAt: at,
+      },
+    }),
+    signal: controller.signal,
+  })
+    .catch(() => {
+      // fire-and-forget
+    })
+    .finally(() => {
+      clearTimeout(timer);
+      if (inflightHeartbeat === controller) inflightHeartbeat = null;
+    });
+}
+
 /**
  * Send the run record if the CLI is paired. Best-effort: a 4s-capped POST that
  * swallows every error. Call once per process from the entry point.
@@ -84,19 +233,25 @@ export async function flushRunReport(
   startedAt: number,
   error?: string,
 ): Promise<void> {
-  const command = args[0];
-  if (!command || SKIP_COMMANDS.has(command)) return;
+  // The terminal upsert supersedes any streaming heartbeat still in flight.
+  inflightHeartbeat?.abort();
+  inflightHeartbeat = null;
+  // Stable per-invocation identity: the server dedupes on clientRunId, so a
+  // retried report, an "in_progress" heartbeat, or a later `backfill runs`
+  // replay of local history never duplicates.
+  const identity = runIdentity(args, startedAt);
+  if (!identity) return;
   const broker = getCredential("broker");
   if (!broker?.baseUrl || !broker.accessToken) return; // opt-in: only when paired
 
-  const sub = args[1] && !args[1].startsWith("-") ? ` ${args[1]}` : "";
   const finishedAt = Date.now();
   try {
     await fetch(`${broker.baseUrl.replace(/\/+$/, "")}/api/cli/run`, {
       method: "POST",
       headers: { Authorization: `Bearer ${broker.accessToken}`, "Content-Type": "application/json" },
       body: JSON.stringify({
-        command: `${command}${sub}`,
+        command: identity.command,
+        clientRunId: identity.clientRunId,
         status,
         startedAt,
         finishedAt,

package/src/schedule.ts

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
-import { mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { credentialsDir, ensureSecureHomeDir, writeSecureFile } from "./credentials.ts";
 
@@ -49,9 +50,11 @@ export type ScheduleRunRecord = {
    * recorded for visibility but nothing ran. Reasons: "plan_not_approved"
    * (scheduled apply against a plan that is not approved — there is no flag
    * that relaxes this), "not_schedulable" (the stored argv no longer passes
-   * the allowlist, e.g. after a hand edit of schedules.json).
+   * the allowlist, e.g. after a hand edit of schedules.json),
+   * "duplicate_firing" (a cron-triggered run already recorded in this minute
+   * — launchd can double-trigger the Vixie dom+dow OR corner).
    */
-  noopReason?: "plan_not_approved" | "not_schedulable";
+  noopReason?: "plan_not_approved" | "not_schedulable" | "duplicate_firing";
 };
 
 // Mirrors stableHash in rules.ts (FNV-1a); duplicated to keep schedule.ts
@@ -729,3 +732,307 @@ export function replaceManagedBlock(existing: string, profile: string, block: st
   if (merged.length === 0) return "";
   return `${merged.join("\n")}\n`;
 }
+
+// ---------------------------------------------------------------------------
+// Local provider: launchd LaunchAgents (macOS)
+//
+// On macOS `crontab -` writes to the TCC-protected /var/at/tabs, which
+// requires granting Full Disk Access to the *terminal app* — a permission no
+// program can request and a huge over-grant for one timer line. Per-user
+// LaunchAgents need no permission at all: one plist per enabled entry in
+// ~/Library/LaunchAgents, loaded with `launchctl bootstrap gui/<uid>`. Bonus
+// over cron: launchd coalesces firings missed while asleep into one run on
+// wake, where cron silently skips. Same audit story as the crontab block —
+// every plist's ProgramArguments is `... schedule run <id>` and nothing else,
+// and install replaces the com.fullstackgtm.<profile>.* fleet wholesale.
+
+/**
+ * One launchd StartCalendarInterval dict: every present key must match (AND),
+ * a missing key is a wildcard, and an array of dicts fires when ANY dict
+ * matches. Weekday 0 is Sunday, as in cron.
+ */
+export type LaunchdCalendarInterval = {
+  Minute?: number;
+  Hour?: number;
+  Day?: number;
+  Weekday?: number;
+  Month?: number;
+};
+
+/**
+ * Compile a cron expression to StartCalendarInterval dicts. Full-range fields
+ * (`*`, but also spellings like `0-59`) are omitted (launchd wildcard); the
+ * rest cross-product, capped so a dense expression cannot render a megabyte
+ * plist. Vixie day semantics: when day-of-month AND day-of-week are both
+ * restricted, either may match — launchd ANDs keys within one dict, so that
+ * becomes the union of a Day dict set and a Weekday dict set. A date matching
+ * both sets makes launchd trigger twice in the same minute; the run entry
+ * point drops the second via isDuplicateCronFiring.
+ */
+export function cronToCalendarIntervals(cron: CronExpression, cap = 512): LaunchdCalendarInterval[] {
+  const full = (values: number[], min: number, max: number) => values.length === max - min + 1;
+  const minutes: Array<number | undefined> = full(cron.minute, 0, 59) ? [undefined] : cron.minute;
+  const hours: Array<number | undefined> = full(cron.hour, 0, 23) ? [undefined] : cron.hour;
+  const months: Array<number | undefined> = full(cron.month, 1, 12) ? [undefined] : cron.month;
+  const domRestricted = cron.dayOfMonthRestricted && !full(cron.dayOfMonth, 1, 31);
+  const dowRestricted = cron.dayOfWeekRestricted && !full(cron.dayOfWeek, 0, 6);
+  const daySlots: Array<Pick<LaunchdCalendarInterval, "Day" | "Weekday">> = [];
+  if (domRestricted) for (const day of cron.dayOfMonth) daySlots.push({ Day: day });
+  if (dowRestricted) for (const weekday of cron.dayOfWeek) daySlots.push({ Weekday: weekday });
+  if (daySlots.length === 0) daySlots.push({});
+  const count = minutes.length * hours.length * daySlots.length * months.length;
+  if (count > cap) {
+    throw new Error(
+      `Cron expression "${cron.source}" expands to ${count} launchd calendar intervals (cap ${cap}). ` +
+        "Simplify the expression or split it into separate schedules.",
+    );
+  }
+  const intervals: LaunchdCalendarInterval[] = [];
+  for (const month of months) {
+    for (const daySlot of daySlots) {
+      for (const hour of hours) {
+        for (const minute of minutes) {
+          const dict: LaunchdCalendarInterval = {};
+          if (minute !== undefined) dict.Minute = minute;
+          if (hour !== undefined) dict.Hour = hour;
+          if (daySlot.Day !== undefined) dict.Day = daySlot.Day;
+          if (daySlot.Weekday !== undefined) dict.Weekday = daySlot.Weekday;
+          if (month !== undefined) dict.Month = month;
+          intervals.push(dict);
+        }
+      }
+    }
+  }
+  return intervals;
+}
+
+/**
+ * True when a cron-triggered run was already recorded in `firedAt`'s minute.
+ * The `schedule run` entry point checks this for trigger:cron so a launchd
+ * double-trigger (dom+dow OR corner above) records a duplicate_firing no-op
+ * instead of running the command twice. Manual runs are never deduplicated.
+ */
+export function isDuplicateCronFiring(runs: ScheduleRunRecord[], firedAt: string): boolean {
+  const minute = new Date(firedAt);
+  minute.setSeconds(0, 0);
+  return runs.some((run) => {
+    if (run.trigger !== "cron") return false;
+    const fired = new Date(run.firedAt);
+    fired.setSeconds(0, 0);
+    return fired.getTime() === minute.getTime();
+  });
+}
+
+/** Reverse-DNS namespace for one profile's agents; install/uninstall own this prefix wholesale. */
+export function launchdAgentPrefix(profile: string): string {
+  if (!/^[A-Za-z0-9._-]+$/.test(profile)) {
+    throw new Error(
+      `Cannot build a launchd label from profile "${profile}" — profile names in LaunchAgent labels ` +
+        "must be alphanumeric with dot/dash/underscore.",
+    );
+  }
+  return `com.fullstackgtm.${profile}.`;
+}
+
+export function launchdLabel(profile: string, scheduleEntryId: string): string {
+  if (!/^[A-Za-z0-9._-]+$/.test(scheduleEntryId)) {
+    throw new Error(`Cannot build a launchd label from schedule id "${scheduleEntryId}".`);
+  }
+  return `${launchdAgentPrefix(profile)}${scheduleEntryId}`;
+}
+
+function xmlEscape(value: string): string {
+  return value.replace(/[&<>"']/g, (char) => {
+    switch (char) {
+      case "&":
+        return "&amp;";
+      case "<":
+        return "&lt;";
+      case ">":
+        return "&gt;";
+      case '"':
+        return "&quot;";
+      default:
+        return "&apos;";
+    }
+  });
+}
+
+/**
+ * Render one LaunchAgent plist. ProgramArguments is an argv array — launchd
+ * execs it directly, no shell, so there is no quoting/injection surface at
+ * all (values are XML-escaped for the document, nothing more).
+ */
+export function renderLaunchdPlist(options: {
+  label: string;
+  programArguments: string[];
+  calendarIntervals: LaunchdCalendarInterval[];
+  environment?: Record<string, string>;
+  standardOutPath?: string;
+  standardErrorPath?: string;
+}): string {
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    "<dict>",
+    "\t<key>Label</key>",
+    `\t<string>${xmlEscape(options.label)}</string>`,
+    "\t<key>ProgramArguments</key>",
+    "\t<array>",
+    ...options.programArguments.map((arg) => `\t\t<string>${xmlEscape(arg)}</string>`),
+    "\t</array>",
+    "\t<key>StartCalendarInterval</key>",
+    "\t<array>",
+  ];
+  const keyOrder = ["Minute", "Hour", "Day", "Weekday", "Month"] as const;
+  for (const interval of options.calendarIntervals) {
+    lines.push("\t\t<dict>");
+    for (const key of keyOrder) {
+      const value = interval[key];
+      if (value === undefined) continue;
+      lines.push(`\t\t\t<key>${key}</key>`, `\t\t\t<integer>${value}</integer>`);
+    }
+    lines.push("\t\t</dict>");
+  }
+  lines.push("\t</array>");
+  if (options.environment && Object.keys(options.environment).length > 0) {
+    lines.push("\t<key>EnvironmentVariables</key>", "\t<dict>");
+    for (const [name, value] of Object.entries(options.environment)) {
+      lines.push(`\t\t<key>${xmlEscape(name)}</key>`, `\t\t<string>${xmlEscape(value)}</string>`);
+    }
+    lines.push("\t</dict>");
+  }
+  if (options.standardOutPath) {
+    lines.push("\t<key>StandardOutPath</key>", `\t<string>${xmlEscape(options.standardOutPath)}</string>`);
+  }
+  if (options.standardErrorPath) {
+    lines.push("\t<key>StandardErrorPath</key>", `\t<string>${xmlEscape(options.standardErrorPath)}</string>`);
+  }
+  lines.push("</dict>", "</plist>");
+  return `${lines.join("\n")}\n`;
+}
+
+export type LaunchdIo = {
+  /** Plist file names currently in the agents directory. */
+  list(): string[];
+  write(fileName: string, content: string): void;
+  remove(fileName: string): void;
+  /** Load one agent plist into the user's gui domain; throws on failure. */
+  bootstrap(fileName: string): void;
+  /** Best-effort unload by label; a label that is not loaded is not an error. */
+  bootout(label: string): void;
+};
+
+/**
+ * The real ~/Library/LaunchAgents + launchctl. Everything above takes a
+ * LaunchdIo so tests inject fakes and never touch the user's agents.
+ */
+export function systemLaunchdIo(agentsDirOverride?: string): LaunchdIo {
+  const agentsDir = agentsDirOverride ?? join(homedir(), "Library", "LaunchAgents");
+  const domain = () => {
+    const uid = typeof process.getuid === "function" ? process.getuid() : null;
+    if (uid === null) throw new Error("launchd scheduling requires a POSIX user id (macOS only).");
+    return `gui/${uid}`;
+  };
+  const launchctl = (args: string[]) => {
+    const result = spawnSync("launchctl", args, { encoding: "utf8" });
+    if (result.error) throw new Error(`Cannot run \`launchctl\`: ${result.error.message}`);
+    return result;
+  };
+  return {
+    list() {
+      try {
+        return readdirSync(agentsDir).filter((name) => name.endsWith(".plist"));
+      } catch {
+        return [];
+      }
+    },
+    write(fileName, content) {
+      mkdirSync(agentsDir, { recursive: true });
+      // 0644 like every LaunchAgent: launchd refuses group/world-WRITABLE
+      // plists, and this file holds a dispatch line, not a secret.
+      writeFileSync(join(agentsDir, fileName), content, { mode: 0o644 });
+    },
+    remove(fileName) {
+      rmSync(join(agentsDir, fileName), { force: true });
+    },
+    bootstrap(fileName) {
+      const result = launchctl(["bootstrap", domain(), join(agentsDir, fileName)]);
+      if (result.status !== 0) {
+        throw new Error(
+          `\`launchctl bootstrap\` failed for ${fileName}: ${(result.stderr ?? "").trim() || `exit ${result.status}`}`,
+        );
+      }
+    },
+    bootout(label) {
+      launchctl(["bootout", `${domain()}/${label}`]);
+    },
+  };
+}
+
+/**
+ * Materialize enabled entries as one LaunchAgent each, replacing the
+ * profile's com.fullstackgtm.<profile>.* fleet wholesale (stale agents are
+ * booted out and deleted; plists outside the prefix are never touched).
+ * `cliArgv` is the argv-array analog of the crontab invocation line.
+ */
+export function installLaunchdAgents(
+  profile: string,
+  entries: ScheduleEntry[],
+  cliArgv: string[],
+  io: LaunchdIo,
+  options: { environment?: Record<string, string>; logDir?: string } = {},
+): { installed: string[]; removed: string[] } {
+  for (const token of cliArgv) {
+    if (hasControlChar(token)) {
+      throw new Error(
+        "Refusing to render LaunchAgents: the resolved CLI invocation (node path or script path) " +
+          "contains a newline or control character.",
+      );
+    }
+  }
+  const removed = uninstallLaunchdAgents(profile, io);
+  const installed: string[] = [];
+  for (const entry of entries) {
+    assertRenderableEntry(profile, entry);
+    let intervals: LaunchdCalendarInterval[];
+    try {
+      intervals = cronToCalendarIntervals(parseCron(entry.cron));
+    } catch (error) {
+      throw new Error(
+        `Schedule ${entry.id} ("${entry.label}") cannot materialize as a LaunchAgent: ` +
+          `${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+    const label = launchdLabel(profile, entry.id);
+    const logPath = options.logDir ? join(options.logDir, `${label}.log`) : undefined;
+    const plist = renderLaunchdPlist({
+      label,
+      programArguments: [...cliArgv, "schedule", "run", entry.id, "--profile", profile, "--trigger", "cron"],
+      calendarIntervals: intervals,
+      environment: options.environment,
+      standardOutPath: logPath,
+      standardErrorPath: logPath,
+    });
+    const fileName = `${label}.plist`;
+    io.write(fileName, plist);
+    io.bootstrap(fileName);
+    installed.push(label);
+  }
+  return { installed, removed };
+}
+
+/** Boot out and delete every agent in the profile's prefix; returns the removed labels. */
+export function uninstallLaunchdAgents(profile: string, io: LaunchdIo): string[] {
+  const prefix = launchdAgentPrefix(profile);
+  const removed: string[] = [];
+  for (const name of io.list()) {
+    if (!name.startsWith(prefix)) continue;
+    const label = name.slice(0, -".plist".length);
+    io.bootout(label);
+    io.remove(name);
+    removed.push(label);
+  }
+  return removed;
+}

package/src/spoolFiles.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared reader for the spool container convention (docs/signal-spool-format.md):
+ * newline-delimited JSON — one object per line, append-only — with a JSON array
+ * accepted in a `.json` file for hand-staged convenience, and a DIRECTORY
+ * meaning "every `*.jsonl` / `*.json` file in it, name-sorted" so multiple
+ * receivers can each append their own file.
+ *
+ * The container is the convention; the row SCHEMA stays with each caller:
+ * `signals fetch --from` validates staged signal rows, `enrich ingest` stages
+ * enrichment rows, `market observe --from` validates observation-set envelopes.
+ * This module only parses objects out of files — it never interprets them.
+ *
+ * Extracted from the `file` signal-source connector (the Phase-2 webhook
+ * landing-zone reader), which now delegates here; error-message text is
+ * parameterized by `label` so existing connector errors are unchanged.
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** Spool files in a landing-zone directory: `*.jsonl` / `*.json`, name-sorted. */
+export function spoolFilesIn(dir: string): string[] {
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  return names
+    .filter((name) => name.endsWith(".jsonl") || name.endsWith(".json"))
+    .sort()
+    .map((name) => join(dir, name));
+}
+
+/** Parse a JSON-array spool file into rows. `label` prefixes error messages. */
+export function parseSpoolArray(raw: string, path: string, label: string): Record<string, unknown>[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${label} ${path}: not valid JSON (${error instanceof Error ? error.message : String(error)}).`);
+  }
+  if (!Array.isArray(parsed)) throw new Error(`${label} ${path}: expected a JSON array of staged signal rows.`);
+  return parsed.map((entry, index) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`${label} ${path}: row ${index} is not an object.`);
+    }
+    return entry as Record<string, unknown>;
+  });
+}
+
+/** Parse a JSONL spool file into rows. `label` prefixes error messages. */
+export function parseSpoolJsonl(raw: string, path: string, label: string): Record<string, unknown>[] {
+  const out: Record<string, unknown>[] = [];
+  const lines = raw.split("\n");
+  lines.forEach((line, index) => {
+    const t = line.trim();
+    if (!t) return;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(t);
+    } catch (error) {
+      throw new Error(`${label} ${path}: line ${index} is not valid JSON (${error instanceof Error ? error.message : String(error)}).`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error(`${label} ${path}: line ${index} is not a JSON object.`);
+    }
+    out.push(parsed as Record<string, unknown>);
+  });
+  return out;
+}
+
+/** Parse one spool file's text — JSON array if it opens with `[`, else JSONL. */
+export function parseSpoolText(raw: string, path: string, label: string): Record<string, unknown>[] {
+  const trimmed = raw.trim();
+  if (!trimmed) return [];
+  return trimmed.startsWith("[") ? parseSpoolArray(trimmed, path, label) : parseSpoolJsonl(trimmed, path, label);
+}
+
+/**
+ * Should an explicitly named intake path be read with spool semantics?
+ * True for a directory (a landing zone) or a `*.jsonl` file. Plain `.json` /
+ * `.csv` files keep each verb's original single-file handling, so existing
+ * invocations parse exactly as before.
+ */
+export function isSpoolPath(absPath: string): boolean {
+  try {
+    if (statSync(absPath).isDirectory()) return true;
+  } catch {
+    return false;
+  }
+  return absPath.endsWith(".jsonl");
+}
+
+/** A parsed spool row plus where it came from (for error labels). */
+export type SpoolRow = { file: string; index: number; row: Record<string, unknown> };
+
+/**
+ * Read an explicitly named spool path — a `.jsonl` file or a directory of
+ * `*.jsonl` / `*.json` files. Unlike the webhook `file` connector (where a
+ * missing spool is an empty source), the user named this path: a missing or
+ * unreadable file is an error, and a malformed row throws with file + line.
+ */
+export function readSpoolPath(absPath: string, label: string): SpoolRow[] {
+  const isDir = statSync(absPath).isDirectory();
+  const files = isDir ? spoolFilesIn(absPath) : [absPath];
+  if (isDir && files.length === 0) {
+    throw new Error(`${label} ${absPath}: directory contains no *.jsonl / *.json spool files.`);
+  }
+  const rows: SpoolRow[] = [];
+  for (const file of files) {
+    const raw = readFileSync(file, "utf8");
+    parseSpoolText(raw, file, label).forEach((row, index) => rows.push({ file, index, row }));
+  }
+  return rows;
+}