@stigmer/server 3.14.0-dev.20260910084630

package/src/temporal/schedule/__tests__/activities.test.ts

@@ -0,0 +1,301 @@
+/**
+ * Pins the tick activities against Go's tick_activities_test.go: the
+ * record-tick revalidation matrix (deleted/disabled/paused decline), the
+ * start-run re-validation collapse to SKIPPED (and its no-ledger-row
+ * deleted arm), phase classification incl. GONE, the idempotent success
+ * reset, and the ONE-closure failure record — increment, threshold latch
+ * (first pause's copy never rewritten), next_fire_at clear, and the
+ * best-effort artifact re-sync exactly at the crossing.
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { create } from "@bufbuild/protobuf";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ScheduleSchema } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import { SqliteStore } from "../../../store/sqlite/store.js";
+import { createScheduleTickActivities } from "../activities.js";
+import type { ScheduleTickActivityDeps } from "../activities.js";
+import { ScheduleTemporalConfig } from "../config.js";
+import {
+  FAILURE_RUN_FAILED,
+  FAILURE_START_FAILED,
+  PHASE_CANCELLED,
+  PHASE_COMPLETED,
+  PHASE_FAILED,
+  PHASE_GONE,
+  PHASE_RUNNING,
+  PHASE_TERMINATED,
+  RECORD_FAILED_RUN_ACTIVITY_NAME,
+  RECORD_SUCCESSFUL_RUN_ACTIVITY_NAME,
+  RECORD_TICK_ACTIVITY_NAME,
+  POLL_EXECUTION_PHASE_ACTIVITY_NAME,
+  RUN_REFUSED,
+  RUN_SKIPPED,
+  RUN_STARTED,
+  START_SCHEDULED_RUN_ACTIVITY_NAME,
+  TICK_FIRED,
+  TICK_SKIPPED_AUTO_PAUSED,
+  TICK_SKIPPED_DELETED,
+  TICK_SKIPPED_DISABLED,
+} from "../names.js";
+import type { RunOutcomeResult } from "../run-starter.js";
+
+const silentLogger = createLogger({ level: "error", pretty: false, write: () => {} });
+const NOMINAL = "2026-08-25T09:30:00Z";
+
+let dir: string;
+let store: SqliteStore;
+
+// Threshold 2 (the conformance execution targets' pin) makes the latch
+// provable in two failures.
+const config = new ScheduleTemporalConfig("schedule_stigmer", 60, 24, 2, 60, true, 5, 20, 1.0, 90);
+
+let peekResult: Date | undefined;
+let peekError: Error | undefined;
+let ensureCalls: string[];
+let startRunOutcome: RunOutcomeResult;
+
+function activities() {
+  const deps: ScheduleTickActivityDeps = {
+    store,
+    config,
+    logger: silentLogger,
+    syncer: {
+      peekNextFireAt: async () => {
+        if (peekError !== undefined) {
+          throw peekError;
+        }
+        return peekResult;
+      },
+      ensureAndRecord: async (schedule) => {
+        ensureCalls.push(schedule.metadata?.id ?? "");
+        return undefined;
+      },
+    },
+    runStarter: { startRun: async () => startRunOutcome },
+  };
+  return createScheduleTickActivities(deps);
+}
+
+function scheduleRow(overrides?: { enabled?: boolean; pausedReason?: string; failures?: number }) {
+  return create(ScheduleSchema, {
+    metadata: { id: "sch_01act", org: "acme", slug: "daily" },
+    spec: {
+      cron: "0 9 * * *",
+      timeZone: "UTC",
+      enabled: overrides?.enabled ?? true,
+      target: { case: "agent", value: { agentRef: { slug: "helper" } } },
+    },
+    status: {
+      pausedReason: overrides?.pausedReason ?? "",
+      consecutiveFailures: overrides?.failures ?? 0,
+    },
+  });
+}
+
+beforeAll(() => {
+  dir = mkdtempSync(path.join(tmpdir(), "tick-activities-test-"));
+  store = SqliteStore.open(path.join(dir, "test.db"));
+});
+
+afterAll(async () => {
+  await store.close();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+beforeEach(async () => {
+  peekResult = undefined;
+  peekError = undefined;
+  ensureCalls = [];
+  startRunOutcome = { kind: "started", executionId: "aex_01x", alreadyExisted: false };
+  await store.deleteResource(ApiResourceKind.schedule, "sch_01act");
+  await store.deleteScheduleRunsBySchedule("sch_01act");
+});
+
+describe("recordTick — the revalidation matrix", () => {
+  it("declines a deleted row (orphaned artifact fires are harmless by construction)", async () => {
+    const outcome = await activities()[RECORD_TICK_ACTIVITY_NAME]("sch_01act", NOMINAL);
+    expect(outcome).toBe(TICK_SKIPPED_DELETED);
+  });
+
+  it("declines an owner-disabled row", async () => {
+    await store.saveResource(ApiResourceKind.schedule, "sch_01act", ScheduleSchema, scheduleRow({ enabled: false }));
+    expect(await activities()[RECORD_TICK_ACTIVITY_NAME]("sch_01act", NOMINAL)).toBe(TICK_SKIPPED_DISABLED);
+  });
+
+  it("declines a platform-paused row", async () => {
+    await store.saveResource(ApiResourceKind.schedule, "sch_01act", ScheduleSchema, scheduleRow({ pausedReason: "Paused after 2..." }));
+    expect(await activities()[RECORD_TICK_ACTIVITY_NAME]("sch_01act", NOMINAL)).toBe(TICK_SKIPPED_AUTO_PAUSED);
+  });
+
+  it("fires a live row: stamps last_fire_at = NOMINAL and refreshes next_fire_at", async () => {
+    await store.saveResource(ApiResourceKind.schedule, "sch_01act", ScheduleSchema, scheduleRow());
+    peekResult = new Date("2026-08-26T09:30:00Z");
+    expect(await activities()[RECORD_TICK_ACTIVITY_NAME]("sch_01act", NOMINAL)).toBe(TICK_FIRED);
+
+    const row = await store.getResource(ApiResourceKind.schedule, "sch_01act", ScheduleSchema);
+    expect(row.status?.lastFireAt?.seconds).toBe(BigInt(Date.parse(NOMINAL) / 1000));
+    expect(row.status?.nextFireAt?.seconds).toBe(BigInt(Date.parse("2026-08-26T09:30:00Z") / 1000));
+    expect(row.status?.audit?.statusAudit?.event).toBe("updated");
+  });
+
+  it("a failed next-fire refresh never blocks recording the fire", async () => {
+    await store.saveResource(ApiResourceKind.schedule, "sch_01act", ScheduleSchema, scheduleRow());
+    peekError = new Error("temporal is away");
+    expect(await activities()[RECORD_TICK_ACTIVITY_NAME]("sch_01act", NOMINAL)).toBe(TICK_FIRED);
+    const row = await store.getResource(ApiResourceKind.schedule, "sch_01act", ScheduleSchema);
+    expect(row.status?.lastFireAt).toBeDefined();
+    expect(row.status?.nextFireAt).toBeUndefined();
+  });
+});
+
+describe("startScheduledRun — re-validation and the ledger", () => {
+  it("collapses a row disabled between record and start into SKIPPED, with a ledger row", async () => {
+    await store.saveResource(ApiResourceKind.schedule, "sch_01act", ScheduleSchema, scheduleRow({ enabled: false }));
+    const result = await activities()[START_SCHEDULED_RUN_ACTIVITY_NAME]("sch_01act", NOMINAL);
+    expect(result.outcome).toBe(RUN_SKIPPED);
+    // The budget rides the RESULT even on skips (replay-safe timing).
+    expect(result.trackingTimeoutMinutes).toBe(60);
+    const { total } = await store.listScheduleRuns("sch_01act", 0, 10);
+    expect(total).toBe(1); // the skip left its ledger row (row exists)
+  });
+
+  it("the deleted-row skip leaves NO ledger row (the cascade already ran)", async () => {
+    const result = await activities()[START_SCHEDULED_RUN_ACTIVITY_NAME]("sch_01act", NOMINAL);
+    expect(result.outcome).toBe(RUN_SKIPPED);
+    const { total } = await store.listScheduleRuns("sch_01act", 0, 10);
+    expect(total).toBe(0);
+  });
+
+  it("a started run writes the non-terminal cron ledger row", async () => {
+    await store.saveResource(ApiResourceKind.schedule, "sch_01act", ScheduleSchema, scheduleRow());
+    const result = await activities()[START_SCHEDULED_RUN_ACTIVITY_NAME]("sch_01act", NOMINAL);
+    expect(result.outcome).toBe(RUN_STARTED);
+    expect(result.executionId).toBe("aex_01x");
+    const { runs } = await store.listScheduleRuns("sch_01act", 0, 10);
+    expect(runs).toHaveLength(1);
+    expect(runs[0]?.outcome).toBe("started");
+    expect(runs[0]?.origin).toBe("cron");
+    expect(runs[0]?.completedAt).toBe("");
+  });
+
+  it("a refused run writes a terminal ledger row with the 'run refused: ' prefix", async () => {
+    await store.saveResource(ApiResourceKind.schedule, "sch_01act", ScheduleSchema, scheduleRow());
+    startRunOutcome = { kind: "refused", reason: "gate said no" };
+    const result = await activities()[START_SCHEDULED_RUN_ACTIVITY_NAME]("sch_01act", NOMINAL);
+    expect(result.outcome).toBe(RUN_REFUSED);
+    expect(result.failureReason).toBe("run refused: gate said no");
+    const { runs } = await store.listScheduleRuns("sch_01act", 0, 10);
+    expect(runs[0]?.outcome).toBe("refused");
+    expect(runs[0]?.reason).toBe("run refused: gate said no");
+    expect(runs[0]?.completedAt).not.toBe("");
+  });
+});
+
+describe("pollExecutionPhase — one row read, GONE distinct from RUNNING", () => {
+  it.each([
+    [ExecutionPhase.EXECUTION_COMPLETED, PHASE_COMPLETED],
+    [ExecutionPhase.EXECUTION_CANCELLED, PHASE_CANCELLED],
+    [ExecutionPhase.EXECUTION_TERMINATED, PHASE_TERMINATED],
+    [ExecutionPhase.EXECUTION_FAILED, PHASE_FAILED],
+    [ExecutionPhase.EXECUTION_IN_PROGRESS, PHASE_RUNNING],
+    [ExecutionPhase.EXECUTION_PENDING, PHASE_RUNNING],
+  ])("classifies phase %d as %s", async (phase, want) => {
+    await store.saveResource(
+      ApiResourceKind.agent_execution,
+      "aex_01poll",
+      AgentExecutionSchema,
+      create(AgentExecutionSchema, {
+        metadata: { id: "aex_01poll", org: "acme" },
+        status: { phase },
+      }),
+    );
+    expect(await activities()[POLL_EXECUTION_PHASE_ACTIVITY_NAME]("aex_01poll")).toBe(want);
+  });
+
+  it("a deleted row answers GONE (a deleted run must not brick its schedule)", async () => {
+    expect(await activities()[POLL_EXECUTION_PHASE_ACTIVITY_NAME]("aex_missing")).toBe(PHASE_GONE);
+  });
+});
+
+describe("recordSuccessfulRun — the absorbing zero", () => {
+  it("resets the streak, marks the cron ledger verdict, and is idempotent", async () => {
+    await store.saveResource(ApiResourceKind.schedule, "sch_01act", ScheduleSchema, scheduleRow({ failures: 1 }));
+    await activities()[START_SCHEDULED_RUN_ACTIVITY_NAME]("sch_01act", NOMINAL);
+
+    await activities()[RECORD_SUCCESSFUL_RUN_ACTIVITY_NAME]("sch_01act");
+    let row = await store.getResource(ApiResourceKind.schedule, "sch_01act", ScheduleSchema);
+    expect(row.status?.consecutiveFailures).toBe(0);
+    const { runs } = await store.listScheduleRuns("sch_01act", 0, 10);
+    expect(runs[0]?.outcome).toBe("completed");
+
+    // Retried freely: a second call is harmless.
+    await activities()[RECORD_SUCCESSFUL_RUN_ACTIVITY_NAME]("sch_01act");
+    row = await store.getResource(ApiResourceKind.schedule, "sch_01act", ScheduleSchema);
+    expect(row.status?.consecutiveFailures).toBe(0);
+  });
+
+  it("a deleted row is a silent no-op", async () => {
+    await expect(activities()[RECORD_SUCCESSFUL_RUN_ACTIVITY_NAME]("sch_01act")).resolves.toBeUndefined();
+  });
+});
+
+describe("recordFailedRun — the one-closure verdict", () => {
+  it("increments below the threshold without latching", async () => {
+    await store.saveResource(ApiResourceKind.schedule, "sch_01act", ScheduleSchema, scheduleRow());
+    const recorded = await activities()[RECORD_FAILED_RUN_ACTIVITY_NAME]("sch_01act", "run aex_01x ended failed", FAILURE_RUN_FAILED);
+    expect(recorded).toEqual({ consecutiveFailures: 1, paused: false });
+    expect(ensureCalls).toEqual([]); // no crossing → no re-sync
+  });
+
+  it("latches the pause with the byte-pinned copy exactly at the crossing and clears next_fire_at", async () => {
+    await store.saveResource(ApiResourceKind.schedule, "sch_01act", ScheduleSchema, scheduleRow({ failures: 1 }));
+    const recorded = await activities()[RECORD_FAILED_RUN_ACTIVITY_NAME]("sch_01act", "run aex_01x ended failed", FAILURE_RUN_FAILED);
+    expect(recorded).toEqual({ consecutiveFailures: 2, paused: true });
+
+    const row = await store.getResource(ApiResourceKind.schedule, "sch_01act", ScheduleSchema);
+    expect(row.status?.pausedReason).toBe(
+      "Paused after 2 consecutive failed runs. Last failure: run aex_01x ended failed",
+    );
+    expect(row.status?.nextFireAt).toBeUndefined();
+    // The crossing triggers the best-effort immediate artifact re-sync.
+    expect(ensureCalls).toEqual(["sch_01act"]);
+  });
+
+  it("never rewrites the first pause's copy past the threshold", async () => {
+    await store.saveResource(
+      ApiResourceKind.schedule,
+      "sch_01act",
+      ScheduleSchema,
+      scheduleRow({ failures: 2, pausedReason: "Paused after 2 consecutive failed runs. Last failure: original" }),
+    );
+    const recorded = await activities()[RECORD_FAILED_RUN_ACTIVITY_NAME]("sch_01act", "a newer failure", FAILURE_RUN_FAILED);
+    expect(recorded).toEqual({ consecutiveFailures: 3, paused: true });
+    const row = await store.getResource(ApiResourceKind.schedule, "sch_01act", ScheduleSchema);
+    expect(row.status?.pausedReason).toContain("original");
+    expect(ensureCalls).toEqual([]); // already latched — not a crossing
+  });
+
+  it("a deleted row answers the zero post-image (deleting must never resurrect)", async () => {
+    const recorded = await activities()[RECORD_FAILED_RUN_ACTIVITY_NAME]("sch_01act", "x", FAILURE_START_FAILED);
+    expect(recorded).toEqual({ consecutiveFailures: 0, paused: false });
+  });
+
+  it("marks the cron ledger verdict for tracked failures but not for START_FAILED", async () => {
+    await store.saveResource(ApiResourceKind.schedule, "sch_01act", ScheduleSchema, scheduleRow());
+    await activities()[START_SCHEDULED_RUN_ACTIVITY_NAME]("sch_01act", NOMINAL);
+
+    await activities()[RECORD_FAILED_RUN_ACTIVITY_NAME]("sch_01act", "run aex_01x ended failed", FAILURE_RUN_FAILED);
+    const { runs } = await store.listScheduleRuns("sch_01act", 0, 10);
+    expect(runs[0]?.outcome).toBe("failed");
+    expect(runs[0]?.reason).toBe("run aex_01x ended failed");
+  });
+});

package/src/temporal/schedule/__tests__/artifact.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Pins the artifact mapping against Go's artifact_test.go: the id
+ * contract, the drift-fingerprint note, the two-lever paused derivation,
+ * and the baked policy (SKIP overlap, PauseOnFailure false, one action
+ * arg) — every value here is cross-repo wire contract.
+ */
+import { create } from "@bufbuild/protobuf";
+import { ScheduleOverlapPolicy } from "@temporalio/client";
+import type { ScheduleDescription } from "@temporalio/client";
+import { describe, expect, it } from "vitest";
+
+import { ScheduleSchema } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+
+import { ScheduleArtifact, desiredPaused, note } from "../artifact.js";
+import { ScheduleTemporalConfig } from "../config.js";
+import { artifactId, resourceIdOf } from "../names.js";
+
+const config = new ScheduleTemporalConfig(
+  "schedule_stigmer",
+  60,
+  24,
+  5,
+  60,
+  true,
+  5,
+  20,
+  1.0,
+  90,
+);
+
+function schedule(overrides?: {
+  enabled?: boolean;
+  pausedReason?: string;
+  cron?: string;
+  timeZone?: string;
+}) {
+  return create(ScheduleSchema, {
+    metadata: { id: "sch_01test", org: "acme", slug: "daily" },
+    spec: {
+      cron: overrides?.cron ?? "0 9 * * *",
+      timeZone: overrides?.timeZone ?? "Asia/Kolkata",
+      enabled: overrides?.enabled ?? true,
+      target: { case: "agent", value: { agentRef: { slug: "helper" } } },
+    },
+    status: { pausedReason: overrides?.pausedReason ?? "" },
+  });
+}
+
+describe("artifact identity", () => {
+  it("prefixes the resource id with schedule/tick/", () => {
+    expect(artifactId("sch_01test")).toBe("schedule/tick/sch_01test");
+  });
+
+  it("resourceIdOf inverts artifactId", () => {
+    expect(resourceIdOf("schedule/tick/sch_01test")).toBe("sch_01test");
+  });
+});
+
+describe("note — the drift fingerprint", () => {
+  it("renders cron=<cron> tz=<tz> byte-for-byte", () => {
+    expect(note(schedule())).toBe("cron=0 9 * * * tz=Asia/Kolkata");
+  });
+});
+
+describe("desiredPaused — two levers, one artifact state", () => {
+  it("false when enabled and unlatched", () => {
+    expect(desiredPaused(schedule())).toBe(false);
+  });
+  it("true when owner-disabled", () => {
+    expect(desiredPaused(schedule({ enabled: false }))).toBe(true);
+  });
+  it("true when platform-paused", () => {
+    expect(desiredPaused(schedule({ pausedReason: "Paused after 5..." }))).toBe(true);
+  });
+});
+
+describe("createOptions — the baked policy", () => {
+  const artifact = new ScheduleArtifact(config);
+  const options = artifact.createOptions(schedule());
+
+  it("pins the artifact id and cron spec", () => {
+    expect(options.scheduleId).toBe("schedule/tick/sch_01test");
+    expect(options.spec.cronExpressions).toEqual(["0 9 * * *"]);
+    expect(options.spec.timezone).toBe("Asia/Kolkata");
+  });
+
+  it("pins overlap SKIP, catchup window, and PauseOnFailure=false", () => {
+    expect(options.policies?.overlap).toBe(ScheduleOverlapPolicy.SKIP);
+    expect(options.policies?.catchupWindow).toBe(60 * 60_000);
+    expect(options.policies?.pauseOnFailure).toBe(false);
+  });
+
+  it("bakes the action: workflow id = artifact id, type schedule/tick, ONE arg, own queue, 24h backstop", () => {
+    expect(options.action.type).toBe("startWorkflow");
+    expect(options.action.workflowId).toBe("schedule/tick/sch_01test");
+    expect(options.action.workflowType).toBe("schedule/tick");
+    expect(options.action.args).toEqual(["sch_01test"]);
+    expect(options.action.taskQueue).toBe("schedule_stigmer");
+    expect(options.action.workflowRunTimeout).toBe(24 * 3_600_000);
+    // No retry policy: a failed tick is a missed fire, not a hot loop.
+    expect(options.action.retry).toBeUndefined();
+  });
+
+  it("derives the initial paused state and the note", () => {
+    expect(options.state?.paused).toBe(false);
+    expect(options.state?.note).toBe("cron=0 9 * * * tz=Asia/Kolkata");
+    expect(artifact.createOptions(schedule({ enabled: false })).state?.paused).toBe(true);
+  });
+});
+
+describe("applyDesiredState — the update half of ensure", () => {
+  const artifact = new ScheduleArtifact(config);
+
+  it("rewrites spec, action, policy, and state to the complete desired state", () => {
+    // A partial double narrowed through unknown — the target type stays
+    // named, so a ScheduleDescription shape change flags this test.
+    const previous = {
+      state: { paused: true, note: "cron=old tz=old", remainingActions: 0 },
+      info: {},
+    } as unknown as ScheduleDescription;
+    const update = artifact.applyDesiredState(
+      previous,
+      schedule({ cron: "30 8 * * *", timeZone: "UTC" }),
+    );
+    expect(update.spec?.cronExpressions).toEqual(["30 8 * * *"]);
+    expect(update.spec?.timezone).toBe("UTC");
+    expect(update.action.workflowType).toBe("schedule/tick");
+    expect(update.policies?.overlap).toBe(ScheduleOverlapPolicy.SKIP);
+    // The SDK's ScheduleUpdateOptions types `state` through an Omit over an
+    // optional union; narrow for the assertions.
+    const state = update.state as { paused: boolean; note: string };
+    expect(state.paused).toBe(false);
+    expect(state.note).toBe("cron=30 8 * * * tz=UTC");
+  });
+
+  it("preserves unrelated previous state fields (Go mutates desc.Schedule.State in place)", () => {
+    const previous = {
+      state: { paused: false, note: "x", remainingActions: 7 },
+      info: {},
+    } as unknown as ScheduleDescription;
+    const update = artifact.applyDesiredState(previous, schedule());
+    expect((update.state as { remainingActions?: number }).remainingActions).toBe(7);
+  });
+});

