muse-crew 0.7.20 → 0.8.0

package/lib/worktree-lifecycle.sh

@@ -6,13 +6,18 @@
 # worktree strategy lives — workflows and agents never run raw git worktree
 # commands; they call these lifecycle commands instead.
 #
-# The crew's registry ($REPO/.worktrees/.registry/<task_id>) is the source
-# of truth for task→branch/path. Never reconstruct the mapping from git
-# state alone.
+# The crew's registry ($REPO/.worktrees/.registry/<task_id>) is the first
+# source of truth for task→branch/path. When the registry is empty (a
+# Build agent created the branch with raw git from an abbreviated id,
+# bypassing prepare — task 4e1a1bba, 2026-09-17), resolve_branch() falls
+# back to enumerating refs: the canonical task/<full-id> ref wins, then a
+# task/<id-prefix> ref is tolerated (matched by strict prefix, never
+# created). Canonical stays task/<full-id>; ambiguous prefixes fail closed.
 #
 # Commands:
 #   validate  <task_id>                  — check task ID is safe for branches/paths
 #   prepare   <task_id>                  — create worktree + branch, register ownership
+#   resolve-branch <task_id>             — print the resolved task branch name
 #   inspect   <task_id>                  — diff against main for review
 #   integrate <task_id> <commit_msg>     — merge lock → merge into main → report commit
 #   verify-merge <task_id>              — confirm the task branch tip is an ancestor of main (post-step merge check)
@@ -63,15 +68,47 @@ MERGE_RECORDS_DIR="$CREW_HOME/.merge-records"
 
 # --- helpers ---
 
-# Task branch name: task/<id>. The registry wins when the task was
-# prepared before.
+# Task branch name. Resolution order (task 4e1a1bba, 2026-09-17):
+#   1. the registry — prepare writes the branch it created;
+#   2. the canonical task/<full-id> ref, when it exists;
+#   3. a task/<id-prefix> ref, matched by strict literal prefix over
+#      refs/heads/task/ — tolerated, never created. Build and Integrate
+#      therefore agree on the branch name even when Build bypassed
+#      prepare with an abbreviated id.
+# When nothing matches, the canonical name is returned anyway so callers
+# keep their "branch X does not exist" failure (and verify-merge's merge-
+# record fallback) instead of failing on an empty name. Ambiguous prefixes
+# fail closed (exit 1).
 resolve_branch() {
   local task_id="$1" b
   if [ -f "$REGISTRY_DIR/$task_id" ]; then
     b=$(grep '^branch=' "$REGISTRY_DIR/$task_id" | cut -d= -f2-)
     if [ -n "$b" ]; then printf '%s' "$b"; return 0; fi
   fi
-  printf 'task/%s' "$task_id"
+  local canonical="task/$task_id"
+  if git -C "$REPO" rev-parse --verify "$canonical" >/dev/null 2>&1; then
+    printf '%s' "$canonical"; return 0
+  fi
+  local matches=() ref stripped
+  while IFS= read -r ref; do
+    [ -n "$ref" ] || continue
+    [ "$ref" = "$canonical" ] && continue
+    # Strict literal prefix: ref must be a proper prefix of the canonical
+    # name. The quoted expansion keeps the pattern literal (task ids are
+    # [a-zA-Z0-9_-], but literal is literal).
+    stripped="${canonical#"$ref"}"
+    if [ "$stripped" != "$canonical" ]; then
+      matches+=("$ref")
+    fi
+  done < <(git -C "$REPO" for-each-ref --format='%(refname:short)' 'refs/heads/task/')
+  if [ "${#matches[@]}" -eq 1 ]; then
+    printf '%s' "${matches[0]}"; return 0
+  fi
+  if [ "${#matches[@]}" -gt 1 ]; then
+    echo "ERROR: task id '$task_id' matches multiple task branches: ${matches[*]} — ambiguous, refusing to guess" >&2
+    return 1
+  fi
+  printf '%s' "$canonical"
 }
 
 # Worktree path: $REPO/.worktrees/<id>. The registry wins when the task
@@ -168,6 +205,17 @@ cmd_prepare() {
   echo "BASE: $base_commit"
 }
 
