@ashlr/stack-core 0.3.6 → 0.3.9

package/src/__tests__/phantom-wire.test.ts

@@ -6430,3 +6430,55 @@ describe("webhookStubFor — arbitrary replacement with leading and trailing spa
     ).toBe(plain);
   });
 });
+
+describe("webhookStubFor — $1 in replacement text (original PR 1023)", () => {
+  const count = (s: string, needle: string) => s.split(needle).length - 1;
+
+  it("preserves $1 literally at every expansion site when it appears in a provider name", () => {
+    // $1 is a replacement directive for String.prototype.replace/replaceAll:
+    // it splices the first capture group. Template-literal interpolation does
+    // NOT interpret $1, so provider names carrying it must land in the stub
+    // as inert characters — exactly the bytes the caller passed in.
+    const name = "svc$1pay";
+    const stub = webhookStubFor(name);
+
+    // The name appears literally at the two case-preserving sites.
+    expect(stub).toContain(`webhook handler stub for ${name}.`);
+    expect(stub).toContain(`forge a ${name} webhook.`);
+
+    // At the handler name site the first character is upper-cased; $ is
+    // ASCII so toUpperCase is the identity, leaving $1 intact.
+    expect(stub).toContain("handleSvc$1payWebhook(req: Request)");
+
+    // At the reveal sites the entire name is upper-cased; $1 is
+    // toUpperCase-invariant, so it survives unchanged.
+    expect(count(stub, "phantom reveal SVC$1PAY_WEBHOOK_SECRET")).toBe(2);
+
+    // Dollar census: the name carries exactly one $ (in $1), and it appears
+    // at five sites in the stub. No $ was dropped by $$ collapse and none
+    // was minted by capture-group substitution.
+    expect(count(stub, "$")).toBe(5);
+    expect(count(stub, "$1")).toBe(5);
+
+    // No ${ opener leaked in — that would indicate the template was parsed
+    // as a replace pattern and $1 was interpreted as a capture reference.
+    expect(stub).not.toContain("${");
+  });
+
+  it("preserves a bare $1 provider name through the capitalize path", () => {
+    // $1 as the entire name exercises the capitalize() function: the first
+    // codepoint is $, which toUpperCase leaves as $. The remaining `1` is
+    // never touched. The name stays $1 at every expansion site.
+    const name = "$1";
+    const stub = webhookStubFor(name);
+
+    expect(stub).toContain(`webhook handler stub for ${name}.`);
+    expect(stub).toContain(`forge a ${name} webhook.`);
+    // capitalize("$1") = "$1" ($ is already uppercase, 1 stays 1)
+    expect(stub).toContain("handle$1Webhook(req: Request)");
+    expect(count(stub, "phantom reveal $1_WEBHOOK_SECRET")).toBe(2);
+
+    // Each $1 is a standalone $ at its own site — five total.
+    expect(count(stub, "$1")).toBe(5);
+  });
+});

package/src/ai/phantom-wire-repeated-unknown-placeholder.test.ts

@@ -1,7 +1,4 @@
 import { afterEach, beforeEach, describe, expect, it, setDefaultTimeout } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import { type Harness, setupFakePhantom } from "../__tests__/_harness.ts";
 import { webhookStubFor } from "./phantom-wire.ts";
 

package/src/fleet/capability-matrix.ts

