@ai-dossier/sched 0.2.0 → 0.3.0

package/dist/engine.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 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. Since #468 it also owns the
+ * detached-ship tail: the PR watcher, script-based teardown, and the
+ * cheap-tier report dispatch.
+ *
+ * One `tick()` is a full reconcile+refill cycle:
+ *
+ * 1. **Poll** ground truth for every live unit and every parked PR OUTSIDE
+ *    the state lock (gh/git subprocesses are slow; the lock must never wait
+ *    on a network call). Parked PRs poll on their own cadence
+ *    (`pr_poll_interval_ms`, persisted `last_pr_poll_at`) — every 2–3 min.
+ * 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); an exit whose milestone is
+ *      the ship phase's `awaiting-merge` (with `pr=`) is a VERIFIED park:
+ *      entry → parked, slot released (a parked unit holds no slot — AC5)
+ *    - `parked` entries: the watcher applies the PR truth — merge accepted
+ *      only when state MERGED AND mergedAt non-null AND the issue is closed
+ *      (AC1) → shipped (gating on MERGE, never the park — AC4);
+ *      CONFLICTING / closed-unmerged / auto-merge-blocked → failed + transitive
+ *      dependents blocked (AC3)
+ *    - failures block their TRANSITIVE dependents (AC4)
+ *    - report agents are dispatched for merged units whose teardown is
+ *      already recorded (before queue refill — cheap reports don't queue
+ *      behind long runs)
+ *    - **Refill** in the SAME lock pass: `computeAssignments` fills every
+ *      freed slot — a runnable unit never waits while a slot is idle (AC5)
+ * 3. **Teardown** (outside the lock — pool/git subprocesses are slow): for
+ *    every freshly-merged unit, recover the setup milestone's worktree info
+ *    and run pool return / worktree remove, VERIFIED before claimed
+ *    (`cleanup=failed-<step>` on mismatch, AC2). Results land in a second
+ *    short lock pass together with the report dispatch.
+ *
+ * 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 { ExecFn } from './project';
+import { type SchedConfig } from './types';
+export interface EngineDeps {
+    store: SchedStore;
+    journal: Journal;
+    groundTruth: GroundTruth;
+    spawnDeps: SpawnDeps;
+    now: () => Date;
+    /** Repo working directory — cwd for teardown subprocesses (#468). */
+    repoDir: string;
+    /** Exec for teardown scripts (#468); injectable so tests never touch git/npx. */
+    teardownExec: ExecFn;
+}
+/** 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 whose agent exited having parked its PR (#468) — now watcher-owned. */
+    parked: string[];
+    /** Parked units whose merge was accepted this tick (#468). */
+    mergeAccepted: string[];
+    /** Report agents dispatched for merged units this tick (#468). */
+    reportDispatched: string[];
+    /** Merged units whose report could not dispatch — waiting for a free slot (#468). */
+    reportWaiting: number;
+    /** Units whose teardown was verified this tick (#468). */
+    teardownDone: string[];
+    /** Units whose teardown failed a step this tick (#468) — degradation, not unit failure. */
+    teardownFailed: string[];
+    /** Units redispatched one tier stronger (stall or unverified exit). */
+    redispatched: string[];
+    /**
+     * Units that hit a failure rail. Full-cycle units end `failed`; MERGED
+     * units also land here on merged-aware REPORT failures
+     * (`report-escalation-cap` / report spawn-error), where the unit actually
+     * completes (`done`, reason recorded) — the report failed, not the work.
+     */
+    failed: string[];
+    /** Issues blocked transitively by a failure. */
+    blocked: number[];
+}
+/**
+ * One full reconcile+refill cycle. Ground truth is polled WITHOUT the lock
+ * (live units AND parked PRs); every state mutation happens under
+ * `store.withLock`; refills are computed in the same pass, so a freed slot
+ * is reused within this tick (AC5). Teardown subprocesses run between two
+ * short lock passes — a slow `npx`/`git` call never holds the lock.
+ */
+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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,EAQL,KAAK,SAAS,EAIf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,WAAW,EAMjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAe,KAAK,OAAO,EAAa,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAIxC,OAAO,EAKL,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;IAChB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,YAAY,EAAE,MAAM,CAAC;CACtB;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,gFAAgF;IAChF,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,8DAA8D;IAC9D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,kEAAkE;IAClE,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,qFAAqF;IACrF,aAAa,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,2FAA2F;IAC3F,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,uEAAuE;IACvE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB;;;;;OAKG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,gDAAgD;IAChD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AA06BD;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,UAAU,CAyCtE;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"}