muse-crew 0.7.20 → 0.8.0

package/workflows/upgrade.js

@@ -0,0 +1,794 @@
+export const meta = {
+  name: "crew-upgrade",
+  description: "Upgrade the crew itself: deploy a new release and hand over to it on the next tick.",
+  phases: ["Triage", "Deploy", "Verify"],
+  steps: [
+    { name: "Triage", identity: "sage" },
+    { name: "Deploy", identity: "wren" },
+    { name: "Verify", identity: "wren" }
+  ],
+  reworkTarget: "Deploy"
+};
+
+// ── Pure helpers (upgrade.js) ─────────────────────────────────────────
+// No I/O, no clock, no randomness. Tests extract these by balanced-brace
+// matching (the merge-record.test.js pattern), so they are plain top-level
+// function declarations with no unbalanced braces inside string literals.
+
+// The upgrade source comes from a `source:` line in the task description:
+//   source: repo          — upgrade to the task project's repo HEAD (default when the line is absent)
+//   source: npm@<x.y.z>   — upgrade to the published npm package muse-crew@<x.y.z>
+// Returns the trimmed token after `source:`, or "repo" when no line is present.
+function parseUpgradeSource(description) {
+  var m = /^source:\s*(\S+)/im.exec(description || "");
+  return m ? m[1].trim() : "repo";
+}
+
+// npm versions are exactly x.y.z — no tags, no ranges, no dist-tags.
+function isValidNpmVersion(v) {
+  return /^\d+\.\d+\.\d+$/.test(v || "");
+}
+
+// Resolve the release identity for a source. Matches crew-release.sh:
+// git source deploys as the HEAD sha, npm source as pkg-<version>.
+function upgradeTarget(source, version, repoHead) {
+  if (source === "repo") {
+    if (!/^[0-9a-f]{40}$/.test(repoHead || "")) {
+      return { ok: false, error: "repo HEAD is not a 40-char hex sha: '" + (repoHead || "") + "'" };
+    }
+    return { ok: true, target: repoHead };
+  }
+  if (source === "npm") {
+    if (!isValidNpmVersion(version)) {
+      return { ok: false, error: "invalid npm version: '" + (version || "") + "' — expected x.y.z" };
+    }
+    return { ok: true, target: "pkg-" + version };
+  }
+  return { ok: false, error: "unknown upgrade source: '" + source + "'" };
+}
+
+// Idempotency: exact string equality of current and target release identities.
+function decideNoOp(current, target) {
+  return current === target;
+}
+
+const inputs = args ?? {};
+const taskId = inputs.task_id;
+const taskTitle = inputs.task_title || "";
+const taskDescription = inputs.task_description || "";
+const startStepIndex = inputs.start_step_index || 0;
+
+// Dispatcher-carried facts for the claim-time persist: the workflow name the
+// dispatcher actually resolved and launched, and whether the task record had
+// no workflow (the standard fallback). The launched workflow writes the
+// resolution back via updatetask in the self-claim below.
+const RESOLVED_WORKFLOW = inputs.resolved_workflow || null;
+const WORKFLOW_WAS_NULL = inputs.workflow_was_null === true;
+// One-shot recovery routing: the dispatcher sets inputs.next_phase when it
+// routes this run via an explicit recover-task redirect. The value is
+// consumed (cleared) atomically by the successful self-claim below:
+// claim-task takes expected_next_phase and clears the matching next_phase in
+// the same transaction as the winning session insert, so no platform death
+// can slip between claim and consumption and replay the routing. A stale or
+// superseded routing survives — only an exact match clears.
+const NEXT_PHASE_ROUTED = (typeof inputs.next_phase === "string" && inputs.next_phase.length > 0) ? inputs.next_phase : null;
+
+// crewHome is required — the dispatcher always passes it (crew-dispatch.js
+// throws without it). Fail closed instead of silently defaulting to the dev
+// home: a missing home is a loud error, a wrong home is silent corruption
+// (2026-09-16: the silent default let a run resolve against the dev home).
+if (!inputs.crewHome) throw new Error("crewHome is required — pass the crew home explicitly; no default");
+const crewHome = inputs.crewHome;
+// Crew API: the workflow calls the crew-owned CLI, not the dashboard.
+// The CLI implements the API.md contract against $CREW_HOME/crew-state.db.
+const CREW_API_SRC = crewHome + "/current/lib/crew-api.js";
+// Pinned at pinLifecycle: after the pin, CREW_API points into RUN_LIB so a
+// mid-flight release swap cannot change the CLI under a running workflow.
+// Load-bearing here: this workflow swaps `current` under itself at Deploy.
+let CREW_API = CREW_API_SRC;
+// Build a shell command invoking the CLI. Args are JSON-encoded and
+// single-quote-wrapped for safe shell passing. The agent runs this and
+// returns the stdout verbatim (the CLI emits JSON on stdout).
+function crewCmd(command, args) {
+  var json = JSON.stringify(args || {}).replace(/'/g, "'\\''");
+  return "node " + CREW_API + " --crew-home " + crewHome + " " + command + " --json '" + json + "'";
+}
+// Telemetry (2026-09-13): structured run timeline. The workflow mints a
+// telemetry run_id at startup via record-run-start (the API generates it
+// server-side — workflow JS never touches the clock or randomness) and
+// records milestone events. Timestamps come from SQLite datetime('now').
+// Fire-and-forget: telemetry must never break the run (no schema — the
+// run-5/run-6 fire-and-forget rule).
+let telemetryRunId = null;
+let telemetryBuffer = [];
+async function telemetryStart(workflowName) {
+  try {
+    const out = await agent(crewCmd("record-run-start", {
+      task_id: taskId, workflow: workflowName, launched_by: "cron"
+    }), { key: "telemetry-start", label: "Recording run start" });
+    const parsed = typeof out === "string" ? JSON.parse(out) : out;
+    if (parsed && parsed.run_id) telemetryRunId = parsed.run_id;
+  } catch (e) {
+    log("Telemetry start failed (non-fatal): " + (e && e.message ? e.message : e));
+  }
+}
+async function telemetryEvent(eventName, detail) {
+  // Buffer non-critical events; flush at critical points.
+  if (!telemetryRunId) return;
+  telemetryBuffer.push({ event_name: eventName, detail: detail || "" });
+  // Auto-flush if buffer gets large (avoid unbounded memory).
+  if (telemetryBuffer.length >= 10) {
+    await telemetryFlush();
+  }
+}
+async function telemetryFlush() {
+  if (!telemetryRunId || telemetryBuffer.length === 0) return;
+  const events = telemetryBuffer.splice(0, telemetryBuffer.length);
+  try {
+    // Send all buffered events in a single agent() call via a batch command.
+    await agent(crewCmd("record-run-events-batch", {
+      run_id: telemetryRunId, task_id: taskId, events: events
+    }), { key: "telemetry-flush", label: "Flushing " + events.length + " telemetry events" });
+  } catch (e) {
+    log("Telemetry flush failed (non-fatal): " + events.length + " events lost");
+  }
+}
+async function telemetryEnd(status) {
+  if (!telemetryRunId) return;
+  // Flush any buffered events before recording the end.
+  await telemetryFlush();
+  try {
+    await agent(crewCmd("record-run-end", {
+      run_id: telemetryRunId, status: status
+    }), { key: "telemetry-end", label: "Recording run end" });
+  } catch (e) {
+    log("Telemetry end failed (non-fatal)");
+  }
+}
+const ORCH_PATH = crewHome + "/.orchestration";
+// Pin lifecycle scripts to this run
+const LIFECYCLE_SRC = crewHome + "/lib/worktree-lifecycle.sh";
+const MERGE_LOCK_SRC = crewHome + "/lib/merge-lock.sh";
+const RUN_LIB = crewHome + "/.pins/" + taskId; // persistent disk, NOT /tmp (tmpfs wiped by cell reboots — canary b5efd1b1)
+const LIFECYCLE = RUN_LIB + "/worktree-lifecycle.sh";
+const MERGE_LOCK = RUN_LIB + "/merge-lock.sh";
+const PUBLISH_NPM_SRC = crewHome + "/lib/publish-npm.sh";
+const PUBLISH_NPM = RUN_LIB + "/publish-npm.sh";
+const CREW_API_PINNED = RUN_LIB + "/crew-api.js";
+const SCHEMA_SQL_SRC = crewHome + "/lib/schema.sql";
+const SCHEMA_SQL_PINNED = RUN_LIB + "/schema.sql";
+// The five basenames the pin step must materialize — asserted mechanically
+// by workflow code from the verbatim listing, never from agent prose.
+const PIN_BASENAMES = [LIFECYCLE, MERGE_LOCK, PUBLISH_NPM, CREW_API_PINNED, SCHEMA_SQL_PINNED].map(function (p) { return p.split("/").pop(); });
+
+// Project config — passed by dispatcher, falls back to dashboard defaults
+const projectConfig = inputs.project_config || {};
+// Project this run was dispatched for — the mid-run project-change guard
+// compares the task's live project against this on every phase boundary.
+const LAUNCH_PROJECT_ID = inputs.project_id || "";
+// REPO_PATH is READ-ONLY in this workflow: it is used only to resolve
+// `git rev-parse HEAD` for the repo upgrade source. Never written to, never
+// a worktree target. Unlike chore.js there is no startup throw here: the
+// npm source needs no repo, and a missing repo_path for the repo source
+// parks fail-closed at Triage.
+const REPO_PATH = projectConfig.repo_path || "";
+// Env prefix baked into every lifecycle invocation the agents run.
+const LIFECYCLE_ENV = "CREW_HOME=" + crewHome + " CREW_REPO=" + REPO_PATH + " ";
+// The stable release script — deploys, reports the live release.
+const DEPLOY_SCRIPT = crewHome + "/crew-release.sh";
+
+if (!taskId) {
+  throw new Error("task_id is required in args");
+}
+
+// pinLifecycle(key) — snapshot the lifecycle scripts into RUN_LIB and return
+// the verbatim `ls -1` listing so WORKFLOW CODE asserts the five pinned
+// basenames; the agent cannot self-certify. (The pin step was the one place
+// the workflows trusted agent prose: task 24be1cd6 walked to Publish on an
+// empty pin dir.) Byte-identical across standard/bugfix/chore — pinned by
+// tests/pin-location.test.js.
+function pinLifecycle(key) {
+  return agent(
+    "Snapshot lifecycle scripts for version pinning.\n" +
+    "Run: mkdir -p " + RUN_LIB + " && cp " + LIFECYCLE_SRC + " " + LIFECYCLE + " && cp " + MERGE_LOCK_SRC + " " + MERGE_LOCK + " && cp " + PUBLISH_NPM_SRC + " " + PUBLISH_NPM + " && cp " + CREW_API_SRC + " " + CREW_API_PINNED + " && cp " + SCHEMA_SQL_SRC + " " + SCHEMA_SQL_PINNED + " && chmod +x " + LIFECYCLE + " " + MERGE_LOCK + " " + PUBLISH_NPM + " && ls -1 " + RUN_LIB + "\n" +
+    "Return the verbatim output of the ls -1 command as { \"listing\": \"<verbatim output>\" } and nothing else.",
+    { key: key, label: "Pinning lifecycle scripts",
+      schema: { type: "object", properties: { listing: { type: "string" } }, required: ["listing"] } }
+  );
+}
+// parsePinListing(result) — basenames from a pin/verify listing.
+// Byte-identical across standard/bugfix/chore — pinned by
+// tests/pin-location.test.js.
+function parsePinListing(result) {
+  return (result && result.listing ? result.listing : "").split("\n").map(function (s) { return s.trim(); }).filter(function (s) { return s.length > 0; });
+}
+// TOOL_CHECK_PREAMBLE - every work agent runs this first. The artifact tool
+// namespace is deferred for workflow children: present but invisible until
+// the child loads it via tool_search.load_tool_namespace (bug 3472bf36 root
+// cause, verified 2026-09-11 by direct probe: 5/5 children self-loaded it;
+// the "non-deterministic platform flake" was children never being told to
+// load it). The two signal lines are the ONLY machine-read tool-availability
+// evidence - the workflow never guesses from English prose.
+// Byte-identical across standard/bugfix/chore/docs - pinned by
+// tests/artifact-tools.test.js.
+var TOOL_CHECK_PREAMBLE =
+  "TOOL CHECK (do this first, before any other work):\n" +
+  "1. Call tool_search.load_tool_namespace with paths [\"artifact\"].\n" +
+  "2. Write exactly one line: artifact_tools: ok - or artifact_tools: missing if the call failed or the tool does not exist.\n" +
+  "3. Run the shell command: echo tool-probe-ok - then write exactly one line: shell_transport: ok - or shell_transport: unavailable if you cannot run shell commands.\n" +
+  "Then do the assignment below.\n\n";
+
+// STEPS inline — export const meta is parsed as metadata, not a runtime binding
+const STEPS = [
+  { name: "Triage", identity: "sage" },
+  { name: "Deploy", identity: "wren" },
+  { name: "Verify", identity: "wren" }
+];
+const REWORK_STEP = "Deploy"; // meta.reworkTarget; kept in the phase loop, but every failure parks fail-closed
+let reworkCount = 0; // never incremented: no Review phase, so rework never routes in practice
+let i = startStepIndex;
+// Triage computes these; later phases consume them. A resumed run (the
+// dispatcher launches at the next step after a completed phase, so Triage
+// never re-executes) reconstructs the plan deterministically through
+// computeUpgradePlan before Deploy/Verify — the plan is pure evidence +
+// mechanical decisions, so re-gathering it is safe.
+let upgradePlan = null; // { source, version, target, current }
+let skipDeploy = false; // idempotent no-op: current == target
+
+// Gather upgrade evidence and compute the plan mechanically. The agent does
+// shell I/O only and returns a schema'd object; WORKFLOW CODE re-parses the
+// `source:` line and makes every decision — the agent's reading is evidence,
+// never the decision. Used by Triage and, on resumed runs, to reconstruct
+// the plan before Deploy/Verify.
+async function computeUpgradePlan(evidenceKey, noteIdentity) {
+  const srcToken = parseUpgradeSource(taskDescription);
+  const sourceIsRepo = (srcToken === "repo");
+  var triageResult;
+  try {
+    triageResult = await agent(
+      TOOL_CHECK_PREAMBLE +
+      "Collect upgrade evidence for a crew self-upgrade task. You do shell I/O only — every decision is made by the workflow from the values you return.\n" +
+      "Task description:\n" + taskDescription + "\n\n" +
+      "1. Find the first line of the task description matching /^source:/im. Echo it verbatim as source_line (empty string if no such line exists).\n" +
+      (sourceIsRepo
+        ? "2. The workflow was told source is repo. Check that " + REPO_PATH + "/workflows is a directory AND " + REPO_PATH + "/lib/crew-release.sh exists — repo_ok is true only if both hold. Run: git -C " + REPO_PATH + " rev-parse HEAD and capture the sha as head (empty string if the command fails).\n"
+        : "2. The workflow was told source is not repo. Skip all repo checks: return repo_ok false and head as an empty string.\n") +
+      "3. Run: " + DEPLOY_SCRIPT + " current " + crewHome + " — capture the full trimmed stdout as current.\n" +
+      "Return JSON { \"source_line\": \"<verbatim>\", \"repo_ok\": <bool>, \"head\": \"<sha or empty>\", \"current\": \"<trimmed stdout>\" } and nothing else.",
+      {
+        key: evidenceKey,
+        label: "Collecting upgrade evidence",
+        schema: {
+          type: "object",
+          properties: {
+            source_line: { type: "string" },
+            repo_ok: { type: "boolean" },
+            head: { type: "string" },
+            current: { type: "string" }
+          },
+          required: ["source_line", "repo_ok", "head", "current"]
+        }
+      }
+    );
+  } catch (e) {
+    return { ok: false, message: "Triage evidence collection failed: " + (e && e.message ? e.message : e) + ". Fail-closed." };
+  }
+  const sourceLine = (triageResult.source_line || "").trim();
+  const current = (triageResult.current || "").trim();
+  const head = (triageResult.head || "").trim();
+
+  // Workflow-side decisions only.
+  let source = null, version = null;
+  if (srcToken === "repo") {
+    source = "repo";
+  } else {
+    const msrc = /^npm@(\S+)$/.exec(srcToken);
+    if (msrc && isValidNpmVersion(msrc[1])) { source = "npm"; version = msrc[1]; }
+  }
+  if (!source) {
+    return { ok: false, message: "Triage rejected: unrecognized upgrade source line: '" + sourceLine + "' — expected 'source: repo' or 'source: npm@<x.y.z>'" };
+  }
+  if (source === "repo") {
+    // Fail closed on a missing repo_path — never silently fall back to
+    // another checkout (the canary's wrong-repo Build, 2026-09-11). The
+    // dispatcher skips unconfigured projects; this is the backstop for
+    // direct launches.
+    if (!REPO_PATH) {
+      return { ok: false, message: "Triage rejected: source is repo but project '" + (inputs.project_id || "unknown") + "' has no repo_path configured — set it via updateproject before dispatching tasks." };
+    }
+    if (!triageResult.repo_ok) {
+      return { ok: false, message: "Triage rejected: repo_path '" + REPO_PATH + "' does not look like a crew repo (workflows dir or lib/crew-release.sh missing)." };
+    }
+  }
+  const t = upgradeTarget(source, version, head);
+  if (!t.ok) {
+    return { ok: false, message: "Triage rejected: " + t.error };
+  }
+  const noOp = decideNoOp(current, t.target);
+  log("Upgrade plan for task " + taskId + ": " + current + " -> " + t.target + " (" + source + ")" + (noOp ? " — idempotent no-op" : ""));
+  await agent(
+    "Log the upgrade plan.\n" +
+    "Run in shell and return the stdout verbatim:\n" + crewCmd("log-event", {
+      task_id: taskId, type: "note", identity: noteIdentity,
+      message: "upgrade plan: " + current + " -> " + t.target + " (" + source + ")" + (noOp ? " — no-op" : "")
+    }) + "\n",
+    { key: evidenceKey + "-plan-note", label: "Logging upgrade plan" }
+  );
+  return { ok: true, plan: { source: source, version: version, target: t.target, current: current }, skipDeploy: noOp };
+}
+
+// Park the task for human attention and end the run. "blocked" is never
+// manually authored — the dashboard derives it mechanically from unmet
+// dependencies — so a workflow outcome that needs a human parks the task
+// instead. Parking is one atomic dashboard action (parktask): the parked
+// state and the explanatory note land in one transaction, never half.
+// The dispatcher skips parked tasks; a human moving parked→todo
+// mechanically resets the retry counters. Returns the workflow result
+// envelope the launcher sees. If the park call itself fails, the run
+// reports "failed" (retryable) so the next tick re-attempts the park —
+// a lost park is never reported as parked.
+// Terminal cleanup: the run's last act at every park/fail boundary. A run
+// that parks or fails must not leak its worktree, branch, or merge lock.
+// The lifecycle's terminal-cleanup releases the lock unconditionally and
+// reclaims the worktree+branch ONLY when the task branch is fully merged
+// into main (then it is redundant); unmerged work is preserved for the
+// human by design. This workflow never acquires the lock or creates a
+// worktree, so the merge-lock release and branch reclamation are harmless
+// no-ops here — the pair is kept verbatim anyway. Fire-and-forget with one
+// bounded retry — the merge-lock lease expiry and the orphan sweep are the
+// backstop for a dead transport.
+async function terminalCleanup() {
+  for (var attempt = 1; attempt <= 2; attempt++) {
+    try {
+      await agent(
+        "Run in shell and return the stdout verbatim:\n" + LIFECYCLE_ENV + " terminal-cleanup " + taskId,
+        { key: "terminal-cleanup" + (attempt > 1 ? "-retry" : ""),
+          label: "Terminal cleanup (merged-branch reclamation)" + (attempt > 1 ? " (retry)" : "") }
+      );
+      return;
+    } catch (cleanupErr) {
+      log("Terminal cleanup attempt " + attempt + " failed for task " + taskId + ": " + (cleanupErr && cleanupErr.message ? cleanupErr.message : cleanupErr));
+    }
+  }
+  log("Terminal cleanup exhausted for task " + taskId + " — merge-lock lease expiry and orphan sweep are the backstop");
+}
+async function parkTask(reason) {
+  log("Parking task " + taskId + " for human attention: " + reason);
+  var parkMessage = ("Parked: " + reason).slice(0, 1000);
+  try {
+    await agent(
+      "Park this task for human attention.\n" +
+      "Run in shell and return the stdout verbatim:\n" + crewCmd("park-task", { task_id: taskId, message: parkMessage }) + "\n" +
+      "The parked state is the human-attention signal — the dispatcher skips parked tasks.",
+      { key: "park-task", label: "Parking task for human attention" }
+    );
+  } catch (parkErr) {
+    log("PARK FAILED for task " + taskId + ": " + (parkErr && parkErr.message ? parkErr.message : parkErr) + " — park did not land, reporting failed so the next tick retries");
+    await terminalCleanup();
+    return { status: "failed", task_id: taskId, reason: "park failed: " + reason, park_failed: true };
+  }
+  await terminalCleanup();
+  await telemetryEnd("parked");
+  return { status: "parked", task_id: taskId, reason: reason };
+}
+// recordPhase(stepName, identity, sessionId, status, notes) — the crew-api
+// composite: session + event in one transaction. One call per phase.
+async function recordPhase(stepName, identity, sessionId, status, notes) {
+  await agent(
+    "Update session and log event.\n" +
+    "Run in shell and return the stdout verbatim:\n" + crewCmd("record-phase", {
+      task_id: taskId,
+      session: { id: sessionId, task_id: taskId, identity: identity, step: stepName, status: status, notes: notes },
+      event: { task_id: taskId, type: status, identity: identity, message: stepName + " " + status + " by " + identity }
+    }) + "\n",
+    { key: "record-" + stepName, label: "Recording " + stepName + " result" }
+  );
+}
+
+// Telemetry: mark run start before anything else (pin timing is the
+// 2026-09-13 mystery — the pin agent took 15m with no visibility).
+await telemetryStart("crew-upgrade");
+
+// ── Pin lifecycle scripts ────────────────────────────────────────────
+// Copy lifecycle scripts into a per-task temp dir so this run is immune
+// to upgrades that land while it's in flight. Verified mechanically:
+// workflow code asserts the five basenames from the verbatim listing —
+// the agent cannot self-certify. Any miss parks the task before Triage.
+// Load-bearing in this workflow: Deploy swaps `current` under the run, so
+// every crew-api call after the pin goes through the OLD release's CLI.
+await telemetryEvent("pin_start");
+const initialPins = parsePinListing(await pinLifecycle("pin-lifecycle"));
+await telemetryEvent("pin_end", "pinned " + initialPins.length + " files");
+const missingInitialPins = PIN_BASENAMES.filter(function (b) { return initialPins.indexOf(b) === -1; });
+if (missingInitialPins.length > 0) {
+  return await parkTask("Lifecycle pin incomplete before Triage — missing " + missingInitialPins.join(", ") + " in " + RUN_LIB + ".");
+}
+log("Lifecycle scripts pinned to " + RUN_LIB);
+// From here on, every crew-api.js invocation uses the pinned copy: immune
+// to a release swap landing mid-flight.
+CREW_API = CREW_API_PINNED;
+log("Crew API pinned to " + CREW_API);
+
+while (i < STEPS.length) {
+  const step = STEPS[i];
+  const isFirstClaim = (i === startStepIndex && reworkCount === 0);
+
+  phase(step.name);
+  log(step.name + " step (" + step.identity + ") for task " + taskId);
+  await telemetryEvent("phase_start", step.name);
+
+  // ── Project-change guard ───────────────────────────────────────────
+  // A task moved to another project mid-run must not keep working in the
+  // old project's repo. Re-read the task's project at every phase
+  // boundary: if it differs from the project this run was dispatched for,
+  // abort the stale run (failed at the rework target) so the dispatcher
+  // re-launches the step with the new project's config. No worktree to
+  // clean up here — this workflow never creates one.
+  if (LAUNCH_PROJECT_ID) {
+    const projectCheck = await agent(
+      "Read this task's current project from the crew API.\n" +
+      "Run in shell and return the stdout verbatim:\n" + crewCmd("get-state", { events_limit: 1 }) + "\n" +
+      "Find the task with id \"" + taskId + "\" in the returned tasks array.\n" +
+      "Return exactly { \"project\": \"<the task's project field, or empty string if absent>\" } and nothing else.",
+      {
+        key: "project-check-" + step.name,
+        label: "Checking project before " + step.name,
+        schema: { type: "object", properties: { project: { type: "string" } }, required: ["project"] }
+      }
+    );
+    const currentProject = (projectCheck && projectCheck.project) ? projectCheck.project : LAUNCH_PROJECT_ID;
+    if (currentProject !== LAUNCH_PROJECT_ID) {
+      const abortMessage = "Task project changed mid-run from '" + LAUNCH_PROJECT_ID + "' to '" + currentProject + "' — aborting stale run. The dispatcher will re-launch from " + REWORK_STEP + " with the new project context.";
+      log(abortMessage);
+      await agent(
+        "Abort the stale run.\n" +
+        "Run in shell and return the stdout verbatim:\n" + crewCmd("record-phase", {
+          task_id: taskId,
+          session: { task_id: taskId, identity: step.identity, step: REWORK_STEP, status: "failed",
+            notes: abortMessage + " No worktree exists — this workflow never creates one." },
+          event: { task_id: taskId, type: "failed", identity: step.identity, message: abortMessage }
+        }) + "\n",
+        { key: "abort-project-change", label: "Aborting stale run (project changed)" }
+      );
+      return { status: "failed", task_id: taskId, reason: abortMessage };
+    }
+  }
+
+  // Self-claim — the dispatcher only recommends; the launched workflow claims
+  // the task as its first action, so a claim can never exist without a launched
+  // agent behind it. If another run claimed the task first (two poll ticks
+  // raced in the window before this run's claim), claimtask returns
+  // claimed:false and this run stands down as a duplicate.
+  let activeSessionId;
+  if (isFirstClaim) {
+    var firstClaimUpdateArgs = { id: taskId, state: "in_progress" };
+    if (WORKFLOW_WAS_NULL && RESOLVED_WORKFLOW) firstClaimUpdateArgs.workflow = RESOLVED_WORKFLOW;
+    const claimResult = await agent(
+      "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", ...(NEXT_PHASE_ROUTED ? { expected_next_phase: NEXT_PHASE_ROUTED } : {}) }) + "\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: \"\" }.",
+      {
+        key: "claim-" + step.name,
+        label: "Claiming " + step.name,
+        schema: {
+          type: "object",
+          properties: { claimed: { type: "boolean" }, session_id: { type: "string" } },
+          required: ["claimed", "session_id"]
+        }
+      }
+    );
+    if (!claimResult.claimed) {
+      log("Standing down — task " + taskId + " was already claimed by another run");
+      await telemetryEnd("duplicate");
+      return { status: "duplicate", task_id: taskId, reason: "task already claimed by another run" };
+    }
+    activeSessionId = claimResult.session_id;
+    await telemetryEvent("claim", step.name + " claimed");
+    // Flush telemetry before proceeding — the claim is a critical point.
+    // If a subsequent agent() fails, we want the claim event persisted.
+    await telemetryFlush();
+  } else {
+    const claimResult = await agent(
+      "Claim a session for this task step.\n" +
+      "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" +
+      "Return the session_id from the response.",
+      {
+        key: "claim-" + step.name,
+        label: "Claiming " + step.name,
+        schema: {
+          type: "object",
+          properties: { session_id: { type: "string" } },
+          required: ["session_id"]
+        }
+      }
+    );
+    activeSessionId = claimResult.session_id;
+  }
+
+  // ── Triage (sage) ──────────────────────────────────────────────────
+  // The agent does shell I/O only and returns a schema'd object. WORKFLOW
+  // CODE re-parses the `source:` line and makes every decision — the
+  // agent's reading is evidence, never the decision.
+  // ── Triage (sage) ──────────────────────────────────────────────────
+  // The agent does shell I/O only and returns a schema'd object. WORKFLOW
+  // CODE re-parses the `source:` line and makes every decision — the
+  // agent's reading is evidence, never the decision.
+  if (step.name === "Triage") {
+    const g = await computeUpgradePlan("triage-evidence", step.identity);
+    if (!g.ok) {
+      await recordPhase("Triage", step.identity, activeSessionId, "rejected", g.message);
+      return await parkTask(g.message);
+    }
+    upgradePlan = g.plan;
+    const t = upgradePlan.target;
+    const source = upgradePlan.source;
+    if (g.skipDeploy) {
+      skipDeploy = true;
+      log("Idempotent no-op for task " + taskId + ": already on " + t + " — skipping Deploy");
+      await agent(
+        "Log the idempotent no-op.\n" +
+        "Run in shell and return the stdout verbatim:\n" + crewCmd("log-event", {
+          task_id: taskId, type: "note", identity: step.identity,
+          message: "already on " + t + " — no-op"
+        }) + "\n",
+        { key: "upgrade-noop-note", label: "Logging idempotent no-op" }
+      );
+      await recordPhase("Triage", step.identity, activeSessionId, "completed",
+        "already on " + t + " — no-op; Deploy skipped, Verify re-checks and passes trivially");
+    } else {
+      await recordPhase("Triage", step.identity, activeSessionId, "completed",
+        "upgrade plan: " + upgradePlan.current + " -> " + t + " (" + source + ")");
+    }
+    i++;
+    continue;
+  }
+
+  // ── Deploy (wren) ──────────────────────────────────────────────────
+  // Single command through the STABLE $CREW_HOME/crew-release.sh: it
+  // self-updates from the source, validates workflow syntax, builds the
+  // registry, and swaps `current` atomically. deploy is documented as
+  // needing no cross-step lock, so Deploy takes no merge lock. No retries,
+  // no auto-rollback — any non-zero exit parks with the exact output and
+  // names `crew-release.sh rollback` as the human recovery path.
+  if (step.name === "Deploy") {
+    if (skipDeploy) {
+      log("Deploy skipped for task " + taskId + " — idempotent no-op, already on " + upgradePlan.target);
+      await recordPhase("Deploy", step.identity, activeSessionId, "completed",
+        "Deploy skipped — already on target " + upgradePlan.target + " (no-op)");
+      i++;
+      continue;
+    }
+    if (!upgradePlan) {
+      // Resumed run: the dispatcher launches at the next step after a
+      // completed Triage, so Triage never re-executes in this process.
+      // Reconstruct the plan deterministically — it is pure evidence +
+      // mechanical decisions, so re-gathering it is safe. Fail closed only
+      // when the evidence itself cannot be gathered.
+      log("Deploy reached with no upgrade plan — reconstructing on resumed run.");
+      const rg = await computeUpgradePlan("triage-evidence-reconstruct", step.identity);
+      if (!rg.ok) {
+        return await parkTask("Deploy reached with no upgrade plan and reconstruction failed: " + rg.message + " Fail-closed.");
+      }
+      upgradePlan = rg.plan;
+      skipDeploy = rg.skipDeploy;
+    }
+    const stagingDir = crewHome + "/.upgrade-staging/" + upgradePlan.version;
+    const deployShell =
+      (upgradePlan.source === "repo")
+        ? DEPLOY_SCRIPT + " deploy " + REPO_PATH + " " + crewHome
+        : "STAGING=\"" + stagingDir + "\" && mkdir -p \"$STAGING\" && cd \"$STAGING\" && npm init -y >/dev/null 2>&1 && npm install muse-crew@" + upgradePlan.version;
+    const deploySteps =
+      "1. Run the install (npm source only):\n" + (upgradePlan.source === "repo" ? "   (skipped — repo source has nothing to install)\n" : "   " + deployShell + "\n") +
+      "2. Run the deploy:\n   " + (upgradePlan.source === "repo"
+        ? deployShell
+        // Explicit validated package-root path — crew-release.sh reads
+        // workflows/, lib/ and package.json from the directory it is given,
+        // so the deploy source is the installed package root, not the
+        // staging root. Do not rely on a $STAGING shell variable persisting
+        // between separate shell invocations.
+        : DEPLOY_SCRIPT + " deploy \"" + stagingDir + "/node_modules/muse-crew\" " + crewHome) +
+      " — capture ALL of the command's output and its exit code (run the command, then echo EXIT_CODE=$?).\n" +
+      (upgradePlan.source === "npm"
+        ? "3. Remove the staging dir: rm -rf \"" + stagingDir + "\" — best-effort, ALWAYS, even when the deploy fails. Log whether the removal succeeded. Never let cleanup change the deploy outcome.\n"
+        : "") +
+      "Do not run git checkout, git pull, or any repo-mutating command. Do not publish to npm — the npm source only INSTALLS the published package. Do not touch the scheduler.";
+    var deployResult;
+    try {
+      deployResult = await agent(
+        TOOL_CHECK_PREAMBLE +
+        "Run the crew upgrade deploy. This step performs the release swap — the workflow decides everything from the values you return.\n" +
+        deploySteps + "\n" +
+        "Return JSON { \"exit\": <the deploy command's exit code as an integer>, \"output\": \"<the deploy command's full output, trimmed>\" } and nothing else.",
+        {
+          key: "deploy-run",
+          label: "Deploying crew upgrade (" + upgradePlan.source + ")",
+          schema: {
+            type: "object",
+            properties: {
+              exit: { type: "number" },
+              output: { type: "string" }
+            },
+            required: ["exit", "output"]
+          }
+        }
+      );
+    } catch (e) {
+      return await parkTask("Deploy agent call failed: " + (e && e.message ? e.message : e) + ". Fail-closed — the deploy outcome is unknown; human recovery path: " + DEPLOY_SCRIPT + " rollback " + crewHome);
+    }
+    const deployExit = deployResult.exit;
+    const deployOutput = (deployResult.output || "").trim();
+    if (deployExit !== 0) {
+      const msg = "Deploy failed (exit " + deployExit + "). Human recovery path: " + DEPLOY_SCRIPT + " rollback " + crewHome + ". Deploy output: " + deployOutput;
+      await recordPhase("Deploy", step.identity, activeSessionId, "failed", msg);
+      return await parkTask(msg);
+    }
+    log("Deploy succeeded for task " + taskId + " — target " + upgradePlan.target);
+    await recordPhase("Deploy", step.identity, activeSessionId, "completed",
+      "deployed " + upgradePlan.target + " (" + upgradePlan.source + ")\ndeploy output:\n" + deployOutput.slice(0, 1500));
+    i++;
+    continue;
+  }
+
+  // ── Verify (wren — mechanical, no LLM judgment) ─────────────────────
+  // Three mechanical checks, each a schema'd agent() shell call. The agent
+  // never writes "looks good" — the WORKFLOW evaluates pass/fail from the
+  // returned values. Handover is automatic: the next poll tick launches the
+  // dispatcher through the `current` symlink, i.e. the new release.
+  if (step.name === "Verify") {
+    if (!upgradePlan) {
+      // Resumed run at Verify (Deploy completed in a prior run):
+      // reconstruct the plan deterministically, as in Deploy.
+      log("Verify reached with no upgrade plan — reconstructing on resumed run.");
+      const rg = await computeUpgradePlan("triage-evidence-reconstruct", step.identity);
+      if (!rg.ok) {
+        return await parkTask("Verify reached with no upgrade plan and reconstruction failed: " + rg.message + " Fail-closed.");
+      }
+      upgradePlan = rg.plan;
+      skipDeploy = rg.skipDeploy;
+    }
+    const target = upgradePlan.target;
+    const old = upgradePlan.current;
+
+    // Check 1: the live release identity equals the target.
+    var curCheck;
+    try {
+      curCheck = await agent(
+        TOOL_CHECK_PREAMBLE +
+        "Read the live release identity.\n" +
+        "Run: " + DEPLOY_SCRIPT + " current " + crewHome + "\n" +
+        "Return JSON { \"current\": \"<trimmed stdout>\" } and nothing else.",
+        {
+          key: "verify-current",
+          label: "Verifying live release",
+          schema: {
+            type: "object",
+            properties: { current: { type: "string" } },
+            required: ["current"]
+          }
+        }
+      );
+    } catch (e) {
+      return await parkTask("Verify failed — check 1 (crew-release.sh current): agent call failed (" + (e && e.message ? e.message : e) + "). Fail-closed.");
+    }
+    const liveCurrent = (curCheck.current || "").trim();
+    if (liveCurrent !== target) {
+      const msg = "Verify failed — check 1 (crew-release.sh current): live release '" + liveCurrent + "' != target '" + target + "'";
+      await recordPhase("Verify", step.identity, activeSessionId, "rejected", msg);
+      return await parkTask(msg);
+    }
+    log("Verify check 1 passed for task " + taskId + ": current == target (" + target + ")");
+
+    // Check 2: the deployed registry parses as JSON. For the repo source it
+    // must contain the "upgrade" key (the release was built from a repo
+    // containing this workflow); npm releases predating the upgrade
+    // workflow are still valid upgrades and are only required to parse.
+    var regCheck;
+    try {
+      regCheck = await agent(
+        TOOL_CHECK_PREAMBLE +
+        "Read the deployed registry.\n" +
+        "Run: cat " + crewHome + "/workflows/registry.json\n" +
+        "Return JSON { \"raw\": \"<the file's full content, verbatim>\" } and nothing else.",
+        {
+          key: "verify-registry",
+          label: "Reading deployed registry",
+          schema: {
+            type: "object",
+            properties: { raw: { type: "string" } },
+            required: ["raw"]
+          }
+        }
+      );
+    } catch (e) {
+      return await parkTask("Verify failed — check 2 (registry.json): agent call failed (" + (e && e.message ? e.message : e) + "). Fail-closed.");
+    }
+    let regOk = false, regHasUpgrade = false;
+    try {
+      const regParsed = JSON.parse(regCheck.raw || "");
+      regOk = true;
+      regHasUpgrade = !!(regParsed && regParsed.upgrade);
+    } catch (e) {
+      regOk = false;
+    }
+    if (!regOk) {
+      const msg = "Verify failed — check 2 (registry.json): " + crewHome + "/workflows/registry.json does not parse as JSON";
+      await recordPhase("Verify", step.identity, activeSessionId, "rejected", msg);
+      return await parkTask(msg);
+    }
+    if (upgradePlan.source === "repo" && !regHasUpgrade) {
+      const msg = "Verify failed — check 2 (registry.json): parses as JSON but has no \"upgrade\" key — the deployed release was not built from a repo containing this workflow";
+      await recordPhase("Verify", step.identity, activeSessionId, "rejected", msg);
+      return await parkTask(msg);
+    }
+    log("Verify check 2 passed for task " + taskId + ": registry.json parses" + (upgradePlan.source === "repo" ? " and carries the upgrade key" : ""));
+
+    // Check 3: the crew DB is readable by the OLD release's CLI. Use the
+    // PINNED copy explicitly: the workflow swapped `current` under itself
+    // at Deploy, so the live path may already point at the new release.
+    // The new release's CLI is exercised by the next tick's dispatcher,
+    // not here.
+    var gsCheck;
+    try {
+      gsCheck = await agent(
+        TOOL_CHECK_PREAMBLE +
+        "Check the crew database is readable by the OLD release's CLI. Use the PINNED path below — NOT " + crewHome + "/current — because the workflow swapped `current` under itself at Deploy and the live path may already point at the new release.\n" +
+        "Run: node " + CREW_API_PINNED + " --crew-home " + crewHome + " get-state --json '{}'; echo EXIT_CODE=$?\n" +
+        "Return JSON { \"exit\": <the exit code as an integer> } and nothing else.",
+        {
+          key: "verify-get-state",
+          label: "Verifying crew DB readability (pinned CLI)",
+          schema: {
+            type: "object",
+            properties: { exit: { type: "number" } },
+            required: ["exit"]
+          }
+        }
+      );
+    } catch (e) {
+      return await parkTask("Verify failed — check 3 (pinned crew-api.js get-state): agent call failed (" + (e && e.message ? e.message : e) + "). Fail-closed.");
+    }
+    if (gsCheck.exit !== 0) {
+      const msg = "Verify failed — check 3 (pinned crew-api.js get-state): exit " + gsCheck.exit + " — the crew DB is not readable by the pinned old-release CLI";
+      await recordPhase("Verify", step.identity, activeSessionId, "rejected", msg);
+      return await parkTask(msg);
+    }
+    log("Verify check 3 passed for task " + taskId + ": pinned crew-api.js get-state exits 0");
+
+    await agent(
+      "Log the completed upgrade.\n" +
+      "Run in shell and return the stdout verbatim:\n" + crewCmd("log-event", {
+        task_id: taskId, type: "note", identity: step.identity,
+        message: "upgrade: " + old + " -> " + target + " (" + upgradePlan.source + ")"
+      }) + "\n",
+      { key: "upgrade-done-note", label: "Logging completed upgrade" }
+    );
+    await recordPhase("Verify", step.identity, activeSessionId, "completed",
+      "all three checks passed: current == " + target + ", registry.json valid" +
+      (upgradePlan.source === "repo" ? " (carries upgrade key)" : "") +
+      ", pinned crew-api.js get-state exits 0" +
+      (skipDeploy ? " (idempotent no-op — Deploy skipped)" : ""));
+    i++;
+    continue;
+  }
+
+  // Unreachable: STEPS is fixed, but fail closed on an unknown step.
+  return await parkTask("Unknown step '" + step.name + "' in crew-upgrade. Fail-closed.");
+}
+
+await agent(
+  "Mark this task as done.\n" +
+  "Run in shell and return the stdout verbatim:\n" + crewCmd("update-task", { id: taskId, state: "done" }) + "\n" +
+  "Then run in shell and return the stdout verbatim:\n" + crewCmd("log-event", {
+    task_id: taskId, type: "completed",
+    message: "Crew self-upgrade complete: " + upgradePlan.current + " -> " + upgradePlan.target + " (" + upgradePlan.source + "). Handover is automatic: the next poll tick launches the dispatcher through the `current` symlink, i.e. the new release."
+  }),
+  { key: "task-done", label: "Completing task: " + taskTitle }
+);
+
+log("Crew self-upgrade complete for task " + taskId + ": " + upgradePlan.current + " -> " + upgradePlan.target);
+await telemetryEnd("completed");
+await agent("Clean up pinned lifecycle scripts: rm -rf " + RUN_LIB, { key: "cleanup-pins", label: "Cleaning pinned scripts" });
+return { status: "ok", task_id: taskId, message: "Crew self-upgrade complete: " + upgradePlan.current + " -> " + upgradePlan.target + " (" + upgradePlan.source + ")" };