package/src/temporal/schedule/__tests__/config.test.ts

@@ -0,0 +1,137 @@
+/**
+ * Pins the config clamps and env parsing against Go's config.go: the
+ * tracking-budget ceiling (one hour inside the run timeout), the
+ * threshold and retention floors, and Go's strict strconv parsing
+ * (malformed values keep the default, never NaN).
+ */
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+
+import { ScheduleTemporalConfig, newScheduleConfigFromEnv } from "../config.js";
+
+const ENV_KEYS = [
+  "TEMPORAL_SCHEDULE_STIGMER_TASK_QUEUE",
+  "STIGMER_SCHEDULES_CATCHUP_WINDOW_MINUTES",
+  "STIGMER_SCHEDULES_TICK_RUN_TIMEOUT_HOURS",
+  "STIGMER_SCHEDULES_MAX_CONSECUTIVE_FAILURES",
+  "STIGMER_SCHEDULES_RUN_TRACKING_TIMEOUT_MINUTES",
+  "STIGMER_SCHEDULES_RECONCILIATION_ENABLED",
+  "STIGMER_SCHEDULES_RECONCILIATION_INTERVAL_MINUTES",
+  "STIGMER_SCHEDULES_EXECUTION_PROFILE_MAX_TOOL_ROUNDS",
+  "STIGMER_SCHEDULES_EXECUTION_PROFILE_MAX_COST_USD",
+  "STIGMER_SCHEDULES_RUN_HISTORY_RETENTION_DAYS",
+];
+
+// Snapshot-and-restore rather than delete-and-hope: the invoking shell may
+// legitimately carry STIGMER_SCHEDULES_* values, and a test must neither
+// fail on them nor destroy them for the rest of the worker process.
+const saved = new Map<string, string | undefined>();
+
+beforeAll(() => {
+  for (const key of ENV_KEYS) {
+    saved.set(key, process.env[key]);
+  }
+});
+
+beforeEach(() => {
+  for (const key of ENV_KEYS) {
+    delete process.env[key];
+  }
+});
+
+afterAll(() => {
+  for (const [key, value] of saved) {
+    if (value === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+});
+
+function config(overrides: Partial<Record<"timeout" | "tracking" | "threshold" | "retention", number>>) {
+  return new ScheduleTemporalConfig(
+    "schedule_stigmer",
+    60,
+    overrides.timeout ?? 24,
+    overrides.threshold ?? 5,
+    overrides.tracking ?? 60,
+    true,
+    5,
+    20,
+    1.0,
+    overrides.retention ?? 90,
+  );
+}
+
+describe("defaults from an empty environment", () => {
+  it("loads the documented defaults", () => {
+    const c = newScheduleConfigFromEnv();
+    expect(c.stigmerQueue).toBe("schedule_stigmer");
+    expect(c.catchupWindowMinutes).toBe(60);
+    expect(c.tickRunTimeoutHours).toBe(24);
+    expect(c.maxConsecutiveFailures).toBe(5);
+    expect(c.runTrackingTimeoutMinutes).toBe(60);
+    expect(c.reconciliationEnabled).toBe(true);
+    expect(c.reconciliationIntervalMinutes).toBe(5);
+    expect(c.executionProfileMaxToolRounds).toBe(20);
+    expect(c.executionProfileMaxCostUsd).toBe(1.0);
+    expect(c.runHistoryRetentionDays).toBe(90);
+  });
+});
+
+describe("env parsing — Go strconv parity", () => {
+  it("reads well-formed overrides", () => {
+    process.env.STIGMER_SCHEDULES_MAX_CONSECUTIVE_FAILURES = "2";
+    process.env.STIGMER_SCHEDULES_RECONCILIATION_ENABLED = "false";
+    process.env.STIGMER_SCHEDULES_EXECUTION_PROFILE_MAX_COST_USD = "0.5";
+    const c = newScheduleConfigFromEnv();
+    expect(c.maxConsecutiveFailures).toBe(2);
+    expect(c.reconciliationEnabled).toBe(false);
+    expect(c.executionProfileMaxCostUsd).toBe(0.5);
+  });
+
+  it("keeps the default on a malformed int (Go Atoi failure)", () => {
+    process.env.STIGMER_SCHEDULES_MAX_CONSECUTIVE_FAILURES = "two";
+    expect(newScheduleConfigFromEnv().maxConsecutiveFailures).toBe(5);
+  });
+
+  it("keeps the default on a non-ParseBool token (Go ParseBool failure)", () => {
+    process.env.STIGMER_SCHEDULES_RECONCILIATION_ENABLED = "no";
+    expect(newScheduleConfigFromEnv().reconciliationEnabled).toBe(true);
+  });
+});
+
+describe("resolvedRunTrackingTimeoutMinutes — the cloud edition's exact clamp", () => {
+  it("passes an in-range budget through", () => {
+    expect(config({}).resolvedRunTrackingTimeoutMinutes()).toBe(60);
+  });
+  it("caps at one hour inside the baked run timeout", () => {
+    expect(config({ timeout: 2, tracking: 600 }).resolvedRunTrackingTimeoutMinutes()).toBe(60);
+  });
+  it("floors at 1 minute", () => {
+    expect(config({ tracking: 0 }).resolvedRunTrackingTimeoutMinutes()).toBe(1);
+    expect(config({ tracking: -5 }).resolvedRunTrackingTimeoutMinutes()).toBe(1);
+  });
+  it("a degenerate run timeout still yields a 1-minute ceiling", () => {
+    expect(config({ timeout: 1, tracking: 60 }).resolvedRunTrackingTimeoutMinutes()).toBe(1);
+  });
+});
+
+describe("threshold and retention floors", () => {
+  it("floors the pause threshold at 1 (never pause on configuration)", () => {
+    expect(config({ threshold: 0 }).resolvedMaxConsecutiveFailures()).toBe(1);
+    expect(config({ threshold: -3 }).resolvedMaxConsecutiveFailures()).toBe(1);
+    expect(config({ threshold: 5 }).resolvedMaxConsecutiveFailures()).toBe(5);
+  });
+  it("floors the ledger retention at 1 day (never prune history as it lands)", () => {
+    expect(config({ retention: 0 }).resolvedRunHistoryRetentionDays()).toBe(1);
+    expect(config({ retention: 90 }).resolvedRunHistoryRetentionDays()).toBe(90);
+  });
+
+  it("floors the reconciliation interval at 1 minute (a zero would hot-loop where Go panics)", () => {
+    const zero = new ScheduleTemporalConfig("q", 60, 24, 5, 60, true, 0, 20, 1.0, 90);
+    expect(zero.resolvedReconciliationIntervalMinutes()).toBe(1);
+    const five = new ScheduleTemporalConfig("q", 60, 24, 5, 60, true, 5, 20, 1.0, 90);
+    expect(five.resolvedReconciliationIntervalMinutes()).toBe(5);
+  });
+});