@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):

ai-dossier sched enqueue --issues 101,105..109 --deps 100 --tier strong   # flags
ai-dossier sched enqueue --from-manifest batch-prep.json                  # batch-prep output
ai-dossier sched start            # the dispatch engine: spawn, verify, escalate, watch parked PRs (Ctrl-C stops it)
ai-dossier sched start --once     # a single reconcile+refill tick (cron-style)
ai-dossier sched status           # queue (+pr/cleanup), engine lease, slots, batches, blocked/failed; --anchors adds the ledger anchor sweep (#768) plus orphaned anchors no longer in state.batches (#790)
ai-dossier sched pause            # prevent every new agent process; live units keep running
ai-dossier sched resume
ai-dossier sched resume --batch b1  # recheck a gate-inconclusive block (#583), or re-run gate + tail over a batch blocked over landed work (#822)
ai-dossier sched stop --issue 42  # terminate one full-cycle agent (or stop a parked batch member, #832) and record it stopped (no recovery)
ai-dossier sched stop --batch b1  # terminate every batch agent (incl. parallel members) and stop unfinished members
ai-dossier sched abandon --issue 42 --reason "operator abort"
ai-dossier sched abandon --batch b1   # dissolve; every unshipped member — parked and validated ones included — requeues as full-cycle
ai-dossier sched requeue --issue 42   # a PARKED batch member (evicted / handed-back) → full-cycle from its member branch, on the batch profile (#810)
ai-dossier sched attach-pr --batch b1 4270  # record a blocked batch's own MERGED PR by hand (resolves pr-detect-ambiguous, #824)
ai-dossier sched stats --issues 4..9  # per-issue tokens/cost from ~/.dossier/runs.jsonl (#524)
ai-dossier sched stats --batch b1 --project owner-repo  # batch member/tail/report/fix costs from raw dispatch logs (#564)

Every subcommand except stats (without --batch) takes --project <slug> (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 <id> instead takes --project like every other subcommand and reads that project's ~/.dossier/sched/<project>/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 <n> 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 <id> — 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:<id>#<issue>) 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 <owner/name> is passed) and lands an issue carrying decision-pending / needs-clarification / epic / decomposed as blocked (reason: label:<name>) 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.…