@ashlr/stack-core 0.3.7 → 0.3.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashlr/stack-core",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "Ashlr Stack core — provider adapters, .stack.toml config, Phantom integration. Shared logic behind the Stack CLI and MCP server.",
   "license": "MIT",
   "author": {

package/src/__tests__/_harness.ts

@@ -3,6 +3,26 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { __resetPhantomCache } from "../phantom.ts";
 
+/** Install a source-owned fake executable with an interpreter-appropriate target. */
+export function writeShimmedExecutable(
+  dir: string,
+  name: string,
+  script: string,
+  ext = "sh",
+): string {
+  const realPath = join(dir, `${name}.${ext}`);
+  const binPath = join(dir, name);
+  writeFileSync(realPath, script);
+  chmodSync(realPath, 0o700);
+  try {
+    symlinkSync(realPath, binPath);
+  } catch {
+    writeFileSync(binPath, script);
+    chmodSync(binPath, 0o700);
+  }
+  return binPath;
+}
+
 /**
  * Fake `phantom` binary for integration tests. Writes a bash script into a
  * tmpdir, prepends that tmpdir to PATH, and exposes helpers to inspect the
@@ -163,20 +183,7 @@ case "\${1:-}" in
     ;;
 esac
 `;
-  const binPath = join(dir, "phantom");
-  // Sandboxed runners and macOS Gatekeeper's provenance policy refuse to
-  // exec an extensionless file written by a non-platform process, while a
-  // `*.sh` target passes the check. Write the shim as `phantom.sh` and link
-  // `phantom` at it; fall back to the direct file where symlinks fail.
-  const realPath = join(dir, "phantom.sh");
-  writeFileSync(realPath, script);
-  chmodSync(realPath, 0o755);
-  try {
-    symlinkSync(realPath, binPath);
-  } catch {
-    writeFileSync(binPath, script);
-    chmodSync(binPath, 0o755);
-  }
+  writeShimmedExecutable(dir, "phantom", script);
 
   const previousPath = process.env.PATH ?? "";
   process.env.PATH = `${dir}:${previousPath}`;

package/src/__tests__/fixtures/stack-manifest.v1.json

@@ -2,9 +2,9 @@
   "schema_version": 1,
   "kind": "ashlr-stack-manifest",
   "components": [
-    { "id": "core", "name": "@ashlr/stack-core", "version": "0.3.7", "distribution": "npm" },
-    { "id": "cli", "name": "@ashlr/stack", "version": "0.3.7", "distribution": "npm" },
-    { "id": "mcp", "name": "ashlr-stack-mcp", "version": "0.3.7", "distribution": "npm" },
+    { "id": "core", "name": "@ashlr/stack-core", "version": "0.3.9", "distribution": "npm" },
+    { "id": "cli", "name": "@ashlr/stack", "version": "0.3.9", "distribution": "npm" },
+    { "id": "mcp", "name": "ashlr-stack-mcp", "version": "0.3.9", "distribution": "npm" },
     { "id": "plugin", "name": "stack", "version": "0.1.0", "distribution": "claude-code-plugin" }
   ]
 }

package/src/__tests__/fleet-capability-matrix.test.ts

@@ -0,0 +1,357 @@
+import { describe, expect, test } from "bun:test";
+import {
+  type CapabilityDeclaration,
+  DEFAULT_RESOURCE_ROLES,
+  FLEET_ROLES,
+  type FleetResource,
+  type FleetResourceQuota,
+  type JobRequirement,
+  buildFleetResource,
+  capacityBound,
+  effectiveRoles,
+  isFleetRole,
+  matchRequirement,
+  modelFamily,
+  parseCapabilityDocument,
+  parseModelMap,
+  resolveModel,
+  resourceHeadroom,
+} from "../fleet/capability-matrix.ts";
+
+const quota = (over: Partial<FleetResourceQuota> = {}): FleetResourceQuota => ({
+  target: null,
+  ceiling: null,
+  hardCap: null,
+  held: false,
+  running: null,
+  queued: null,
+  quotaRemaining: null,
+  ...over,
+});
+
+const resource = (id: string, over: Partial<Omit<FleetResource, "id">> = {}): FleetResource => ({
+  id,
+  declared: false,
+  roles: DEFAULT_RESOURCE_ROLES,
+  capabilities: [],
+  tiers: null,
+  quota: null,
+  ...over,
+});
+
+const requirement = (over: Partial<JobRequirement> = {}): JobRequirement => ({
+  role: "implementer",
+  capabilities: [],
+  tier: null,
+  ...over,
+});
+
+describe("parseCapabilityDocument", () => {
+  test("parses a minimal valid document", () => {
+    const result = parseCapabilityDocument(
+      JSON.stringify({
+        schema: "fleet.capabilities.v1",
+        resources: {
+          "codex-cmp": { roles: ["implementer", "reviewer"], capabilities: ["ci-watch"] },
+          local: { roles: [], tiers: ["mid", "fast"] },
+        },
+      }),
+    );
+    expect(result.status).toBe("ok");
+    expect(result.error).toBeNull();
+    const doc = result.document!;
+    expect(doc.schema).toBe("fleet.capabilities.v1");
+    expect(doc.dropped).toBe(0);
+    expect(doc.resources.get("codex-cmp")).toEqual({
+      roles: ["implementer", "reviewer"],
+      capabilities: ["ci-watch"],
+      tiers: null,
+    });
+    expect(doc.resources.get("local")).toEqual({
+      roles: [],
+      capabilities: [],
+      tiers: ["mid", "fast"],
+    });
+  });
+
+  test("rejects malformed JSON, non-objects and wrong schema", () => {
+    for (const [text, error] of [
+      ["not json", "not valid JSON"],
+      ["[1,2]", "not a JSON object"],
+      ['{"resources":{}}', 'expected schema "fleet.capabilities.v1"'],
+      ['{"schema":"fleet.capabilities.v1","resources":[]} ', '"resources" must be an object'],
+    ] as const) {
+      const result = parseCapabilityDocument(text);
+      expect(result.status).toBe("invalid");
+      expect(result.document).toBeNull();
+      expect(result.error).toBe(error);
+    }
+  });
+
+  test("missing resources means an empty document", () => {
+    const result = parseCapabilityDocument('{"schema":"fleet.capabilities.v1"}');
+    expect(result.status).toBe("ok");
+    expect(result.document!.resources.size).toBe(0);
+  });
+
+  test("drops invalid resource entries whole and counts them", () => {
+    const result = parseCapabilityDocument(
+      JSON.stringify({
+        schema: "fleet.capabilities.v1",
+        resources: {
+          good: { capabilities: ["local-inference"] },
+          "bad role": { roles: ["implementer"] }, // invalid resource id
+          typo: { roles: ["reviewr"] }, // unknown role
+          badcap: { capabilities: ["Local Inference"] }, // invalid tag
+          badtier: { tiers: ["FRONTIER"] }, // invalid tier
+          wrongtype: { roles: "implementer" }, // roles not an array
+          "": {}, // empty id
+          "has space": {}, // invalid id
+        },
+      }),
+    );
+    expect(result.status).toBe("ok");
+    const doc = result.document!;
+    expect([...doc.resources.keys()]).toEqual(["good"]);
+    expect(doc.dropped).toBe(7);
+  });
+
+  test("ignores unknown keys for forward compatibility", () => {
+    const result = parseCapabilityDocument(
+      JSON.stringify({
+        schema: "fleet.capabilities.v1",
+        comment: "operator notes",
+        resources: { a: { roles: ["planner"], note: "free text" } },
+      }),
+    );
+    expect(result.status).toBe("ok");
+    expect(result.document!.resources.get("a")).toEqual({
+      roles: ["planner"],
+      capabilities: [],
+      tiers: null,
+    });
+  });
+
+  test("dedupes repeated tags and roles", () => {
+    const result = parseCapabilityDocument(
+      JSON.stringify({
+        schema: "fleet.capabilities.v1",
+        resources: { a: { roles: ["reviewer", "reviewer"], capabilities: ["publish", "publish"] } },
+      }),
+    );
+    expect(result.document!.resources.get("a")).toEqual({
+      roles: ["reviewer"],
+      capabilities: ["publish"],
+      tiers: null,
+    });
+  });
+});
+
+describe("effectiveRoles / buildFleetResource", () => {
+  test("undeclared resources default to implementer on all tiers", () => {
+    const resource = buildFleetResource("any-lane", undefined, null);
+    expect(resource.declared).toBe(false);
+    expect(resource.roles).toEqual(["implementer"]);
+    expect(resource.capabilities).toEqual([]);
+    expect(resource.tiers).toBeNull();
+    expect(resource.quota).toBeNull();
+  });
+
+  test("explicit empty roles serve nothing; absent roles keep the default", () => {
+    const none: CapabilityDeclaration = { roles: [], capabilities: [], tiers: null };
+    const partial: CapabilityDeclaration = { roles: null, capabilities: ["publish"], tiers: null };
+    expect(effectiveRoles(none)).toEqual([]);
+    expect(effectiveRoles(partial)).toEqual(["implementer"]);
+    expect(buildFleetResource("r", none, null).roles).toEqual([]);
+    expect(buildFleetResource("r", partial, null).capabilities).toEqual(["publish"]);
+  });
+});
+
+describe("headroom", () => {
+  test("capacity is the smallest known bound; headroom subtracts running", () => {
+    expect(capacityBound(quota({ target: 10, ceiling: 32, hardCap: 8 }))).toBe(8);
+    expect(capacityBound(quota({ ceiling: 4 }))).toBe(4);
+    expect(capacityBound(quota())).toBeNull();
+    expect(resourceHeadroom(quota({ target: 6, running: 4 }))).toBe(2);
+    expect(resourceHeadroom(quota({ target: 6, running: 9 }))).toBe(0);
+    expect(resourceHeadroom(quota({ running: 4 }))).toBeNull();
+    expect(resourceHeadroom(null)).toBeNull();
+  });
+});
+
+describe("matchRequirement", () => {
+  const reviewerOnly = resource("reviewer-box", {
+    declared: true,
+    roles: ["reviewer"],
+    capabilities: ["ci-watch"],
+    tiers: ["work", "mid"],
+    quota: quota({ target: 2, running: 1 }),
+  });
+  const general = resource("general-lane", { quota: quota({ target: 4, running: 4 }) });
+  const local = resource("local-lane", {
+    declared: true,
+    roles: ["implementer", "planner"],
+    capabilities: ["local-inference"],
+    tiers: ["mid", "fast"],
+    quota: quota({ target: 6, running: 0 }),
+  });
+  const held = resource("held-lane", { quota: quota({ target: 4, running: 0, held: true }) });
+  const unknownQuota = resource("mystery", { declared: true, roles: ["implementer"] });
+  const resources = [reviewerOnly, general, local, held, unknownQuota];
+
+  test("implementer matches every undeclared-default lane with headroom or unknown quota", () => {
+    const result = matchRequirement(requirement(), resources);
+    // general is at capacity (running 4 >= target 4); held is held; reviewer-box lacks the role.
+    expect(result.eligible).toEqual(["local-lane", "mystery"]);
+    const byId = new Map(result.matches.map((m) => [m.id, m]));
+    expect(byId.get("general-lane")).toMatchObject({
+      eligible: false,
+      reasons: ["at-capacity"],
+      headroom: 0,
+    });
+    expect(byId.get("held-lane")!.reasons).toContain("held");
+    expect(byId.get("reviewer-box")!.reasons).toContain("missing-role:implementer");
+    expect(byId.get("mystery")).toMatchObject({ eligible: true, headroom: null });
+  });
+
+  test("reviewer role binds only to the declared reviewer resource", () => {
+    const result = matchRequirement(requirement({ role: "reviewer" }), resources);
+    expect(result.eligible).toEqual(["reviewer-box"]);
+    expect(result.matches.find((m) => m.id === "local-lane")!.reasons).toContain(
+      "missing-role:reviewer",
+    );
+  });
+
+  test("capability requirements narrow eligibility independently of tier", () => {
+    const result = matchRequirement(
+      requirement({ capabilities: ["local-inference"], tier: "mid" }),
+      resources,
+    );
+    expect(result.eligible).toEqual(["local-lane"]);
+    const byId = new Map(result.matches.map((m) => [m.id, m]));
+    // reviewer-box serves mid but lacks local-inference and the implementer role.
+    expect(byId.get("reviewer-box")!.reasons).toEqual(
+      expect.arrayContaining(["missing-role:implementer", "missing-capability:local-inference"]),
+    );
+    // mystery has unrestricted tiers, so only the capability tag blocks it.
+    expect(byId.get("mystery")!.reasons).toEqual(["missing-capability:local-inference"]);
+    // general-lane is also at capacity; held-lane is held.
+    expect(byId.get("general-lane")!.reasons).toContain("at-capacity");
+    expect(byId.get("held-lane")!.reasons).toContain("held");
+  });
+
+  test("tier check only applies when the resource restricts tiers", () => {
+    const open = resource("open-lane", { quota: quota({ target: 4, running: 1 }) });
+    const result = matchRequirement(requirement({ tier: "frontier" }), [open, local]);
+    const byId = new Map(result.matches.map((m) => [m.id, m]));
+    expect(byId.get("open-lane")!.eligible).toBe(true); // tiers null = unrestricted
+    expect(byId.get("local-lane")!.reasons).toContain("tier-unsupported:frontier");
+  });
+
+  test("fleet HOLD and fleet hard cap block every resource", () => {
+    const held = matchRequirement(requirement(), [general, local], { fleetHold: true });
+    expect(held.eligible).toEqual([]);
+    expect(held.matches.every((m) => m.reasons.includes("fleet-hold"))).toBe(true);
+
+    const full = matchRequirement(requirement(), [general, local], {
+      fleet: { running: 18, hardCap: 18 },
+    });
+    expect(full.eligible).toEqual([]);
+    expect(full.matches.every((m) => m.reasons.includes("fleet-at-capacity"))).toBe(true);
+
+    // Below the cap, or unknown running/hardCap, nothing fleet-level blocks.
+    const open = matchRequirement(requirement(), [general, local], {
+      fleet: { running: 3, hardCap: 18 },
+    });
+    expect(open.matches.some((m) => m.reasons.includes("fleet-at-capacity"))).toBe(false);
+    const unknown = matchRequirement(requirement(), [general, local], {
+      fleet: { running: null, hardCap: 18 },
+    });
+    expect(unknown.matches.some((m) => m.reasons.includes("fleet-at-capacity"))).toBe(false);
+  });
+
+  test("eligible ordering: headroom desc, unknown last, id tie-break; limit truncates", () => {
+    const a = resource("b-lane", { quota: quota({ target: 5, running: 1 }) }); // headroom 4
+    const b = resource("a-lane", { quota: quota({ target: 9, running: 1 }) }); // headroom 8
+    const c = resource("c-lane"); // headroom null
+    const result = matchRequirement(requirement(), [a, b, c]);
+    expect(result.eligible).toEqual(["a-lane", "b-lane", "c-lane"]);
+    const limited = matchRequirement(requirement(), [a, b, c], { limit: 2 });
+    expect(limited.matches.map((m) => m.id)).toEqual(["a-lane", "b-lane"]);
+    expect(limited.eligible).toEqual(["a-lane", "b-lane"]);
+  });
+
+  test("is provider-name agnostic: identical declarations match identically", () => {
+    const decl: CapabilityDeclaration = {
+      roles: ["implementer", "reviewer"],
+      capabilities: ["publish"],
+      tiers: null,
+    };
+    const one = buildFleetResource("devin", decl, quota({ target: 2, running: 0 }));
+    const two = buildFleetResource("acme-runner-7", decl, quota({ target: 2, running: 0 }));
+    const result = matchRequirement(requirement({ capabilities: ["publish"] }), [one, two]);
+    expect(result.eligible).toEqual(["acme-runner-7", "devin"]);
+  });
+});
+
+describe("parseModelMap / resolveModel", () => {
+  test("parses flat lane[.tier] model entries and drops invalid ones", () => {
+    const { map, dropped } = parseModelMap(
+      JSON.stringify({
+        "codex.work": "gpt-5.3-codex",
+        devin: "swe-2-flash-max",
+        "codex-local.mid": "qwen3-coder-next",
+        "": "bad",
+        "bad key": "x",
+        num: 3,
+      }),
+    );
+    expect(dropped).toBe(3);
+    expect(map.get("codex.work")).toBe("gpt-5.3-codex");
+    expect(map.get("devin")).toBe("swe-2-flash-max");
+  });
+
+  test("invalid JSON yields an empty map", () => {
+    expect(parseModelMap("nope").map.size).toBe(0);
+    expect(parseModelMap("nope").dropped).toBe(1);
+    expect(parseModelMap("nope").status).toBe("invalid");
+    expect(parseModelMap("[]").status).toBe("invalid");
+    expect(parseModelMap("{}").status).toBe("ok");
+  });
+
+  test("resolveModel mirrors dispatchd precedence: lane.tier, lane, family.tier, family", () => {
+    const { map } = parseModelMap(
+      JSON.stringify({
+        "codex-cmp.work": "cmp-work-model",
+        "codex.work": "family-work-model",
+        codex: "family-model",
+        "codex-local": "local-model",
+        devin: "devin-model",
+      }),
+    );
+    // codex-cmp is a codex family member but keeps its own lane keys first.
+    expect(resolveModel(map, "codex-cmp", "work")).toEqual({
+      model: "cmp-work-model",
+      via: "codex-cmp.work",
+    });
+    expect(resolveModel(map, "codex-cmp", "fast")).toEqual({
+      model: "family-model",
+      via: "codex",
+    });
+    // codex-local is its own family (dispatchd excludes it from the codex fold).
+    expect(modelFamily("codex-local")).toBe("codex-local");
+    expect(modelFamily("codex-cmp")).toBe("codex");
+    expect(resolveModel(map, "codex-local", "mid")).toEqual({
+      model: "local-model",
+      via: "codex-local",
+    });
+    expect(resolveModel(map, "devin", null)).toEqual({ model: "devin-model", via: "devin" });
+    expect(resolveModel(map, "ghost", "work")).toBeNull();
+  });
+});
+
+test("vocabulary sanity", () => {
+  expect(FLEET_ROLES).toEqual(["planner", "implementer", "reviewer", "release-verifier"]);
+  expect(isFleetRole("implementer")).toBe(true);
+  expect(isFleetRole(" Implementer ")).toBe(false);
+});

package/src/__tests__/fleet-job-run.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  JOB_RUN_SCHEMA,
+  type JobRunRecord,
+  appendJobRunRecord,
+  runJobStages,
+} from "../fleet/job-run.ts";
+
+const tmp = () => mkdtemp(join(tmpdir(), "fleet-job-run-"));
+
+/** A clock that advances `step` ms per call — deterministic timings and stamps. */
+const fakeClock = (start = 1_000, step = 25) => {
+  let t = start;
+  return () => {
+    t += step;
+    return t;
+  };
+};
+
+describe("runJobStages", () => {
+  test("failed write_sheet_jobs produces a queryable record with stage name and partial counts", async () => {
+    // Mirrors production execution 5d2b848b: the sheet write died mid-batch and
+    // the run left no structured trace of which stage failed or how far it got.
+    const lines: string[] = [];
+    const dir = await tmp();
+    const tablePath = join(dir, "job-runs.jsonl");
+    const record = await runJobStages({
+      executionId: "5d2b848b",
+      direction: "postgres->sheets",
+      tablePath,
+      logLine: (line) => lines.push(line),
+      now: fakeClock(),
+      stages: [
+        {
+          name: "read_postgres",
+          run: (c) => {
+            c.rowsOut = 1200;
+          },
+        },
+        {
+          name: "transform",
+          run: (c) => {
+            c.rowsIn = 1200;
+            c.rowsOut = 1150;
+          },
+        },
+        {
+          name: "write_sheet_jobs",
+          run: (c) => {
+            c.rowsIn = 1150;
+            c.rowsOut = 340; // partial commit before the API rejected the batch
+            throw new Error("Sheets API 429: quota exceeded");
+          },
+        },
+      ],
+    });
+
+    expect(record.schema).toBe(JOB_RUN_SCHEMA);
+    expect(record.job).toBe("stacksync");
+    expect(record.executionId).toBe("5d2b848b");
+    expect(record.direction).toBe("postgres->sheets");
+    expect(record.status).toBe("error");
+    expect(record.lastError).toEqual({
+      stage: "write_sheet_jobs",
+      message: "Sheets API 429: quota exceeded",
+    });
+    // Every stage ran, each with a measured duration; the write kept its partial count.
+    expect(record.stages).toEqual([
+      { stage: "read_postgres", status: "ok", durationMs: 25, rowsIn: 0, rowsOut: 1200 },
+      { stage: "transform", status: "ok", durationMs: 25, rowsIn: 1200, rowsOut: 1150 },
+      { stage: "write_sheet_jobs", status: "error", durationMs: 25, rowsIn: 1150, rowsOut: 340 },
+    ]);
+    expect(record.rowsIn).toBe(1200);
+    expect(record.rowsOut).toBe(340);
+    expect(record.persistError).toBeNull();
+
+    // The log line and the table row are the same queryable document.
+    expect(lines).toHaveLength(1);
+    expect(JSON.parse(lines[0]!)).toEqual(record);
+    const table = (await readFile(tablePath, "utf8")).trim().split("\n");
+    expect(table).toHaveLength(1);
+    expect(JSON.parse(table[0]!)).toEqual(record);
+  });
+
+  test("successful run reports ok status, generated id, and ISO bounds", async () => {
+    const record = await runJobStages({
+      logLine: false,
+      stages: [
+        {
+          name: "read_postgres",
+          run: (c) => {
+            c.rowsOut = 7;
+          },
+        },
+        {
+          name: "transform",
+          run: (c) => {
+            c.rowsIn = 7;
+            c.rowsOut = 7;
+          },
+        },
+        {
+          name: "write_sheet_jobs",
+          run: (c) => {
+            c.rowsIn = 7;
+            c.rowsOut = 7;
+          },
+        },
+      ],
+    });
+    expect(record.status).toBe("ok");
+    expect(record.lastError).toBeNull();
+    expect(record.executionId).toMatch(/^[0-9a-f]{8}$/);
+    expect(record.rowsIn).toBe(7);
+    expect(record.rowsOut).toBe(7);
+    expect(record.stages.every((s) => s.status === "ok")).toBe(true);
+    expect(Date.parse(record.startedAt)).toBeLessThanOrEqual(Date.parse(record.finishedAt));
+    expect(record.durationMs).toBeGreaterThanOrEqual(0);
+  });
+
+  test("early failure marks downstream stages skipped and still emits the record", async () => {
+    const lines: string[] = [];
+    const record = await runJobStages({
+      logLine: (line) => lines.push(line),
+      stages: [
+        {
+          name: "read_postgres",
+          run: () => {
+            throw new Error("connection refused");
+          },
+        },
+        { name: "transform", run: () => {} },
+        { name: "write_sheet_jobs", run: () => {} },
+      ],
+    });
+    expect(record.status).toBe("error");
+    expect(record.lastError?.stage).toBe("read_postgres");
+    expect(record.stages[1]).toEqual({
+      stage: "transform",
+      status: "skipped",
+      durationMs: null,
+      rowsIn: 0,
+      rowsOut: 0,
+    });
+    expect(record.stages[2]?.status).toBe("skipped");
+    expect(record.rowsIn).toBe(0);
+    expect(record.rowsOut).toBe(0);
+    expect(lines).toHaveLength(1);
+  });
+
+  test("non-Error throws and oversized messages are flattened and capped", async () => {
+    const record = await runJobStages({
+      logLine: false,
+      stages: [
+        {
+          name: "transform",
+          run: () => {
+            throw `line one\nline two   ${"x".repeat(1000)}`;
+          },
+        },
+      ],
+    });
+    expect(record.status).toBe("error");
+    expect(record.lastError?.stage).toBe("transform");
+    expect(record.lastError?.message.includes("\n")).toBe(false);
+    expect(record.lastError?.message.length).toBeLessThanOrEqual(503);
+  });
+
+  test("table append failure is recorded on the record, never thrown", async () => {
+    const dir = await tmp();
+    const blocker = join(dir, "blocker");
+    await writeFile(blocker, "not a directory");
+    const record = await runJobStages({
+      logLine: false,
+      tablePath: join(blocker, "job-runs.jsonl"),
+      stages: [{ name: "read_postgres", run: () => {} }],
+    });
+    expect(record.persistError).not.toBeNull();
+  });
+});
+
+describe("appendJobRunRecord", () => {
+  test("appends records as one JSONL row each, creating parent dirs", async () => {
+    const dir = await tmp();
+    const path = join(dir, "nested", "runs.jsonl");
+    const record = await runJobStages({
+      logLine: false,
+      stages: [{ name: "read_postgres", run: () => {} }],
+    });
+    await appendJobRunRecord(path, record);
+    await appendJobRunRecord(path, { ...record, status: "error" });
+    const lines = (await readFile(path, "utf8")).trim().split("\n");
+    expect(lines).toHaveLength(2);
+    const rows = lines.map((l) => JSON.parse(l) as JobRunRecord);
+    expect(rows[0]?.status).toBe("ok");
+    expect(rows[1]?.status).toBe("error");
+  });
+});

package/src/__tests__/http.test.ts

@@ -111,6 +111,59 @@ describe("fetchWithRetry", () => {
     expect(calls).toBe(1);
   });
 
+  test("a POST Request is not retried after a server or network failure", async () => {
+    for (const networkFailure of [false, true]) {
+      let calls = 0;
+      globalThis.fetch = (async () => {
+        calls++;
+        if (networkFailure) throw new TypeError("fetch failed");
+        return new Response(null, { status: 503 });
+      }) as unknown as typeof fetch;
+      const request = new Request("https://example.com/charge", { method: "POST" });
+      const result = fetchWithRetry(request, undefined, { baseDelayMs: 1 });
+      if (networkFailure) await expect(result).rejects.toThrow("fetch failed");
+      else expect((await result).status).toBe(503);
+      expect(calls).toBe(1);
+    }
+  });
+
+  test("init method overrides the Request method when deciding whether to retry", async () => {
+    let calls = 0;
+    globalThis.fetch = (async () => {
+      calls++;
+      return new Response(null, { status: 503 });
+    }) as unknown as typeof fetch;
+    await fetchWithRetry(
+      new Request("https://example.com"),
+      { method: "POST" },
+      { baseDelayMs: 1 },
+    );
+    expect(calls).toBe(1);
+  });
+
+  test("Request and init signals interrupt retry delays, including with an external signal", async () => {
+    for (const source of ["request", "init"] as const) {
+      const controller = new AbortController();
+      const external = new AbortController();
+      let calls = 0;
+      globalThis.fetch = (async () => {
+        calls++;
+        setTimeout(() => controller.abort(new Error("cancelled")), 5);
+        return new Response(null, { status: 503 });
+      }) as unknown as typeof fetch;
+      const request = new Request("https://example.com", {
+        signal: source === "request" ? controller.signal : undefined,
+      });
+      await expect(
+        fetchWithRetry(request, source === "init" ? { signal: controller.signal } : undefined, {
+          signal: external.signal,
+          baseDelayMs: 1000,
+        }),
+      ).rejects.toThrow("cancelled");
+      expect(calls).toBe(1);
+    }
+  });
+
   test("idempotent: true overrides method-based default, letting a POST retry", async () => {
     let calls = 0;
     globalThis.fetch = (async () => {

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";

package/src/providers/grafana.ts

@@ -1,5 +1,4 @@
 import { makeApiKeyProvider } from "./_api-key.ts";
-import { verifyFetch } from "./_helpers.ts";
 
 // Grafana is self-hosted or Grafana Cloud — we store both the token and the
 // base URL. The secretName for `makeApiKeyProvider` is the token slot; the URL

package/src/stack-manifest.ts

@@ -26,9 +26,9 @@ export const STACK_MANIFEST = Object.freeze({
   schema_version: 1,
   kind: "ashlr-stack-manifest",
   components: Object.freeze([
-    Object.freeze({ id: "core", name: "@ashlr/stack-core", version: "0.3.7", distribution: "npm" }),
-    Object.freeze({ id: "cli", name: "@ashlr/stack", version: "0.3.7", distribution: "npm" }),
-    Object.freeze({ id: "mcp", name: "ashlr-stack-mcp", version: "0.3.7", distribution: "npm" }),
+    Object.freeze({ id: "core", name: "@ashlr/stack-core", version: "0.3.9", distribution: "npm" }),
+    Object.freeze({ id: "cli", name: "@ashlr/stack", version: "0.3.9", distribution: "npm" }),
+    Object.freeze({ id: "mcp", name: "ashlr-stack-mcp", version: "0.3.9", distribution: "npm" }),
     Object.freeze({
       id: "plugin",
       name: "stack",