muse-crew 0.5.0 → 0.6.0

package/docs/guide.md

@@ -17,8 +17,7 @@ This is the full setup and operations reference. If you're new, start with the [
 - A **release** — the first immutable snapshot of the crew's runtime code.
 - An **`.orchestration/` directory** in the crew home with identities, personas, workflow docs, and feedback conventions.
 - A **project registration** — the task service registered as its own first project.
-- A **polling loop** — checks for work every 3 minutes via Muse's scheduling, even when nobody's in the conversation.
-- An **orphan sweep** — runs every 30 minutes to clean merged worktrees and break stale merge locks. It never touches worktrees belonging to tasks with a running dashboard session.
+- **Cron jobs** — the scheduler state declared in `seed/crons.json`: a polling loop (every 3 minutes via Muse's scheduling, even when nobody's in the conversation) and an orphan sweep (every 30 minutes, cleaning merged worktrees and breaking stale merge locks; it never touches worktrees belonging to tasks with a running dashboard session). Owner is `space:<slug>`, so deleting the task service also removes the crons.
 
 The agent running in the main chat receives the dispatcher's claims and launches each task workflow. Workflows can't launch workflows, so this handoff is structural.
 
@@ -56,12 +55,11 @@ Required arguments:
 
 Optional arguments:
 - `dashboardName` — display name for the project registration (default: `"Muse Crew"`).
-- `cronId` — polling cron identifier (default: `"crew-poll"`).
-- `sweepCronId` — orphan sweep cron identifier (default: `"crew-orphan-sweep"`).
+- `cronIds` — manifest id → live id map for parallel instances on one account (default: `{}`). The manifest's ids are used as-is unless overridden, e.g. `{"crew-poll": "crew-poll-canary", "crew-orphan-sweep": "crew-sweep-canary"}`.
 
 ### What init creates
 
-Init runs five phases, each idempotent — re-running skips anything that already exists:
+Init runs four phases, each idempotent — re-running converges anything that drifted and skips what already matches:
 
 1. **Release** — copies `crew-release.sh` to `crewHome`, runs `init` to create the first release from the source directory. From a Git checkout, it extracts `workflows/` and `lib/` via `git archive` and uses the commit hash as the release identity. From an npm install, it copies the directories directly and uses the package version (e.g., `pkg-0.1.0`). Creates a release directory, sets the `current` symlink.
 
@@ -69,9 +67,7 @@ Init runs five phases, each idempotent — re-running skips anything that alread
 
 3. **Project registration** — registers the task service as a project in its own database via `createproject`. The dashboard becomes its own first project, so the crew can work on the dashboard itself.
 
