@ai-dossier/sched 0.2.0 → 0.2.1

package/dist/dispatch.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Agent dispatch machinery (#464, AC1 — "a runnable queue unit is dispatched
+ * as a spawned agent process … with `--model` per its tier; pid + phase +
+ * last-progress timestamp tracked in state.json"; RFC-0001 §C.1 "spawns agent
+ * processes via the existing `run` machinery").
+ *
+ * The command is a template (default `claude -p --output-format json --model
+ * {model}` — the same headless invocation `ai-dossier run` builds in
+ * cli/src/helpers.ts) with `{model}`/`{issue}` placeholders; the prompt
+ * travels on stdin exactly like the run machinery's headless path. Children
+ * spawn DETACHED and unref'd: an agent must survive a sched crash (RFC F.10 —
+ * restart reconciles by pid, it never owns the agent's lifetime).
+ *
+ * All process I/O is injectable (`SpawnDeps`) so tests spawn fake agents, and
+ * the package itself never invokes an LLM — it spawns a process the operator
+ * configured.
+ */
+import { type ModelTier, type SchedConfig } from './types';
+/** Default tier → model mapping (claude aliases; override in config.json). */
+export declare const DEFAULT_TIER_MODELS: Readonly<Record<ModelTier, string>>;
+/** Default headless agent command template (claude, the run machinery's first choice). */
+export declare const DEFAULT_DISPATCH_COMMAND: readonly string[];
+/** opencode equivalent (the run machinery's second agent, #459). */
+export declare const OPENCODE_DISPATCH_COMMAND: readonly string[];
+/** Default prompt sent on the child's stdin. */
+export declare const DEFAULT_PROMPT_TEMPLATE: string;
+/** Fully-resolved dispatch settings the engine runs with. */
+export interface ResolvedDispatch {
+    /** Command template with `{model}`/`{issue}` placeholders. */
+    command: string[];
+    /** Prompt template with `{issue}` placeholder. */
+    prompt: string;
+    /** Model per tier; null means "no model flag" (the command's `--model {model}` pair drops). */
+    tierModels: Record<ModelTier, string | null>;
+    stallTimeoutMs: number;
+    reconcileIntervalMs: number;
+}
+/** Resolve engine dispatch settings from the (possibly sparse) config. */
+export declare function resolveDispatch(config: SchedConfig): ResolvedDispatch;
+/**
+ * Build the concrete agent argv for one dispatch: substitute `{issue}` and
+ * `{model}`. When the tier's model is null, the `{model}` item AND its
+ * immediately-preceding flag (e.g. `--model`) drop together — a command never
+ * carries a flag whose value is missing.
+ */
+export declare function buildAgentCommand(template: readonly string[], tier: ModelTier, issue: number, tierModels: Readonly<Record<ModelTier, string | null>>): string[];
+/** Build the child's stdin prompt for one dispatch. */
+export declare function buildPrompt(template: string, issue: number): string;
+/** One tier stronger on the ladder, or null at the top (RFC-0001 §C.1). */
+export declare function escalateTier(tier: ModelTier): ModelTier | null;
+export interface SpawnDeps {
+    /**
+     * Spawn a detached agent process and return its pid. `logFile` receives the
+     * child's combined stdout/stderr (agents outlive sched, so their output
+     * cannot stay in this process's pipes). Throws synchronously when the
+     * process cannot be spawned (missing binary, unwritable log dir).
+     */
+    spawn(cmd: string[], prompt: string, logFile: string): number;
+    /**
+     * Signal a pid; returns false when it was already dead (or not ours).
+     * `expectedStart` (the persisted `/proc` start-time) enables the pid-reuse
+     * guard: a pid whose start-time no longer matches was reused by an
+     * unrelated process and is never signalled.
+     */
+    kill(pid: number, expectedStart?: number): boolean;
+    /**
+     * Whether a pid is alive (best-effort). `expectedStart` applies the same
+     * pid-reuse guard as `kill`.
+     */
+    isAlive(pid: number, expectedStart?: number): boolean;
+    /**
+     * `/proc/<pid>/stat` start-time (field 22) of a pid, when the platform
+     * exposes it (Linux); null elsewhere. The engine persists this at spawn so
+     * pid identity survives engine restarts (decision 1, option C).
+     */
+    processStart(pid: number): number | null;
+}
+/** `issue:464` → `issue-464` (filesystem-safe unit ids for log file names). */
+export declare function unitLogName(unit: string): string;
+/** Poll cadence bounds for `sleep`'s stop-check interval (engine loop). */
+export declare const STOP_POLL_MIN_MS = 100;
+export declare const STOP_POLL_MAX_MS = 1000;
+/**
+ * `/proc/<pid>/stat` start-time (field 22, clock ticks since boot) — stable
+ * process identity for the lifetime of the pid, so a recycled pid is
+ * detectable. Null when /proc is unavailable (macOS/Windows) or the process
+ * is gone.
+ */
+export declare function procStartTime(pid: number): number | null;
+/**
+ * Real process I/O: detached spawn with output to a log file, unref'd.
+ *
+ * Pid-reuse guard (decision 1, option C — hybrid): every pid this instance
+ * spawns is recorded with its `/proc` start-time; `kill`/`isAlive` accept the
+ * start-time persisted in state.json and refuse a pid whose current
+ * start-time no longer matches (it was reused by an unrelated process — the
+ * agent we spawned is already dead, so skipping the signal loses nothing).
+ * On platforms without /proc the guard degrades to best-effort, and pids
+ * without a recorded start-time (e.g. from pre-decision state files) stay
+ * best-effort everywhere.
+ */
+export declare function createSpawnDeps(cwd?: string): SpawnDeps;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,WAAW,EAEjB,MAAM,SAAS,CAAC;AAEjB,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAInE,CAAC;AAEF,0FAA0F;AAC1F,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAOrD,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAOtD,CAAC;AAEF,gDAAgD;AAChD,eAAO,MAAM,uBAAuB,QAKwB,CAAC;AAE7D,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,+FAA+F;IAC/F,UAAU,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,gBAAgB,CAcrE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,GACrD,MAAM,EAAE,CAgBV;AAED,uDAAuD;AACvD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI,CAE9D;AAID,MAAM,WAAW,SAAS;IACxB;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9D;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACnD;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACtD;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAC1C;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAcxD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAyEvD"}

package/dist/dispatch.js

@@ -0,0 +1,262 @@
+"use strict";
+/**
+ * Agent dispatch machinery (#464, AC1 — "a runnable queue unit is dispatched
+ * as a spawned agent process … with `--model` per its tier; pid + phase +
+ * last-progress timestamp tracked in state.json"; RFC-0001 §C.1 "spawns agent
+ * processes via the existing `run` machinery").
+ *
+ * The command is a template (default `claude -p --output-format json --model
+ * {model}` — the same headless invocation `ai-dossier run` builds in
+ * cli/src/helpers.ts) with `{model}`/`{issue}` placeholders; the prompt
+ * travels on stdin exactly like the run machinery's headless path. Children
+ * spawn DETACHED and unref'd: an agent must survive a sched crash (RFC F.10 —
+ * restart reconciles by pid, it never owns the agent's lifetime).
+ *
+ * All process I/O is injectable (`SpawnDeps`) so tests spawn fake agents, and
+ * the package itself never invokes an LLM — it spawns a process the operator
+ * configured.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STOP_POLL_MAX_MS = exports.STOP_POLL_MIN_MS = exports.DEFAULT_PROMPT_TEMPLATE = exports.OPENCODE_DISPATCH_COMMAND = exports.DEFAULT_DISPATCH_COMMAND = exports.DEFAULT_TIER_MODELS = void 0;
+exports.resolveDispatch = resolveDispatch;
+exports.buildAgentCommand = buildAgentCommand;
+exports.buildPrompt = buildPrompt;
+exports.escalateTier = escalateTier;
+exports.unitLogName = unitLogName;
+exports.procStartTime = procStartTime;
+exports.createSpawnDeps = createSpawnDeps;
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const project_1 = require("./project");
+const types_1 = require("./types");
+/** Default tier → model mapping (claude aliases; override in config.json). */
+exports.DEFAULT_TIER_MODELS = {
+    mechanical: 'haiku',
+    mid: 'sonnet',
+    strong: 'opus',
+};
+/** Default headless agent command template (claude, the run machinery's first choice). */
+exports.DEFAULT_DISPATCH_COMMAND = [
+    'claude',
+    '-p',
+    '--output-format',
+    'json',
+    '--model',
+    '{model}',
+];
+/** opencode equivalent (the run machinery's second agent, #459). */
+exports.OPENCODE_DISPATCH_COMMAND = [
+    'opencode',
+    'run',
+    '--format',
+    'json',
+    '--model',
+    '{model}',
+];
+/** Default prompt sent on the child's stdin. */
+exports.DEFAULT_PROMPT_TEMPLATE = 'Run the full-cycle-issue workflow for GitHub issue #{issue} in this repository.\n\n' +
+    'Begin by fetching the workflow: ai-dossier run imboard-ai/git/full-cycle-issue --pull\n\n' +
+    'Then execute it end-to-end for issue #{issue}, following every phase ' +
+    '(gate, setup, plan, implement, review, ship, report) without asking questions, ' +
+    'until the final report milestone is posted on the issue.';
+/** Resolve engine dispatch settings from the (possibly sparse) config. */
+function resolveDispatch(config) {
+    const dispatch = config.dispatch ?? {};
+    const tierModels = {
+        mechanical: dispatch.tier_models?.mechanical ?? exports.DEFAULT_TIER_MODELS.mechanical,
+        mid: dispatch.tier_models?.mid ?? exports.DEFAULT_TIER_MODELS.mid,
+        strong: dispatch.tier_models?.strong ?? exports.DEFAULT_TIER_MODELS.strong,
+    };
+    return {
+        command: dispatch.command ?? [...exports.DEFAULT_DISPATCH_COMMAND],
+        prompt: dispatch.prompt ?? exports.DEFAULT_PROMPT_TEMPLATE,
+        tierModels,
+        stallTimeoutMs: config.stall_timeout_ms ?? types_1.DEFAULT_STALL_TIMEOUT_MS,
+        reconcileIntervalMs: config.reconcile_interval_ms ?? types_1.DEFAULT_RECONCILE_INTERVAL_MS,
+    };
+}
+/**
+ * Build the concrete agent argv for one dispatch: substitute `{issue}` and
+ * `{model}`. When the tier's model is null, the `{model}` item AND its
+ * immediately-preceding flag (e.g. `--model`) drop together — a command never
+ * carries a flag whose value is missing.
+ */
+function buildAgentCommand(template, tier, issue, tierModels) {
+    const model = tierModels[tier] ?? null;
+    const argv = [];
+    for (const item of template) {
+        if (item === '{model}') {
+            if (model === null) {
+                // Drop the preceding flag along with the placeholder.
+                if (argv.length > 0 && argv[argv.length - 1].startsWith('--'))
+                    argv.pop();
+                continue;
+            }
+            argv.push(model);
+            continue;
+        }
+        argv.push(item.replaceAll('{issue}', String(issue)));
+    }
+    return argv;
+}
+/** Build the child's stdin prompt for one dispatch. */
+function buildPrompt(template, issue) {
+    return template.replaceAll('{issue}', String(issue));
+}
+/** One tier stronger on the ladder, or null at the top (RFC-0001 §C.1). */
+function escalateTier(tier) {
+    return types_1.TIER_LADDER[tier];
+}
+/** `issue:464` → `issue-464` (filesystem-safe unit ids for log file names). */
+function unitLogName(unit) {
+    return (0, project_1.sanitizeSlug)(unit);
+}
+/** Poll cadence bounds for `sleep`'s stop-check interval (engine loop). */
+exports.STOP_POLL_MIN_MS = 100;
+exports.STOP_POLL_MAX_MS = 1000;
+/**
+ * `/proc/<pid>/stat` start-time (field 22, clock ticks since boot) — stable
+ * process identity for the lifetime of the pid, so a recycled pid is
+ * detectable. Null when /proc is unavailable (macOS/Windows) or the process
+ * is gone.
+ */
+function procStartTime(pid) {
+    try {
+        const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf-8');
+        // comm (field 2) is parenthesized and may contain spaces — everything
+        // after the LAST ')' is fields 3..N, space-separated.
+        const close = stat.lastIndexOf(')');
+        if (close === -1)
+            return null;
+        const fields = stat.slice(close + 2).split(' ');
+        // field 22 (starttime) -> index 19 in the post-comm array (field 3 = index 0)
+        const start = Number.parseInt(fields[19] ?? '', 10);
+        return Number.isInteger(start) && start >= 0 ? start : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Real process I/O: detached spawn with output to a log file, unref'd.
+ *
+ * Pid-reuse guard (decision 1, option C — hybrid): every pid this instance
+ * spawns is recorded with its `/proc` start-time; `kill`/`isAlive` accept the
+ * start-time persisted in state.json and refuse a pid whose current
+ * start-time no longer matches (it was reused by an unrelated process — the
+ * agent we spawned is already dead, so skipping the signal loses nothing).
+ * On platforms without /proc the guard degrades to best-effort, and pids
+ * without a recorded start-time (e.g. from pre-decision state files) stay
+ * best-effort everywhere.
+ */
+function createSpawnDeps(cwd) {
+    /** Pids spawned by THIS instance -> their /proc start-time (Linux). */
+    const spawnedStarts = new Map();
+    /** True when `pid` plausibly still names the process we recorded. */
+    function matchesRecordedStart(pid, expectedStart) {
+        const expected = expectedStart ?? spawnedStarts.get(pid);
+        if (expected === undefined)
+            return true; // no recorded identity — best-effort
+        const current = procStartTime(pid);
+        if (current === null)
+            return true; // /proc unavailable (non-Linux) or a race — best-effort
+        return current === expected;
+    }
+    return {
+        spawn(cmd, prompt, logFile) {
+            fs.mkdirSync(path.dirname(logFile), { recursive: true, mode: 0o700 });
+            const out = fs.openSync(logFile, 'a', 0o600);
+            try {
+                const child = (0, node_child_process_1.spawn)(cmd[0], cmd.slice(1), {
+                    ...(cwd ? { cwd } : {}),
+                    detached: true,
+                    stdio: ['pipe', out, out],
+                });
+                // Spawn failures surface synchronously via the pid check below; the
+                // async 'error' event must never crash the engine (ENOENT), and an
+                // agent exiting before reading stdin must never crash it either (EPIPE).
+                child.on('error', (err) => {
+                    process.stderr.write(`⚠ sched: spawn '${cmd[0]}' failed: ${err.message}\n`);
+                });
+                if (child.stdin !== null) {
+                    child.stdin.on('error', () => { });
+                    child.stdin.write(prompt);
+                    child.stdin.end();
+                }
+                child.unref();
+                if (child.pid === undefined) {
+                    throw new Error(`failed to spawn '${cmd[0]}' — is it on PATH? (command: ${cmd.join(' ')})`);
+                }
+                const start = procStartTime(child.pid);
+                if (start !== null)
+                    spawnedStarts.set(child.pid, start);
+                return child.pid;
+            }
+            finally {
+                // The child holds its own dups of the fd; the parent's copy must close.
+                fs.closeSync(out);
+            }
+        },
+        kill(pid, expectedStart) {
+            if (!matchesRecordedStart(pid, expectedStart)) {
+                spawnedStarts.delete(pid);
+                return false; // reused pid — the agent we spawned is already gone
+            }
+            try {
+                process.kill(pid, 'SIGTERM');
+                return true;
+            }
+            catch {
+                spawnedStarts.delete(pid);
+                return false;
+            }
+        },
+        isAlive(pid, expectedStart) {
+            try {
+                process.kill(pid, 0);
+                return matchesRecordedStart(pid, expectedStart);
+            }
+            catch (err) {
+                return err.code === 'EPERM';
+            }
+        },
+        processStart(pid) {
+            return procStartTime(pid);
+        },
+    };
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"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"}

package/dist/engine.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The scheduler engine (#464): dispatch, completion verification, and the
+ * stall/escalation ladder (RFC-0001 §C.1) — the deterministic organs that
+ * replace fleet-cycle's LLM supervision.
+ *
+ * One `tick()` is a full reconcile+refill cycle:
+ *
+ * 1. **Poll** ground truth for every live unit OUTSIDE the state lock (gh/git
+ *    subprocesses are slow; the lock must never wait on a network call).
+ * 2. **Apply** under `SchedStore.withLock`:
+ *    - `assigned` slots (crash between assign and spawn) are spawned/re-attached
+ *    - `running` slots: dead pid → exit rail; ground truth says complete →
+ *      external advance (kill the leftover agent, complete); new milestone or
+ *      pushed commit → progress; no progress for `stall_timeout_ms` →
+ *      redispatch one tier stronger (cap 2, then failed)
+ *    - `exited`/`verifying` slots: the agent exited — completion is verified
+ *      against ground truth, never assumed (AC2); unverified exits ride the
+ *      same recovery ladder as stalls
+ *    - `recovering` slots: respawned with the escalated tier (resume rails —
+ *      the agent re-enters via gate and resumes from the milestone trail)
+ *    - failures block their TRANSITIVE dependents (AC4)
+ * 3. **Refill**: `computeAssignments` fills every freed slot in the SAME tick —
+ *    a runnable unit never waits while a slot is idle (AC5).
+ *
+ * Everything that touches the world (processes, GitHub, git) is injected;
+ * the state machine is pure. Only `issue:<n>` units are dispatched — batch
+ * member sequencing is a follow-up (#464 non-goal).
+ */
+import { type SpawnDeps } from './dispatch';
+import { type GroundTruth } from './groundtruth';
+import { type Journal } from './journal';
+import type { SchedStore } from './persist';
+import { type SchedConfig } from './types';
+export interface EngineDeps {
+    store: SchedStore;
+    journal: Journal;
+    groundTruth: GroundTruth;
+    spawnDeps: SpawnDeps;
+    now: () => Date;
+}
+/** What one tick did — surfaced by `sched start`. */
+export interface TickResult {
+    /** Units spawned this tick (first dispatch or redispatch). */
+    spawned: string[];
+    /** Units completed by external ground truth while their agent was still alive. */
+    externalAdvances: string[];
+    /** Units verified complete after an observed exit. */
+    completed: string[];
+    /** Units redispatched one tier stronger (stall or unverified exit). */
+    redispatched: string[];
+    /** Units failed (escalation cap / strongest tier / spawn error). */
+    failed: string[];
+    /** Issues blocked transitively by a failure. */
+    blocked: number[];
+}
+/**
+ * One full reconcile+refill cycle. Ground truth is polled WITHOUT the lock;
+ * every state mutation happens under `store.withLock`; refills are computed in
+ * the same pass, so a freed slot is reused within this tick (AC5).
+ */
+export declare function tick(deps: EngineDeps, config: SchedConfig): TickResult;
+/**
+ * The long-running loop behind `sched start`: tick, sleep, repeat. Returns
+ * when `shouldStop()` says so (the CLI wires SIGINT). A failed tick is
+ * journaled (`tick-failed`, with the error name — `LockTimeoutError` and
+ * `CorruptStateError` demand different operator actions) and reported on
+ * stderr, and the loop continues — one bad tick (e.g. a transient gh
+ * failure) never stops the scheduler.
+ */
+export declare function runLoop(deps: EngineDeps, config: SchedConfig, shouldStop: () => boolean, onTick?: (result: TickResult) => void): Promise<void>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAML,KAAK,SAAS,EAIf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,WAAW,EAAiD,MAAM,eAAe,CAAC;AAChG,OAAO,EAAe,KAAK,OAAO,EAAa,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG5C,OAAO,EAGL,KAAK,WAAW,EAKjB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,WAAW,CAAC;IACzB,SAAS,EAAE,SAAS,CAAC;IACrB,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,UAAU;IACzB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,kFAAkF;IAClF,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,sDAAsD;IACtD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,uEAAuE;IACvE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,oEAAoE;IACpE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,gDAAgD;IAChD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAqkBD;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,UAAU,CAWtE;AAED;;;;;;;GAOG;AACH,wBAAsB,OAAO,CAC3B,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,MAAM,OAAO,EACzB,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,GACpC,OAAO,CAAC,IAAI,CAAC,CAcf"}