muse-crew 0.7.1 → 0.7.2

package/API.md

@@ -190,6 +190,27 @@ Two namespaces, not one: the vocabulary above is the **dashboard API** (task sta
 
 Record that a poll tick occurred. Takes no arguments. Used by the dispatcher at the end of each cycle to update the last-polled timestamp.
 
+### `reserve-dispatch`
+
+Create a dispatch reservation for a task after the cron worker launches its workflow. The dispatcher skips reserved tasks on subsequent ticks — without this, a task whose workflow takes longer than the poll interval to self-claim would be re-dispatched every tick.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `task_id` | string | Required. The task that was dispatched. |
+| `run_id` | string | Required. The workflow run ID returned by `workflow_launch_async`. |
+| `workflow` | string | Required. Which workflow was launched (`standard`, `bugfix`, `chore`). |
+| `ttl_seconds` | integer | Optional. Reservation lifetime, clamped to 60–3600 seconds. Default 900 (15 minutes). |
+
+Upserts: re-reserving the same task replaces the existing reservation. Returns the reservation with `dispatched_at` and `expires_at` timestamps.
+
+### `clear-reservation`
+
+Remove a task's dispatch reservation. Called by the workflow after a successful self-claim. Takes `task_id` (required). Returns `{ ok: true, cleared: <boolean> }` — `cleared` is false if no reservation existed (idempotent).
+
+### `list-reservations`
+
+List all active (unexpired) dispatch reservations, ordered by dispatch time. Takes no arguments. The dispatcher consumes this via `getdispatchstate` (which includes `reservations`) rather than calling it directly.
+
 ---
 
 ## Projects

package/lib/crew-api.js

@@ -371,6 +371,15 @@ commands["get-dispatch-state"] = (db) => {
       total_sessions: sessionCount,
       total_events: eventCount,
     },
+    // Active dispatch reservations: tasks the worker launched but whose
+    // workflow has not yet self-claimed. The dispatcher skips these.
+    reservations: db.prepare(
+      `SELECT task_id, run_id, workflow, dispatched_at, expires_at
+       FROM dispatch_reservations WHERE expires_at > ? ORDER BY dispatched_at`
+    ).all(now()).map((r) => ({
+      task_id: r.task_id, run_id: r.run_id, workflow: r.workflow,
+      dispatched_at: r.dispatched_at, expires_at: r.expires_at,
+    })),
   };
 };
 
@@ -562,6 +571,41 @@ commands["claim-task"] = (db, args) => {
   return { ok: true, claimed: false, reason: "already_claimed", existing_session_id: existing.id };
 };
 
