@ai-dossier/sched weekly downloads statistics

@ai-dossier/sched

Use one portable AI-agent skill across Claude Code, Codex, OpenCode, and MCP-compatible workflows.

@ai-dossier/sched is for engineering teams running parallel coding agents. It is a deterministic scheduler that queues work, manages worker slots, verifies completion, watches PRs, and recovers stalled multi-agent workflows without invoking an LLM itself.

Part of the ai-dossier ecosystem: use @ai-dossier/cli to run workflows, @ai-dossier/worktree-pool for ready worktrees, and the ai-dossier project for the complete platform.

Deterministic scheduler core for dossier batch cycles — queue, worker slots, typed state machines, crash-safe persistence, the dispatch engine (#464: spawning agent processes, verifying their completion against ground truth, mechanizing the stall/escalation ladder), and since #468 the PR watcher + tail work (parked-PR watching, script-based teardown, cheap-tier report dispatch — retiring the fleet pattern of re-dispatching a full-cycle run for the tail), and since #472 **batch failure recovery (attribution, bisect, one bounded fix, eviction, dissolve). The scheduler itself never invokes an LLM** — it spawns the agent process the operator configured and reconciles the durable record (ai-dossier runstate / gh / git) that the spawned run leaves behind.

Design: RFC-0001 *Batch Cycles* (rfcs/0001-batch-cycles.md) §B/C.1/D — the §D state machines are frozen verbatim into the types below. This package is the deterministic replacement for fleet-cycle's LLM-prose supervision, whose named failure — slots sitting idle after a subagent finished — is a scheduling bug this state machine makes impossible to forget.

CLI surface

Consumed through the monorepo CLI (@ai-dossier/cli ≥ 0.19.0):

Every subcommand except stats (without --batch) takes --project (default: owner-repo of the current directory, falling back to the repo basename — fleet-cycle's convention) and --json. stats without --batch reads ~/.dossier/runs.jsonl, a single global file, not the per-project state — it takes --json and --issues only; see "runs.jsonl telemetry" below for the resulting cross-repo caveat (the same issue number in two repos sums together). stats --batch instead takes --project like every other subcommand and reads that project's ~/.dossier/sched//runs/ directory directly, reconstructing costs from the raw dispatch logs rather than runs.jsonl (#564) — see "Batch members (#564)" below.

pause prevents every new agent process, including escalation and same-tier recovery takeovers; it does not terminate agents that are already running. stop --issue is the single-command stop path: it PID-start-safely terminates that issue's live agent, releases its slot, and records a terminal stopped outcome that will not recover or escalate. A slot-mode member still in a live batch (pending, in work, or validated) must instead be stopped through stop --batch — a parked (handed-back/evicted) member can be stopped on its own (#832) — which terminates every agent the batch holds (its own slot plus one per running parallel member, batch:#) and atomically stops the batch and its unfinished members. abandon only records failure and releases the slot; it intentionally does not terminate its process.

Since #507, enqueue additionally reads each candidate issue's live GitHub labels (one gh issue view --json labels call per issue, resolved against the current directory's repo unless --repo is passed) and lands an issue carrying decision-pending / needs-clarification / epic / decomposed as blocked (reason: label:) instead of queued — without spending a slot on an agent that would only rediscover the same block. A failed gh lookup fails open: the issue enqueues normally, with a warning and a label-check-failed journal event.

The dispatch engine (#464)

sched start runs a tick loop (default 60s, --interval or reconcile_interval_ms) where every mechanical supervision decision is code, not remembered prose:

1. Dispatch (AC1) — a runnable unit is spawned as a detached agent process (claude -p --output-format stream-json --verbose --model by default — json buffers the whole session into a single write at exit, which left a 0-byte log for any dispatch killed before a clean exit (#524); opencode fallback; command/prompt/tier-models configurable), prompt on stdin, output appended to runs/.log. Each tier may fully override the command/model/prompt independently via dispatch.tiers. (#527) — a MIXED agent-CLI ladder, not just a different model on the same CLI: a unit can start on opencode for mechanical/mid and be rescued on claude at strong. dispatch.tiers is additive over the top-level command/tier_models/prompt shorthand — any field a tier leaves unset falls back to the shorthand, so an existing config with no tiers resolves exactly as before. The intended arrangement (#680) is cheap open-weights for member implementation and a stronger model for the judgment steps that actually need it. Worked example — opencode/GLM for the implementing tiers, claude/opus kept for strong:…

Description from the npm listing.