-4. **Polling cron** — creates a 3-minute interval cron from the template at `seed/cron-body-template.md`, with `crewHome` and the dashboard slug substituted in. Owner is `space:<slug>`, so deleting the task service also removes the cron.
-
-5. **Sweep cron** — creates a 30-minute interval cron that runs the orphan sweep to clean merged worktrees and break stale merge locks. Owner is `space:<slug>`.
+4. **Crons** — reads the manifest at `seed/crons.json` and makes the scheduler match it: missing jobs are created from the entry (title, enabled, mode, schedule, owner, timeout_secs, and the body built from the entry's template with `crewHome` and the dashboard slug substituted in); existing jobs are viewed and converged — drifted fields are updated, unchanged jobs are left alone. One exception: init never touches `enabled` on an existing job. `enabled` is a creation-time default only — a disabled job is a deliberate human decision (the orphan sweep ships disabled as a holding state), and re-init must not silently resurrect it. Jobs removed from the manifest are left alone; deletion is a human decision.
 
 ### Verification
 
@@ -83,16 +79,17 @@ After init completes, it returns a summary:
   "crewHome": "~/workspace/.jarvis",
   "dashboardSlug": "orchestra-dashboard",
   "dashboardName": "Muse Crew",
-  "cronId": "crew-poll",
   "releaseHash": "<git commit hash>",
   "scaffold": { "created": 23, "skipped": 0 },
   "project": "registered",
-  "cron": "created",
-  "sweepCron": "created"
+  "crons": [
+    { "id": "crew-poll", "action": "created", "updated_fields": [] },
+    { "id": "crew-orphan-sweep", "action": "created", "updated_fields": [] }
+  ]
 }
 ```
 
-Re-running init against an existing setup returns all `"existed"` / `"skipped"` results with no mutations.
+Re-running init against an existing setup returns `"unchanged"` (or `"updated"` with the converged field names) for each cron, with no other mutations.
 
 ## Connecting an existing project
 

package/package.json

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

package/seed/AGENTS.md

@@ -2,6 +2,7 @@
 
 Init source data. Everything `crew-init.js` reads when setting up a new crew instance on a Muse account.
 
+- `crons.json` — the declarative cron manifest; crew-init creates/updates each entry idempotently; `enabled` is a creation-time default only
 - `cron-body-template.md` — template for creating the dispatch cron job
 - `cron-sweep-body-template.md` — template for creating the orphan-sweep cron job
 - `posture.md` — PM posture that shapes the user's assistant for crew interaction

package/seed/crons.json

@@ -0,0 +1,31 @@
+{
+  "crons": [
+    {
+      "body_template": "cron-body-template.md",
+      "enabled": true,
+      "id": "crew-poll",
+      "mode": "task",
+      "owner": "space:{dashboardSlug}",
+      "schedule": {
+        "every": "3m",
+        "kind": "interval"
+      },
+      "timeout_secs": 120,
+      "title": "Muse Crew polling loop"
+    },
+    {
+      "body_template": "cron-sweep-body-template.md",
+      "enabled": false,
+      "id": "crew-orphan-sweep",
+      "mode": "task",
+      "owner": "space:{dashboardSlug}",
+      "schedule": {
+        "every": "30m",
+        "kind": "interval"
+      },
+      "timeout_secs": 120,
+      "title": "Muse Crew orphan sweep"
+    }
+  ],
+  "version": 1
+}

package/workflows/crew-init.js

@@ -1,12 +1,11 @@
 export const meta = {
   name: "crew-init",
-  description: "Initialize Muse Crew: bootstrap release, scaffold orchestration, register dashboard project, set up polling cron. Idempotent — safe to re-run.",
+  description: "Initialize Muse Crew: bootstrap release, scaffold orchestration, register dashboard project, set up cron jobs. Idempotent — safe to re-run.",
   phases: [
     { name: "release", title: "Bootstrap release system" },
     { name: "scaffold", title: "Scaffold orchestration directory" },
     { name: "project", title: "Register dashboard project" },
-    { name: "cron", title: "Create polling cron" },
-    { name: "sweep-cron", title: "Create sweep cron" }
+    { name: "crons", title: "Create and converge cron jobs" }
   ]
 };
 
@@ -16,8 +15,7 @@ const crewRepoPath = inputs.crewRepoPath;
 const crewHome = inputs.crewHome;
 const dashboardSlug = inputs.dashboardSlug;
 const dashboardName = inputs.dashboardName || "Muse Crew";
-const cronId = inputs.cronId || "crew-poll";
-const sweepCronId = inputs.sweepCronId || "crew-orphan-sweep";
+const cronIds = inputs.cronIds || {};
 
 if (!crewRepoPath) throw new Error("crewRepoPath is required — path to muse-crew (git checkout or npm install)");
 if (!crewHome) throw new Error("crewHome is required — e.g. ~/.crew");
@@ -145,98 +143,89 @@ try {
 }
 log("Project: " + (projectResult.registered ? "registered" : "failed"));
 
-// ── Phase 4: Polling cron ─────────────────────────────────────────────
-// The cron body template lives in the repo at seed/cron-body-template.md.
-// Placeholders: {crewHome}, {dashboardSlug} are replaced with actual values.
-// Owner is the dashboard artifact so deleting the dashboard kills the cron.
-phase("cron");
-var cronResult;
+// ── Phase 4: Cron jobs (declarative manifest) ──────────────────────────
+// The manifest lives in the repo at seed/crons.json. Body templates live
+// in seed/ with {crewHome}/{dashboardSlug} placeholders. Missing jobs are
+// created from the manifest; existing jobs converge to it — except `enabled`,
+// which is a creation-time default only and is never touched on update.
+phase("crons");
+var cronsResult;
 try {
-  cronResult = await agent(
-    "Check if the polling cron exists and create it if not.\n\n" +
-    "Cron id: " + cronId + "\n" +
-    "Template: " + crewRepoPath + "/seed/cron-body-template.md\n" +
+  cronsResult = await agent(
+    "Ensure the Muse Crew cron jobs match the repo's declarative manifest.\n\n" +
+    "Manifest: " + crewRepoPath + "/seed/crons.json\n" +
     "crewHome: " + crewHome + "\n" +
-    "Dashboard slug: " + dashboardSlug + "\n\n" +
+    "Dashboard slug: " + dashboardSlug + "\n" +
+    "Id overrides (manifest id -> live id): " + JSON.stringify(cronIds) + "\n\n" +
     "Steps:\n" +
-    "1. Call cron_list and look for a job with id '" + cronId + "'\n" +
-    "2. If it exists, return { existed: true }\n" +
-    "3. If not found:\n" +
-    "   a. Read the template at " + crewRepoPath + "/seed/cron-body-template.md\n" +
-    "   b. Replace all occurrences of {crewHome} with: " + crewHome + "\n" +
-    "      Replace all occurrences of {dashboardSlug} with: " + dashboardSlug + "\n" +
-    "   c. Call cron_add with:\n" +
-    "      - id: '" + cronId + "'\n" +
-    "      - title: 'Muse Crew polling loop'\n" +
-    "      - enabled: true\n" +
-    "      - mode: 'task'\n" +
-    "      - schedule: { kind: 'interval', every: '3m' }\n" +
-    "      - owner: 'space:" + dashboardSlug + "'\n" +
-    "      - timeout_secs: 120\n" +
-    "      - body: the processed template text\n" +
-    "   d. Return { existed: false }\n\n" +
-    "Return JSON with existed (boolean).",
+    "1. Read the manifest at " + crewRepoPath + "/seed/crons.json and parse it as JSON.\n" +
+    "   Fail closed (return passed: false) if the file is missing, is not valid JSON,\n" +
+    "   or any entry lacks a required field (id, title, enabled, mode, schedule,\n" +
+    "   owner, body_template).\n" +
+    "2. For each manifest entry, in order:\n" +
+    "   a. The live id is the override for entry.id when present, else entry.id.\n" +
+    "   b. Read the body template at " + crewRepoPath + "/seed/<entry.body_template>.\n" +
+    "   c. Replace all occurrences of {crewHome} with: " + crewHome + " and all\n" +
+    "      occurrences of {dashboardSlug} with: " + dashboardSlug + ".\n" +
+    "   d. Call cron_list and look for a job with the live id.\n" +
+    "   e. If missing, call cron_add with:\n" +
+    "      - id: the live id\n" +
+    "      - title, enabled, mode from the entry\n" +
+    "      - schedule: the entry's schedule object\n" +
+    "      - owner: the entry's owner with {dashboardSlug} replaced by " + dashboardSlug + "\n" +
+    "      - timeout_secs: the entry's timeout_secs when present\n" +
+    "      - body: the resolved template text\n" +
+    "      Record action 'created' with no updated fields.\n" +
+    "   f. If it exists, call cron_view and compare against the manifest-derived\n" +
+    "      definition (title, mode, schedule, owner, timeout_secs, body).\n" +
+    "      Never compare or pass enabled: a live job's enabled state is a human\n" +
+    "      decision; re-init must not silently enable or disable jobs.\n" +
+    "      Compare schedule only on the keys the manifest declares; ignore\n" +
+    "      runtime-owned fields (timezone, at).\n" +
+    "      Call cron_update with only the fields that differ. If nothing differs,\n" +
+    "      do not call cron_update. Record action 'updated' with the updated field\n" +
+    "      names, or 'unchanged' with no updated fields.\n" +
+    "3. Return { passed: true, summary: { crons: [...] } } with one entry per\n" +
+    "   manifest entry, in manifest order: { id, action: 'created' | 'updated' |\n" +
+    "   'unchanged', updated_fields: [...] }.",
     {
-      key: "cron-1",
-      label: "Create polling cron",
+      key: "crons-1",
+      label: "Create and converge cron jobs",
       schema: {
         type: "object",
         properties: {
-          existed: { type: "boolean" }
+          passed: { type: "boolean" },
+          summary: {
+            type: "object",
+            properties: {
+              crons: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    id: { type: "string" },
+                    action: { type: "string", enum: ["created", "updated", "unchanged"] },
+                    updated_fields: { type: "array", items: { type: "string" } }
+                  },
+                  required: ["id", "action", "updated_fields"]
+                }
+              }
+            },
+            required: ["crons"]
+          }
         },
-        required: ["existed"]
+        required: ["passed", "summary"]
       }
     }
   );
 } catch (e) {
-  return { __hatchWorkflowControl: "blocked", result: { blocked_reason: "Cron creation failed", message: String(e.message || e) } };
+  return { __hatchWorkflowControl: "blocked", result: { blocked_reason: "Cron setup failed", message: String(e.message || e) } };
 }
-log("Cron: " + (cronResult.existed ? "already existed" : "created as " + cronId));
-
-// ── Phase 5: Sweep cron ──────────────────────────────────────────────
-phase("sweep-cron");
-var sweepResult;
-try {
-  sweepResult = await agent(
-    "Check if the orphan sweep cron exists and create it if not.\n\n" +
-    "Cron id: " + sweepCronId + "\n" +
-    "Template: " + crewRepoPath + "/seed/cron-sweep-body-template.md\n" +
-    "crewHome: " + crewHome + "\n" +
-    "Dashboard slug: " + dashboardSlug + "\n\n" +
-    "Steps:\n" +
-    "1. Call cron_list and look for a job with id '" + sweepCronId + "'\n" +
-    "2. If it exists, return { existed: true } WITHOUT touching it — adopt means\n" +
-    "   adopt: do not enable it, rewrite its body, or change its schedule.\n" +
-    "3. If not found:\n" +
-    "   a. Read the template at " + crewRepoPath + "/seed/cron-sweep-body-template.md\n" +
-    "   b. Replace all occurrences of {crewHome} with: " + crewHome + "\n" +
-    "      Replace all occurrences of {dashboardSlug} with: " + dashboardSlug + "\n" +
-    "   c. Call cron_add with:\n" +
-    "      - id: '" + sweepCronId + "'\n" +
-    "      - title: 'Muse Crew orphan sweep'\n" +
-    "      - enabled: false (deliberate holding state — the sweep stays disabled\n" +
-    "        until explicitly enabled by a human; never resurrect it enabled)\n" +
-    "      - mode: 'task'\n" +
-    "      - schedule: { kind: 'interval', every: '30m' }\n" +
-    "      - owner: 'space:" + dashboardSlug + "'\n" +
-    "      - timeout_secs: 120\n" +
-    "      - body: the processed template text\n" +
-    "   d. Return { existed: false }\n\n" +
-    "Return JSON with existed (boolean).",
-    {
-      key: "sweep-cron-1",
-      label: "Create sweep cron",
-      schema: {
-        type: "object",
-        properties: { existed: { type: "boolean" } },
-        required: ["existed"]
-      }
-    }
-  );
-} catch (e) {
-  return { __hatchWorkflowControl: "blocked", result: { blocked_reason: "Sweep cron creation failed", message: String(e.message || e) } };
+if (!cronsResult.passed || !cronsResult.summary || !Array.isArray(cronsResult.summary.crons)) {
+  return { __hatchWorkflowControl: "blocked", result: { blocked_reason: "Cron manifest invalid", message: "seed/crons.json failed validation or produced no crons list" } };
 }
-log("Sweep cron: " + (sweepResult.existed ? "already existed" : "created as " + sweepCronId));
+log("Crons: " + cronsResult.summary.crons.map(function (c) { return c.id + "=" + c.action; }).join(", "));
+
 
 // ── Summary ───────────────────────────────────────────────────────────
 return {
@@ -244,10 +233,8 @@ return {
   crewHome: crewHome,
   dashboardSlug: dashboardSlug,
   dashboardName: dashboardName,
-  cronId: cronId,
   releaseHash: releaseResult.hash,
   scaffold: { created: scaffoldCreated, skipped: scaffoldSkipped },
   project: projectResult.registered ? "registered" : "failed",
-  cron: cronResult.existed ? "existed" : "created",
-  sweepCron: sweepResult.existed ? "existed" : "created"
+  crons: cronsResult.summary.crons
 };