+# Agent-side one-liner: $(worktree-lifecycle.sh resolve-branch <id>) prints
+# the branch Build and Integrate must agree on. Mechanical — no agent call
+# per phase needed (task 4e1a1bba). Exits 1 on an ambiguous prefix.
+cmd_resolve_branch() {
+  local task_id="$1"
+  validate_task_id "$task_id"
+  local branch
+  branch=$(resolve_branch "$task_id")
+  echo "$branch"
+}
+
 cmd_inspect() {
   local task_id="$1"
   validate_task_id "$task_id"
@@ -373,7 +421,12 @@ cmd_post_deploy() {
   final_commit=$(git rev-parse HEAD)
 
   # Cleanup worktree + branch — report honestly: a failed removal must
-  # never print success (a lying "removed" hid real leftovers).
+  # never print success (a lying "removed" hid real leftovers). The branch
+  # is resolved, never reconstructed: a Build agent may have created it
+  # from an abbreviated id (task 4e1a1bba) and deleting "task/<full-id>"
+  # would leave the real branch behind.
+  local branch
+  branch=$(resolve_branch "$task_id")
   if [ -d "$WORKTREE_DIR/$task_id" ]; then
     if git worktree remove "$WORKTREE_DIR/$task_id" 2>/dev/null; then
       echo "WORKTREE: removed"
@@ -382,7 +435,7 @@ cmd_post_deploy() {
     fi
   fi
   git worktree prune 2>/dev/null
-  git branch -d "task/$task_id" 2>/dev/null && echo "BRANCH: deleted" || true
+  git branch -d "$branch" 2>/dev/null && echo "BRANCH: deleted" || true
   unregister "$task_id"
 
   # Release merge lock
@@ -480,7 +533,11 @@ cmd_cleanup() {
     echo "WORKTREE: not found (already clean)"
   fi
   git worktree prune 2>/dev/null
-  git branch -D "task/$task_id" 2>/dev/null && echo "BRANCH: deleted" || true
+  # Resolve, never reconstruct: the branch may live under an abbreviated
+  # id (task 4e1a1bba).
+  local branch
+  branch=$(resolve_branch "$task_id")
+  git branch -D "$branch" 2>/dev/null && echo "BRANCH: deleted" || true
   unregister "$task_id"
   echo "CLEANUP: done"
 }
@@ -569,6 +626,7 @@ shift || true
 case "$cmd" in
   validate)     cmd_validate "${1:?task_id required}" ;;
   prepare)      cmd_prepare "${1:?task_id required}" ;;
+  resolve-branch) cmd_resolve_branch "${1:?task_id required}" ;;
   inspect)      cmd_inspect "${1:?task_id required}" ;;
   integrate)    cmd_integrate "${1:?task_id required}" "${2:-}" ;;
   verify-merge) cmd_verify_merge "${1:?task_id required}" ;;
@@ -581,7 +639,7 @@ case "$cmd" in
   merge-record) cmd_merge_record "${1:?task_id required}" ;;
   *)
     echo "Usage: worktree-lifecycle.sh <command> [args]"
-    echo "Commands: validate, prepare, inspect, integrate, verify-merge, post-deploy, terminal-cleanup, cleanup, status, refresh-lock, lock-status, merge-record"
+    echo "Commands: validate, prepare, resolve-branch, inspect, integrate, verify-merge, post-deploy, terminal-cleanup, cleanup, status, refresh-lock, lock-status, merge-record"
     exit 1
     ;;
 esac

package/package.json

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

package/seed/AGENTS.md

@@ -4,6 +4,7 @@ Init source data. Everything `crew-init.js` reads when setting up a new crew ins
 
 - `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-body-update-watch.md` — template for the daily `crew-update-watch` cron job: runs `lib/update-watch.js --crew-home {crewHome}` verbatim and reports stdout
 - `posture.md` — PM posture that shapes the user's assistant for crew interaction
 - `feedback/` — feedback feature placeholder
 - `workflows/` — human-readable workflow definitions, copied to `$CREW_HOME/.orchestration/workflows/` during init

package/seed/cron-body-update-watch.md

@@ -0,0 +1,13 @@
+## Muse Crew update watch
+
+You are the update watcher. Run the deterministic check and report its output.
+
+### Steps
+
+1. Run verbatim:
+   node {crewHome}/current/lib/update-watch.js --crew-home {crewHome}
+   The script exits 0 on every path. Check failures are logged to
+   {crewHome}/update-watch.log and reported on stdout — never thrown.
+2. Report the script's stdout verbatim. Do not summarize, do not judge, do
+   not file tasks yourself — the watcher files through the Crew API when
+   policy and idempotency allow.

package/seed/crons.json

@@ -5,13 +5,26 @@
       "enabled": true,
       "id": "crew-poll",
       "mode": "task",
-      "owner": "space:{dashboardSlug}",
+      "owner": "cli:{instanceId}",
       "schedule": {
         "every": "15m",
         "kind": "interval"
       },
       "timeout_secs": 5400,
       "title": "Muse Crew polling loop"
+    },
+    {
+      "body_template": "cron-body-update-watch.md",
+      "enabled": true,
+      "id": "crew-update-watch",
+      "mode": "task",
+      "owner": "cli:{instanceId}",
+      "schedule": {
+        "every": "24h",
+        "kind": "interval"
+      },
+      "timeout_secs": 600,
+      "title": "Muse Crew automatic update watcher"
     }
   ],
   "version": 1