@@ -0,0 +1,378 @@
+/**
+ * capability-matrix.ts — resource-agnostic job→resource matching for the fleet.
+ *
+ * Today dispatch lanes are provider-named (codex-cmp, claude, devin, codex-local,
+ * …) and the dispatcher picks a lane per queued job. The end-state binds fleet
+ * roles to whatever resource has the capability, quota and availability — this
+ * module is that matching layer. It is pure: callers assemble `FleetResource`
+ * rows from fleet state (slots.json, journals, capabilities.json, models.json)
+ * and this file answers "which resources can serve this requirement" without
+ * ever branching on a provider or lane name.
+ *
+ * Vocabulary:
+ * - Roles (closed set): the four fleet roles a job can require.
+ * - Capabilities (open, validated): orthogonal execution properties a job may
+ *   additionally require; FLEET_CAPABILITIES seeds the known tags.
+ * - Tiers: open, validated strings (the dispatcher uses frontier/work/mid/fast).
+ *
+ * Default capability profile: a resource with no capabilities.json declaration
+ * serves the `implementer` role on every tier — the same contract dispatchd
+ * applies today, where any lane can launch a coding job. A declaration can
+ * narrow roles (`roles: []` serves nothing) or widen them (planner, reviewer,
+ * release-verifier need explicit declaration).
+ */
+
+export const FLEET_ROLES = ["planner", "implementer", "reviewer", "release-verifier"] as const;
+export type FleetRole = (typeof FLEET_ROLES)[number];
+
+/** Seed capability tags; the vocabulary is open — any well-formed tag is valid. */
+export const FLEET_CAPABILITIES = [
+  /** Model inference runs on this host; loopback-only serving, no provider quota. */
+  "local-inference",
+  /** May run the publish path (fork-only pushes through publish.sh). */
+  "publish",
+  /** Can observe CI and repository state (gh or Locus-scoped reads). */
+  "ci-watch",
+] as const;
+
+const ROLE_SET: ReadonlySet<string> = new Set(FLEET_ROLES);
+const RESOURCE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const TAG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const TIER_RE = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+
+export const isFleetRole = (value: unknown): value is FleetRole =>
+  typeof value === "string" && ROLE_SET.has(value);
+
+export const isResourceId = (value: unknown): value is string =>
+  typeof value === "string" && RESOURCE_ID_RE.test(value);
+
+const isTag = (value: unknown): value is string => typeof value === "string" && TAG_RE.test(value);
+const isTier = (value: unknown): value is string =>
+  typeof value === "string" && TIER_RE.test(value);
+
+/** Well-formed capability tag (`local-inference`, `publish`, …); vocabulary is open. */
+export const isFleetCapability = isTag;
+/** Well-formed tier name (`frontier`, `work`, `mid`, `fast`, …); vocabulary is open. */
+export const isFleetTier = isTier;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** Roles a resource serves when nothing narrows them: implementer only. */
+export const DEFAULT_RESOURCE_ROLES: readonly FleetRole[] = ["implementer"];
+
+/** Per-resource quota/availability projection (slots.json + journal counts). */
+export interface FleetResourceQuota {
+  /** Operating launch bound (slots.json target); null when unknown. */
+  target: number | null;
+  ceiling: number | null;
+  hardCap: number | null;
+  /** Operator or autobackoff hold. */
+  held: boolean;
+  /** Observed running jobs for this resource; null when journals are unreadable. */
+  running: number | null;
+  /** Observed queued jobs for this resource; null when journals are unreadable. */
+  queued: number | null;
+  /** Provider quota reading from slots.json when present; informational only —
+   * the dispatcher does not launch-block on it, so neither does matching. */
+  quotaRemaining: number | null;
+}
+
+/** What capabilities.json may declare for one resource. */
+export interface CapabilityDeclaration {
+  /** null = default (implementer); [] = serves no role. */
+  roles: readonly FleetRole[] | null;
+  capabilities: readonly string[];
+  /** null = every tier; otherwise the tiers this resource serves. */
+  tiers: readonly string[] | null;
+}
+
+/** A schedulable resource after declarations and live quota are merged. */
+export interface FleetResource {
+  id: string;
+  /** True when capabilities.json declared this resource. */
+  declared: boolean;
+  /** Effective roles (declaration or the implementer default). */
+  roles: readonly FleetRole[];
+  capabilities: readonly string[];
+  tiers: readonly string[] | null;
+  /** null = no slot data; capacity checks then report headroom null, never block. */
+  quota: FleetResourceQuota | null;
+}
+
+/** What a job needs: a role, optional extra capability tags, optional tier. */
+export interface JobRequirement {
+  role: FleetRole;
+  capabilities: readonly string[];
+  tier: string | null;
+}
+
+export interface ResourceMatch {
+  id: string;
+  eligible: boolean;
+  /** Blocking reason codes; empty iff eligible. Codes: `missing-role:<role>`,
+   * `missing-capability:<tag>`, `tier-unsupported:<tier>`, `held`,
+   * `fleet-hold`, `fleet-at-capacity`, `at-capacity`. */
+  reasons: string[];
+  /** Spare launch slots (capacity bound minus running); null when either side
+   * is unknown — unknown quota never blocks on capacity, it reports null. */
+  headroom: number | null;
+}
+
+export interface MatchResult {
+  requirement: JobRequirement;
+  /** Eligible resources first (headroom desc, id asc), then ineligible by id. */
+  matches: ResourceMatch[];
+  /** Ids of eligible resources in match order. */
+  eligible: string[];
+}
+
+export interface MatchOptions {
+  /** HOLD file present at the queue dir — blocks every resource. */
+  fleetHold?: boolean;
+  /** Fleet-wide running total and hard cap; blocks all only when certainly full. */
+  fleet?: { running: number | null; hardCap: number | null };
+  /** Cap on returned matches (eligible ordering preserved). Default unlimited. */
+  limit?: number;
+}
+
+export interface CapabilityDocument {
+  schema: "fleet.capabilities.v1";
+  resources: ReadonlyMap<string, CapabilityDeclaration>;
+  /** Resource entries skipped for invalid shape (they fall back to defaults). */
+  dropped: number;
+}
+
+export type CapabilityDocumentResult =
+  | { status: "ok"; document: CapabilityDocument; error: null }
+  | { status: "invalid"; document: null; error: string };
+
+const nonNegInt = (value: unknown): number | null =>
+  typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+
+function parseStringList(value: unknown, valid: (v: unknown) => boolean): string[] | null {
+  if (!Array.isArray(value) || value.some((v) => !valid(v))) return null;
+  return [...new Set(value as string[])];
+}
+
+/**
+ * Parse a capabilities.json document. Strict about shape, lenient about scope:
+ * unknown keys are ignored, but a resource entry with an invalid roles /
+ * capabilities / tiers field is dropped whole and counted in `dropped` — an
+ * invalid declaration must never silently narrow or widen a resource.
+ */
+export function parseCapabilityDocument(text: string): CapabilityDocumentResult {
+  let root: unknown;
+  try {
+    root = JSON.parse(text);
+  } catch {
+    return { status: "invalid", document: null, error: "not valid JSON" };
+  }
+  if (!isRecord(root)) return { status: "invalid", document: null, error: "not a JSON object" };
+  if (root.schema !== "fleet.capabilities.v1")
+    return { status: "invalid", document: null, error: 'expected schema "fleet.capabilities.v1"' };
+  if (root.resources !== undefined && !isRecord(root.resources))
+    return { status: "invalid", document: null, error: '"resources" must be an object' };
+
+  const resources = new Map<string, CapabilityDeclaration>();
+  let dropped = 0;
+  for (const [id, value] of Object.entries(isRecord(root.resources) ? root.resources : {})) {
+    if (!isResourceId(id) || !isRecord(value)) {
+      dropped++;
+      continue;
+    }
+    let roles: FleetRole[] | null = null;
+    if (value.roles !== undefined) {
+      const parsed = parseStringList(value.roles, isFleetRole);
+      if (parsed === null) {
+        dropped++;
+        continue;
+      }
+      roles = parsed as FleetRole[];
+    }
+    let capabilities: string[] = [];
+    if (value.capabilities !== undefined) {
+      const parsed = parseStringList(value.capabilities, isTag);
+      if (parsed === null) {
+        dropped++;
+        continue;
+      }
+      capabilities = parsed;
+    }
+    let tiers: string[] | null = null;
+    if (value.tiers !== undefined) {
+      const parsed = parseStringList(value.tiers, isTier);
+      if (parsed === null) {
+        dropped++;
+        continue;
+      }
+      tiers = parsed;
+    }
+    resources.set(id, { roles, capabilities, tiers });
+  }
+  return {
+    status: "ok",
+    document: { schema: "fleet.capabilities.v1", resources, dropped },
+    error: null,
+  };
+}
+
+/** Effective roles for a declaration; absent declaration or absent `roles` → implementer. */
+export function effectiveRoles(
+  declaration: CapabilityDeclaration | undefined,
+): readonly FleetRole[] {
+  return declaration?.roles ?? DEFAULT_RESOURCE_ROLES;
+}
+
+/** Merge a declaration with observed quota into a matchable resource. */
+export function buildFleetResource(
+  id: string,
+  declaration: CapabilityDeclaration | undefined,
+  quota: FleetResourceQuota | null,
+): FleetResource {
+  return {
+    id,
+    declared: declaration !== undefined,
+    roles: effectiveRoles(declaration),
+    capabilities: declaration?.capabilities ?? [],
+    tiers: declaration?.tiers ?? null,
+    quota,
+  };
+}
+
+/** Smallest known launch bound; null when no quota field is usable. */
+export function capacityBound(quota: FleetResourceQuota): number | null {
+  const bounds = [quota.target, quota.ceiling, quota.hardCap].filter(
+    (v): v is number => v !== null,
+  );
+  return bounds.length ? Math.min(...bounds) : null;
+}
+
+/** capacityBound - running; null when either side is unknown. */
+export function resourceHeadroom(quota: FleetResourceQuota | null): number | null {
+  if (quota === null || quota.running === null) return null;
+  const bound = capacityBound(quota);
+  return bound === null ? null : Math.max(0, bound - quota.running);
+}
+
+/**
+ * Match one job requirement against resources. Provider- and lane-name
+ * agnostic: only declared roles, capability tags, tier coverage, holds and
+ * observed quota decide eligibility.
+ */
+export function matchRequirement(
+  requirement: JobRequirement,
+  resources: readonly FleetResource[],
+  options: MatchOptions = {},
+): MatchResult {
+  const fleetFull =
+    options.fleet?.hardCap != null &&
+    options.fleet.running != null &&
+    options.fleet.running >= options.fleet.hardCap;
+  const matches: ResourceMatch[] = resources.map((resource) => {
+    const reasons: string[] = [];
+    if (!resource.roles.includes(requirement.role))
+      reasons.push(`missing-role:${requirement.role}`);
+    for (const tag of requirement.capabilities)
+      if (!resource.capabilities.includes(tag)) reasons.push(`missing-capability:${tag}`);
+    if (
+      requirement.tier !== null &&
+      resource.tiers !== null &&
+      !resource.tiers.includes(requirement.tier)
+    )
+      reasons.push(`tier-unsupported:${requirement.tier}`);
+    if (options.fleetHold === true) reasons.push("fleet-hold");
+    if (fleetFull) reasons.push("fleet-at-capacity");
+    if (resource.quota?.held === true) reasons.push("held");
+    const headroom = resourceHeadroom(resource.quota);
+    if (headroom === 0) reasons.push("at-capacity");
+    return { id: resource.id, eligible: reasons.length === 0, reasons, headroom };
+  });
+  matches.sort((a, b) => {
+    if (a.eligible !== b.eligible) return a.eligible ? -1 : 1;
+    if (a.eligible) {
+      // Eligible: most headroom first; unknown headroom sorts last; id breaks ties.
+      if (a.headroom !== b.headroom) {
+        if (a.headroom === null) return 1;
+        if (b.headroom === null) return -1;
+        return b.headroom - a.headroom;
+      }
+    }
+    return a.id.localeCompare(b.id);
+  });
+  const limited = options.limit === undefined ? matches : matches.slice(0, options.limit);
+  return {
+    requirement,
+    matches: limited,
+    eligible: limited.filter((m) => m.eligible).map((m) => m.id),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// models.json — flat `lane[.tier]` → model map; resolution mirrors dispatchd.
+// ---------------------------------------------------------------------------
+
+const MODEL_KEY_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const MODEL_RE = /^[A-Za-z0-9][A-Za-z0-9._:/+-]{0,127}$/;
+
+export interface ModelMap {
+  map: ReadonlyMap<string, string>;
+  dropped: number;
+  /** "invalid" when the text is not a JSON object; entries may still be dropped from a valid doc. */
+  status: "ok" | "invalid";
+}
+
+/** Parse ~/.ashlr-runs/models.json: `{ "<resource>[.<tier>]": "<model>" }`. */
+export function parseModelMap(text: string): ModelMap {
+  const map = new Map<string, string>();
+  let dropped = 0;
+  let root: unknown;
+  try {
+    root = JSON.parse(text);
+  } catch {
+    return { map, dropped: 1, status: "invalid" };
+  }
+  if (!isRecord(root)) return { map, dropped: 1, status: "invalid" };
+  for (const [key, value] of Object.entries(root)) {
+    const dot = key.indexOf(".");
+    const lane = dot < 0 ? key : key.slice(0, dot);
+    const tier = dot < 0 ? null : key.slice(dot + 1);
+    if (
+      !MODEL_KEY_RE.test(lane) ||
+      (tier !== null && !isTier(tier)) ||
+      typeof value !== "string" ||
+      !MODEL_RE.test(value.trim())
+    ) {
+      dropped++;
+      continue;
+    }
+    map.set(key, value.trim());
+  }
+  return { map, dropped, status: "ok" };
+}
+
+/** The map family dispatchd uses: `codex` for codex-* lanes except codex-local. */
+export const modelFamily = (resourceId: string): string =>
+  resourceId.startsWith("codex") && resourceId !== "codex-local" ? "codex" : resourceId;
+
+/** First non-empty of `<id>.<tier>`, `<id>`, `<family>.<tier>`, `<family>`. */
+export function resolveModel(
+  map: ReadonlyMap<string, string>,
+  resourceId: string,
+  tier: string | null,
+): { model: string; via: string } | null {
+  const family = modelFamily(resourceId);
+  const keys =
+    family === resourceId
+      ? tier === null
+        ? [resourceId]
+        : [`${resourceId}.${tier}`, resourceId]
+      : tier === null
+        ? [resourceId, family]
+        : [`${resourceId}.${tier}`, resourceId, `${family}.${tier}`, family];
+  for (const key of keys) {
+    const model = map.get(key);
+    if (model) return { model, via: key };
+  }
+  return null;
+}

package/src/fleet/job-run.ts

@@ -0,0 +1,190 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+
+/**
+ * job-run.ts — per-execution structured result records for fleet jobs.
+ *
+ * Motivation: stacksync execution 5d2b848b died inside `write_sheet_jobs` and
+ * the only artifact was an unstructured error line — remotely we could not
+ * tell which stage failed, how long each stage took, or how many rows were
+ * pulled vs. committed. Every staged job run now ends with one JobRunRecord:
+ * per-stage timings, rows in/out, and the last error tagged with its stage.
+ *
+ * The record is emitted as a single-line JSON log (greppable in journald or
+ * any log drain) and, when `tablePath` is set, appended as one row to a JSONL
+ * table that `readFleetJsonl` / `jq` can query. Records carry counts and a
+ * bounded, flattened error message — never row payloads.
+ */
+
+export const JOB_RUN_SCHEMA = "fleet.job-run.v1";
+
+/** Stacksync's fixed pipeline order: source read → row transform → sheet write. */
+export const SYNC_STAGES = ["read_postgres", "transform", "write_sheet_jobs"] as const;
+export type SyncStageName = (typeof SYNC_STAGES)[number];
+
+export type StageStatus = "ok" | "error" | "skipped";
+
+export interface StageTiming {
+  stage: string;
+  status: StageStatus;
+  /** Wall time of the stage; null when the stage never ran (skipped). */
+  durationMs: number | null;
+  /** Rows the stage consumed. */
+  rowsIn: number;
+  /** Rows the stage produced; on a failed write this is the partial commit count. */
+  rowsOut: number;
+}
+
+export interface JobRunError {
+  stage: string;
+  message: string;
+}
+
+export interface JobRunRecord {
+  schema: typeof JOB_RUN_SCHEMA;
+  job: string;
+  executionId: string;
+  /** Sync direction for two-way jobs, e.g. "postgres->sheets"; null when unset. */
+  direction: string | null;
+  startedAt: string;
+  finishedAt: string;
+  durationMs: number;
+  status: "ok" | "error";
+  /** Rows that entered the pipeline: the first stage's input, or its output when
+   * it is a source stage (read_postgres reports only rowsOut). */
+  rowsIn: number;
+  /** Rows the pipeline emitted: the last attempted stage's output — partial on failure. */
+  rowsOut: number;
+  stages: StageTiming[];
+  lastError: JobRunError | null;
+  /** Set when the JSONL table append failed; the log line is then the only copy. */
+  persistError: string | null;
+}
+
+/** Mutable counters handed to a stage; partial values survive a throw. */
+export interface StageCounts {
+  rowsIn: number;
+  rowsOut: number;
+}
+
+export interface JobStage {
+  name: string;
+  run: (counts: StageCounts) => void | Promise<void>;
+}
+
+export interface RunJobOptions {
+  stages: readonly JobStage[];
+  /** Job name stamped on the record. Default "stacksync". */
+  job?: string;
+  /** Caller-assigned execution id (e.g. "5d2b848b"); defaults to a random 8-hex id. */
+  executionId?: string;
+  /** Sync direction label, e.g. "postgres->sheets". */
+  direction?: string;
+  /** JSONL table path; when set the record is appended as one line. */
+  tablePath?: string;
+  /** Log-line sink; default writes one JSON line to stdout. Pass `false` to silence. */
+  logLine?: ((line: string) => void) | false;
+  /** Wall clock for ISO stamps and durations (ms); default Date.now. */
+  now?: () => number;
+}
+
+/** Cap on recorded error text — provider error bodies can be kilobytes. */
+const MAX_ERROR_MESSAGE = 500;
+
+function errorMessage(error: unknown): string {
+  const raw = error instanceof Error ? error.message : String(error);
+  const flat = raw.replace(/\s+/g, " ").trim();
+  return flat.length > MAX_ERROR_MESSAGE ? `${flat.slice(0, MAX_ERROR_MESSAGE)}...` : flat;
+}
+
+/** Junk counts (negative, non-finite) record as 0 — a record must never carry NaN. */
+const rowCount = (value: number): number =>
+  Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+
+const defaultLogLine = (line: string): void => console.log(line);
+
+/** Append one record to a JSONL table, creating the parent directory as needed. */
+export async function appendJobRunRecord(path: string, record: JobRunRecord): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await appendFile(path, `${JSON.stringify(record)}\n`, "utf8");
+}
+
+/**
+ * Run `stages` in order and return the execution record. The record — not a
+ * throw — is the outcome: callers branch on `record.status` /
+ * `record.lastError`. A stage that throws ends the run; the failing stage's
+ * timing and partial counts are kept, later stages are marked "skipped", and
+ * the record is still emitted so a remote run leaves evidence.
+ */
+export async function runJobStages(options: RunJobOptions): Promise<JobRunRecord> {
+  const now = options.now ?? Date.now;
+  const startMs = now();
+  const timings: StageTiming[] = [];
+  let lastError: JobRunError | null = null;
+
+  for (const stage of options.stages) {
+    if (lastError !== null) {
+      timings.push({
+        stage: stage.name,
+        status: "skipped",
+        durationMs: null,
+        rowsIn: 0,
+        rowsOut: 0,
+      });
+      continue;
+    }
+    const counts: StageCounts = { rowsIn: 0, rowsOut: 0 };
+    const stageStart = now();
+    try {
+      await stage.run(counts);
+      timings.push({
+        stage: stage.name,
+        status: "ok",
+        durationMs: Math.max(0, Math.round(now() - stageStart)),
+        rowsIn: rowCount(counts.rowsIn),
+        rowsOut: rowCount(counts.rowsOut),
+      });
+    } catch (error) {
+      timings.push({
+        stage: stage.name,
+        status: "error",
+        durationMs: Math.max(0, Math.round(now() - stageStart)),
+        rowsIn: rowCount(counts.rowsIn),
+        rowsOut: rowCount(counts.rowsOut),
+      });
+      lastError = { stage: stage.name, message: errorMessage(error) };
+    }
+  }
+
+  const endMs = now();
+  const attempted = timings.filter((t) => t.status !== "skipped");
+  const first = attempted[0];
+  const last = attempted[attempted.length - 1];
+  const record: JobRunRecord = {
+    schema: JOB_RUN_SCHEMA,
+    job: options.job ?? "stacksync",
+    executionId: options.executionId ?? crypto.randomUUID().slice(0, 8),
+    direction: options.direction ?? null,
+    startedAt: new Date(startMs).toISOString(),
+    finishedAt: new Date(endMs).toISOString(),
+    durationMs: Math.max(0, Math.round(endMs - startMs)),
+    status: lastError === null ? "ok" : "error",
+    rowsIn: first ? first.rowsIn || first.rowsOut : 0,
+    rowsOut: last?.rowsOut ?? 0,
+    stages: timings,
+    lastError,
+    persistError: null,
+  };
+
+  if (options.tablePath) {
+    try {
+      await appendJobRunRecord(options.tablePath, record);
+    } catch (error) {
+      record.persistError = errorMessage(error);
+    }
+  }
+
+  const sink = options.logLine === undefined ? defaultLogLine : options.logLine;
+  if (sink) sink(JSON.stringify(record));
+  return record;
+}

package/src/http.ts

@@ -56,23 +56,21 @@ export async function fetchWithRetry(
   const baseDelayMs = opts.baseDelayMs ?? 400;
   const maxDelayMs = opts.maxDelayMs ?? 8000;
   const retryOn = opts.retryOn ?? defaultRetryOn;
-  const idempotent = opts.idempotent ?? isIdempotent(init?.method);
-  const signal = opts.signal;
+  const idempotent =
+    opts.idempotent ??
+    isIdempotent(init?.method ?? (input instanceof Request ? input.method : undefined));
+  const requestSignal = init?.signal ?? (input instanceof Request ? input.signal : undefined);
+  const mergedInit = mergeSignal({ ...init, signal: requestSignal }, opts.signal);
+  const signal = mergedInit?.signal ?? undefined;
 
   let attempt = 0;
-  // Track the last non-ok response so a final failure returns something the
-  // caller can inspect (status / body) rather than a synthetic error.
-  let lastResponse: Response | undefined;
-  let lastError: unknown;
-
   while (true) {
     if (signal?.aborted) throw abortError(signal);
 
     try {
-      const res = await fetch(input, mergeSignal(init, signal));
+      const res = await fetch(input, mergedInit);
       if (res.ok || !idempotent || !retryOn(res)) return res;
 
-      lastResponse = res;
       if (attempt >= retries) return res;
 
       const waitMs = computeDelay(res, attempt, baseDelayMs, maxDelayMs);
@@ -82,19 +80,14 @@ export async function fetchWithRetry(
       // Network-level failure (DNS, connection reset, fetch threw). Only retry
       // for idempotent requests — a POST that "failed" may have actually been
       // accepted by the remote before the connection dropped.
+      if (signal?.aborted) throw abortError(signal);
       if (isAbortError(err)) throw err;
-      lastError = err;
       if (!idempotent || attempt >= retries) throw err;
       const waitMs = computeDelay(undefined, attempt, baseDelayMs, maxDelayMs);
       await sleep(waitMs, signal);
       attempt++;
     }
   }
-
-  // Unreachable — both branches above either return or throw. The assignment
-  // to lastResponse/lastError keeps TS happy if the loop ever changes shape.
-  void lastResponse;
-  void lastError;
 }
 
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -75,3 +75,5 @@ export {
   type UsageRecord,
 } from "./ai/cost-tracker.ts";
 export * from "./agent-onboard.ts";
+export * from "./fleet/capability-matrix.ts";
+export * from "./fleet/job-run.ts";