+// Dispatch reservations: the cron worker creates one after launching a
+// workflow for a task; the dispatcher skips reserved tasks on the next tick;
+// the workflow clears it on self-claim. Expired reservations are inert.
+commands["reserve-dispatch"] = (db, args) => {
+  if (!args.task_id) throw usageError("task_id is required.");
+  if (!args.run_id) throw usageError("run_id is required.");
+  if (!args.workflow) throw usageError("workflow is required.");
+  requireTask(db, args.task_id);
+  const ttl = Math.max(60, Math.min(3600, Number(args.ttl_seconds) || 900));
+  const dispatchedAt = now();
+  const expiresAt = new Date(Date.now() + ttl * 1000).toISOString();
+  db.prepare(
+    `INSERT INTO dispatch_reservations (task_id, run_id, workflow, dispatched_at, expires_at)
+     VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT(task_id) DO UPDATE SET
+       run_id = excluded.run_id, workflow = excluded.workflow,
+       dispatched_at = excluded.dispatched_at, expires_at = excluded.expires_at`
+  ).run(args.task_id, args.run_id, args.workflow, dispatchedAt, expiresAt);
+  return { ok: true, task_id: args.task_id, run_id: args.run_id, workflow: args.workflow, dispatched_at: dispatchedAt, expires_at: expiresAt };
+};
+
+commands["clear-reservation"] = (db, args) => {
+  if (!args.task_id) throw usageError("task_id is required.");
+  const info = db.prepare("DELETE FROM dispatch_reservations WHERE task_id = ?").run(args.task_id);
+  return { ok: true, cleared: info.changes > 0 };
+};
+
+commands["list-reservations"] = (db) => {
+  const rows = db.prepare(
+    `SELECT task_id, run_id, workflow, dispatched_at, expires_at
+     FROM dispatch_reservations WHERE expires_at > ? ORDER BY dispatched_at`
+  ).all(now());
+  return { ok: true, reservations: rows };
+};
+
 commands["park-task"] = (db, args) => {
   if (!args.task_id) throw usageError("task_id is required.");
   const message = (args.message ?? "").trim();

package/lib/schema.sql

@@ -99,3 +99,20 @@ CREATE INDEX IF NOT EXISTS events_task_id_idx ON events(task_id);
 -- another session holds the claim.
 CREATE UNIQUE INDEX IF NOT EXISTS agent_sessions_one_running_per_task_idx
   ON agent_sessions(task_id) WHERE status = 'running';
+
+-- Dispatch reservations: the dispatcher recommends, the cron worker launches,
+-- and the launched workflow self-claims. The claim can take 15+ minutes for
+-- cron-launched runs (canary 2026-09-13), far longer than the 3-minute poll
+-- interval — without a reservation, every tick re-dispatches the same task.
+-- The worker creates a reservation after launching; the dispatcher skips
+-- reserved tasks; the workflow clears it on self-claim. Expired reservations
+-- are ignored (the workflow died before claiming).
+CREATE TABLE IF NOT EXISTS dispatch_reservations (
+  task_id       TEXT PRIMARY KEY REFERENCES tasks(id) ON DELETE CASCADE,
+  run_id        TEXT NOT NULL,
+  workflow      TEXT NOT NULL,
+  dispatched_at TEXT NOT NULL,
+  expires_at    TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS dispatch_reservations_expires_idx
+  ON dispatch_reservations(expires_at);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muse-crew",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Opinionated orchestration for Muse — workflows, identities, and tooling for autonomous software development.",
   "license": "UNLICENSED",
   "private": false,

package/seed/cron-body-template.md

@@ -13,8 +13,10 @@ You are the dispatch trigger for Muse Crew. Run the authoritative dispatcher wor
    Wait for it to complete. It reads the crew's task state, determines eligibility, claims tasks, acknowledges the poll, and returns structured results.
 
 4. **Launch claims autonomously:** Extract the `claims` array from the dispatcher result. For each claim (up to 3 per tick — if more than 3, launch the first 3 and log the rest as deferred):
-   - Call workflow_launch_async with scriptPath={claim.scriptPath} and args={claim.args}.
-   - The launched workflow self-claims the task as its first action. If the task was already claimed or is done, the claim fails closed and the run stands down quietly — this is the mechanical duplicate protection, not an error.
+   - Call workflow_launch_async with scriptPath={claim.scriptPath} and args={claim.args}. Record the returned run_id.
+   - Immediately create a dispatch reservation so the next tick does not re-dispatch before the workflow self-claims (claims can take 15+ minutes for cron-launched runs). Run in shell:
+     `node {crewHome}/lib/crew-api.js --crew-home {crewHome} reserve-dispatch --json '{"task_id": "{claim.task_id}", "run_id": "<run_id>", "workflow": "{claim.workflow}"}'`
+   - The launched workflow self-claims the task and clears the reservation as its first actions. If the task was already claimed or is done, the claim fails closed and the run stands down quietly — this is the mechanical duplicate protection, not an error.
 
    If the dispatcher returned no claims or the claims array is empty, report: NO_DISPATCH
 

package/workflows/bugfix.js

@@ -1060,6 +1060,7 @@ while (i < STEPS.length) {
       "Claim this task for the " + step.name + " step.\n" +
       "Run in shell and return the stdout verbatim:\n" + crewCmd("update-task", firstClaimUpdateArgs) + "\n" +
       "Then run in shell and return the stdout verbatim:\n" + crewCmd("claim-task", { task_id: taskId, identity: step.identity, step: step.name, notes: step.name + " step started" }) + "\n" +
+      "If the claim response has claimed=true, then run in shell and return the stdout verbatim:\n" + crewCmd("clear-reservation", { task_id: taskId }) + "\n" +
       "Do not interpret the claim response. It already contains an explicit \"claimed\" field — copy it verbatim.\n" +
       "Return { claimed: <verbatim>, session_id: \"<...>\" }. If claimed is false there is no session_id; return { claimed: false, session_id: \"\" }.",
       {

package/workflows/chore.js

@@ -1017,6 +1017,7 @@ while (i < STEPS.length) {
       "Claim this task for the " + step.name + " step.\n" +
       "Run in shell and return the stdout verbatim:\n" + crewCmd("update-task", firstClaimUpdateArgs) + "\n" +
       "Then run in shell and return the stdout verbatim:\n" + crewCmd("claim-task", { task_id: taskId, identity: step.identity, step: step.name, notes: step.name + " step started" }) + "\n" +
+      "If the claim response has claimed=true, then run in shell and return the stdout verbatim:\n" + crewCmd("clear-reservation", { task_id: taskId }) + "\n" +
       "Do not interpret the claim response. It already contains an explicit \"claimed\" field — copy it verbatim.\n" +
       "Return { claimed: <verbatim>, session_id: \"<...>\" }. If claimed is false there is no session_id; return { claimed: false, session_id: \"\" }.",
       {

package/workflows/crew-dispatch.js

@@ -237,6 +237,15 @@ const allTasks = boardData.ready_tasks.map(projectTaskRecord).filter(function (t
 const config = boardData.config || {};
 const projects = boardData.projects || [];
 
+// Dispatch reservations: tasks the worker launched on a previous tick whose
+// workflow has not yet self-claimed. The claim can take 15+ minutes for
+// cron-launched runs (canary 2026-09-13) — far longer than the poll interval —
+// so without this filter every tick would re-dispatch the same task.
+const reservedTaskIds = new Set((boardData.reservations || []).map(function (r) { return r.task_id; }));
+if (reservedTaskIds.size > 0) {
+  log("Reservations: skipping " + reservedTaskIds.size + " task(s) with an active dispatch reservation");
+}
+
 // Default project: explicit arg, or first registered project
 const DEFAULT_PROJECT = inputs.defaultProject || (projects.length > 0 ? projects[0].id : "");
 
@@ -383,6 +392,14 @@ for (var t = 0; t < allTasks.length; t++) {
   var task = allTasks[t];
   if (task.blocked) continue;
 
+  // Skip tasks with an active dispatch reservation: the worker launched a
+  // workflow for this task on a previous tick, but the workflow has not yet
+  // self-claimed (claims can take 15+ minutes for cron-launched runs).
+  if (reservedTaskIds.has(task.id)) {
+    log("Skipped \"" + task.title + "\" — active dispatch reservation (workflow launched, claim pending)");
+    continue;
+  }
+
   // Skip tasks from quiesced projects
   var taskProject = task.project || DEFAULT_PROJECT;
   if (quiescedProjects[taskProject]) {

package/workflows/standard.js

@@ -1059,6 +1059,7 @@ while (i < STEPS.length) {
       "Claim this task for the " + step.name + " step.\n" +
       "Run in shell and return the stdout verbatim:\n" + crewCmd("update-task", firstClaimUpdateArgs) + "\n" +
       "Then run in shell and return the stdout verbatim:\n" + crewCmd("claim-task", { task_id: taskId, identity: step.identity, step: step.name, notes: step.name + " step started" }) + "\n" +
+      "If the claim response has claimed=true, then run in shell and return the stdout verbatim:\n" + crewCmd("clear-reservation", { task_id: taskId }) + "\n" +
       "Do not interpret the claim response. It already contains an explicit \"claimed\" field — copy it verbatim.\n" +
       "Return { claimed: <verbatim>, session_id: \"<...>\" }. If claimed is false there is no session_id; return { claimed: false, session_id: \"\" }.",
       {