package/seed/workflows/upgrade.md

@@ -0,0 +1,21 @@
+# Upgrade
+
+Upgrade the crew itself through its own dispatch loop. The task description carries a `source:` line naming the upgrade source — `repo` (default, the task project's repo HEAD) or `npm@<x.y.z>` (the published npm package). The stable `crew-release.sh` deploys, the workflow verifies mechanically, and handover to the new release is automatic on the next tick.
+
+## Steps
+
+### Triage
+**Identity:** Sage
+Validate the `source:` line (exactly `repo`, or `npm@<x.y.z>` — anything else parks fail-closed), verify the repo checkout and resolve `git rev-parse HEAD` for repo source, read the live release via `crew-release.sh current`, and compute the target. If the crew is already on the target, record the idempotent no-op and skip Deploy.
+
+### Deploy
+**Identity:** Wren
+Run the stable `$CREW_HOME/crew-release.sh deploy` — against the repo HEAD for repo source, or against a staging dir under `$CREW_HOME/.upgrade-staging/<version>` (public npm install only) for npm source. Single command, no merge lock. Any non-zero exit parks fail-closed with the exact output; no retry, no auto-rollback — `crew-release.sh rollback` is the human recovery path.
+
+### Verify
+**Identity:** Wren
+Mechanical, no LLM judgment: (1) `crew-release.sh current` equals the target; (2) `<crewHome>/workflows/registry.json` parses as JSON — and for repo source carries the `upgrade` key (npm releases predating the upgrade workflow are still valid upgrades); (3) `crew-api get-state` works via the pinned old-release CLI. Handover is automatic: the next poll tick launches the dispatcher through the `current` symlink, i.e. the new release. In-flight runs finish on the old release via per-task lib pinning.
+
+## Safety
+
+Never mutate the crew repo — repo source always means the repo's current HEAD. Never publish to npm — the npm source only installs the published package. Never touch the scheduler. Fail closed everywhere.

package/workflows/AGENTS.md

@@ -5,7 +5,7 @@ Executable Muse workflow scripts (JavaScript). These are what the workflow runti
 - `crew-dispatch.js` — reads the board, recommends eligible tasks, returns structured launch records (the launched workflow self-claims; the dispatcher never writes claims). Skips tasks on quiesced projects and on projects with no repo_path configured.
 
 All four workflow scripts share byte-identical transport helpers (`workRetryKey`, `buildTransportRetryTrailer`, `describeWorkAgentFailure`, `workerMissingArtifactTools` — pinned by `tests/closeout.test.js`). The transport-retry loop treats a worker report naming the missing artifact tool namespace (bug 3472bf36, a per-launch platform flake) as a retryable attempt with a fresh launch rather than accepting a useless report.
-- `crew-init.js` — sets up a new crew instance: Gate 0 validates crewHome is workspace-contained and a valid git repo, and (in dashboard mode) validates dashboardRepoPath is workspace-contained and an existing git repo (never auto-created); bootstraps the release system; scaffolds orchestration folders; registers the first project with repo_path set to the validated dashboard repo — skipped in CLI-only mode (no dashboardSlug/dashboardRepoPath), where projects are created later via crew-api.js; creates/converges cron jobs from the declarative manifest (owner `space:<slug>` in dashboard mode, `cli:<crew-home-basename>` in CLI-only mode). Idempotent. The crew owns its state via the Crew API (lib/crew-api.js); the dashboard is an optional client and is never a dependency.
+- `crew-init.js` — sets up a new crew instance: Gate 0 validates crewHome is workspace-contained and a valid git repo, and (in dashboard mode) validates dashboardRepoPath is workspace-contained and an existing git repo (never auto-created); bootstraps the release system; scaffolds orchestration folders; registers the first project with repo_path set to the validated dashboard repo — skipped in CLI-only mode (no dashboardSlug/dashboardRepoPath), where projects are created later via crew-api.js; creates/converges cron jobs from the declarative manifest (scheduler identity is dashboard-independent: first init uses the crew-home basename, re-runs keep the instanceId recorded in `.cron-registry.json`; owner `cli:<instanceId>` — deleting a dashboard artifact never stops the crew). Idempotent. The crew owns its state via the Crew API (lib/crew-api.js); the dashboard is an optional client and is never a dependency.
 - `standard.js` — default task workflow: Triage → Capture → Map → Build → Review → Integrate → Publish → QA
 - `bugfix.js` — adds Capture after Triage, then Reproduce
 - `chore.js` — adds Capture after Triage, drops QA (low-risk)