muse-crew 0.4.4 → 0.4.5

package/API.md

@@ -71,14 +71,14 @@ Send a stuck or failed task to a specific workflow phase for recovery.
 
 ### `parktask`
 
-Atomically park a task for human attention: sets `state` to `parked` and writes the explanatory `note` event in one transaction. Either both land or neither does — callers never see a note without a park or a park without a note. The dispatcher skips parked tasks; moving the task back to `todo` is the human re-queue path (which stamps `retry_reset_at` — see `updatetask`).
+Atomically park a task for human attention: sets `state` to `parked`, writes the explanatory `note` event, and settles every `running` session for the task — in one transaction. Either all land or none do: callers never see a note without a park, a park without a note, or a parked task with a ghost `running` session left behind (a terminal task transition settles its sessions). Settled sessions move to `failed` — the status `recovertask` accepts, so recovery works immediately after a park — with `ended_at` stamped and `Parked: <message>` appended to their notes; `failure_reason` stays null.
 
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
 | `task_id` | uuid | yes | |
 | `message` | string (1–1000) | yes | Why the task needs a human; written to the activity feed as a `note` |
 
-Returns `{ "ok": true, "task": {...} }` with the updated task record.
+Returns `{ "ok": true, "task": {...}, "settled_sessions": <n> }` with the updated task record and the count of sessions settled (`0` when none were running).
 
 ---
 

package/lib/AGENTS.md

@@ -8,6 +8,7 @@ Shell scripts for the crew's infrastructure. Called by workflow scripts, cron, a
 - `worktree-lifecycle.sh` — the worktree lifecycle seam: prepare/cleanup/inspect/integrate/status/post-deploy over git worktrees (`.worktrees/<id>`, branch `task/<id>`). The crew registry (`<repo>/.worktrees/.registry/<id>`) is the source of truth for task→branch/path — never reconstruct it from git state. Prepare fails closed on dirty `main`; cleanup is forgiving.
 - `test-worktree-backend.sh` — regression tests for the lifecycle script (validate, prepare/reuse, inspect, status, cleanup, idempotent cleanup, dirty-main preflight) on a scratch repo
 - `test-version-write.sh` — regression tests for the escape-preserving step-8 version write in publish-npm.sh (fixture: current package.json with the \u2014 escape; extracts the shipped block by anchor)
+- `test-publish-verify.sh` — regression tests for the retry-tolerant step-12 verification in publish-npm.sh (canary 5a027278): extracts the shipped block by anchor and runs it against a fake npm whose read replica lags (non-zero exits, then the old version, then the target) — requires convergence on success, fail-closed `PUBLISH_FAILED=verify` on exhaustion, and `--prefer-online` on every read
 - `orphan-sweep.sh` — find and clean stale worktrees and merge locks
 - `publish-npm.sh` — deterministic npm publish: lock refresh, release install, version write/commit, pack, registry publish, verify, push, post-deploy. Takes TARGET_VERSION as input; idempotent on retry/resume.
 - `compose-evidence.py` — deterministic visual-evidence compositor (Pillow): pairs identical PNG stems from baseline/ and postchange/ dirs, emits `<stem>-sidebyside.png` and amplified-difference `<stem>-overlay.png` into composites/, prints `PAIR`/`SKIP` manifests. Byte-deterministic; nonzero exit on errors.

package/lib/publish-npm.sh

@@ -150,11 +150,28 @@ if [ "$ALREADY_PUBLISHED" = "0" ]; then
   rm -f "$TGZ"
 
   # 12. Verify: ground truth is the registry, not any agent's summary.
-  REG="$(npm view "$PKG" version 2>/dev/null)" \
-    || fail "verify" "npm view $PKG failed"
+  # The registry is eventually consistent: a publish followed by an
+  # immediate read can observe the pre-publish version (canary 5a027278
+  # hit a stale read replica ~6s after publish). A single stale read must
+  # never park a landed publish, so this block retries with backoff and
+  # client cache-busting instead of failing on the first mismatch.
+  # STEP-12-ANCHOR: publish verification (retry-tolerant)
+  VERIFY_ATTEMPTS="${VERIFY_ATTEMPTS:-12}"
+  VERIFY_SLEEP_SECS="${VERIFY_SLEEP_SECS:-10}"
+  REG=""
+  for attempt in $(seq 1 "$VERIFY_ATTEMPTS"); do
+    # --prefer-online busts npm's client-side packument cache; the retry
+    # loop absorbs server-side replica lag. A non-zero exit is a miss,
+    # not an immediate failure.
+    REG="$(npm view "$PKG" version --prefer-online 2>/dev/null || true)"
+    [ "$REG" = "$TARGET_VERSION" ] && break
+    echo "PUBLISH_VERIFY_RETRY=$attempt registry=$REG"
+    [ "$attempt" -lt "$VERIFY_ATTEMPTS" ] && sleep "$VERIFY_SLEEP_SECS"
+  done
   [ "$REG" = "$TARGET_VERSION" ] \
-    || fail "verify" "registry=$REG"
+    || fail "verify" "registry=$REG after $VERIFY_ATTEMPTS attempts"
   echo "PUBLISH_VERIFIED=$TARGET_VERSION"
+  # STEP-12-END
 fi
 
 # 13. Push the version-bump commit (idempotent: no-op if already pushed).

package/lib/test-publish-verify.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# test-publish-verify.sh — regression test for the retry-tolerant step-12
+# publish verification in publish-npm.sh (canary 5a027278).
+#
+# Self-contained: extracts the shipped step-12 block from lib/publish-npm.sh
+# by anchor and runs it against a fake `npm` on PATH whose read replica
+# lags — non-zero exits, then the old version, then the target version —
+# and requires the block to converge on success. Also asserts fail-closed
+# exhaustion when the replica never converges.
+#
+# Anchors: `# STEP-12-ANCHOR` ... `# STEP-12-END` in lib/publish-npm.sh.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PUBLISH="$SCRIPT_DIR/publish-npm.sh"
+
+PKG="muse-crew"
+OLD_VERSION="9.9.8"
+TARGET_VERSION="9.9.9"
+
+pass=0
+fail_count=0
+ok() { echo "PASS: $1"; pass=$((pass + 1)); }
+no() { echo "FAIL: $1"; fail_count=$((fail_count + 1)); }
+
+TMPBASE="$(mktemp -d)"
+trap 'rm -rf "$TMPBASE"' EXIT
+
+# --- Extract the shipped step-12 block by anchor ---
+BLOCK="$TMPBASE/step12.sh"
+sed -n '/# STEP-12-ANCHOR/,/# STEP-12-END/p' "$PUBLISH" > "$BLOCK"
+if grep -q 'PUBLISH_VERIFIED' "$BLOCK" && grep -q 'fail "verify"' "$BLOCK"; then
+  ok "extracted step-12 block from publish-npm.sh"
+else
+  no "step-12 extraction failed (anchors missing)"
+fi
+
+# --- Runner: fake npm first in PATH, behavior baked in at generation time ---
+FAKEBIN="$TMPBASE/fakebin"
+mkdir -p "$FAKEBIN"
+
+# write_fake_npm <behavior>
+#   laggy: exit 1 twice (npm failure), old version twice (stale replica),
+#          then the target version (replica converged)
+#   stale: old version forever (replica never converges)
+write_fake_npm() {
+  case "$1" in
+    laggy) BEHAVIOR='
+      if [ "$n" -le 2 ]; then exit 1; fi
+      if [ "$n" -le 4 ]; then echo "'"$OLD_VERSION"'"; exit 0; fi
+      echo "'"$TARGET_VERSION"'"; exit 0' ;;
+    stale) BEHAVIOR='echo "'"$OLD_VERSION"'"; exit 0' ;;
+    *) echo "unknown behavior: $1" >&2; exit 1 ;;
+  esac
+  cat > "$FAKEBIN/npm" <<EOF
+#!/usr/bin/env bash
+# Records its own argv (for the cache-busting assertion) and its call count.
+echo "\$*" >> "$TMPBASE/argv"
+n=\$(cat "$TMPBASE/calls" 2>/dev/null || echo 0)
+n=\$((n + 1))
+echo "\$n" > "$TMPBASE/calls"
+$BEHAVIOR
+EOF
+  chmod +x "$FAKEBIN/npm"
+}
+
+# run_step12: runs the shipped block; env: PKG TARGET_VERSION
+# VERIFY_ATTEMPTS VERIFY_SLEEP_SECS; returns the block's exit code and
+# captures its stdout in $OUT.
+run_step12() {
+  local runner="$TMPBASE/run-$RANDOM.sh"
+  {
+    echo 'fail() { echo "PUBLISH_FAILED=$1"; shift; echo "$1"; exit 1; }'
+    cat "$BLOCK"
+  } > "$runner"
+  chmod +x "$runner"
+  rm -f "$TMPBASE/calls" "$TMPBASE/argv"
+  OUT="$(PATH="$FAKEBIN:$PATH" \
+    PKG="$PKG" TARGET_VERSION="$TARGET_VERSION" \
+    VERIFY_ATTEMPTS="${VERIFY_ATTEMPTS:-12}" \
+    VERIFY_SLEEP_SECS="${VERIFY_SLEEP_SECS:-0}" \
+    bash "$runner" 2>&1)"
+  local code=$?
+  echo "$OUT"
+  return "$code"
+}
+
+# --- Case 1: lagging replica converges — block must succeed ---
+write_fake_npm laggy
+OUT="$(run_step12)"
+CODE=$?
+if [ "$CODE" -eq 0 ]; then
+  ok "laggy replica converges: block exits 0"
+else
+  no "laggy replica converges: block exited $CODE (output: $OUT)"
+fi
+case "$OUT" in
+  *"PUBLISH_VERIFIED=$TARGET_VERSION"*)
+    ok "prints PUBLISH_VERIFIED=$TARGET_VERSION on convergence" ;;
+  *) no "missing PUBLISH_VERIFIED=$TARGET_VERSION (output: $OUT)" ;;
+esac
+case "$OUT" in
+  *"PUBLISH_FAILED"*) no "PUBLISH_FAILED printed despite convergence" ;;
+  *) ok "no PUBLISH_FAILED on convergence" ;;
+esac
+CALLS="$(cat "$TMPBASE/calls" 2>/dev/null || echo 0)"
+if [ "$CALLS" = "5" ]; then
+  ok "converged after exactly 5 reads (2 failures, 2 stale, 1 good)"
+else
+  no "expected 5 npm calls on convergence, saw $CALLS"
+fi
+RETRIES="$(grep -c 'PUBLISH_VERIFY_RETRY=' <<< "$OUT" || true)"
+if [ "$RETRIES" = "4" ]; then
+  ok "prints a PUBLISH_VERIFY_RETRY progress line per miss"
+else
+  no "expected 4 PUBLISH_VERIFY_RETRY lines, saw $RETRIES"
+fi
+
+# --- Case 2: replica never converges — fail closed with the verify marker ---
+write_fake_npm stale
+VERIFY_ATTEMPTS=3 OUT="$(run_step12)"
+CODE=$?
+if [ "$CODE" -ne 0 ]; then
+  ok "stale replica: block fails closed (non-zero exit)"
+else
+  no "stale replica: block exited 0 despite persistent mismatch"
+fi
+case "$OUT" in
+  *"PUBLISH_FAILED=verify"*)
+    ok "exhaustion keeps the PUBLISH_FAILED=verify marker contract" ;;
+  *) no "missing PUBLISH_FAILED=verify (output: $OUT)" ;;
+esac
+case "$OUT" in
+  *"registry=$OLD_VERSION after 3 attempts"*)
+    ok "exhaustion detail names registry value and attempt count" ;;
+  *) no "missing exhaustion detail (output: $OUT)" ;;
+esac
+CALLS="$(cat "$TMPBASE/calls" 2>/dev/null || echo 0)"
+if [ "$CALLS" = "3" ]; then
+  ok "bounded: stops after VERIFY_ATTEMPTS reads"
+else
+  no "expected 3 npm calls on exhaustion, saw $CALLS"
+fi
+
+# --- Case 3: every read goes through --prefer-online (client cache-bust) ---
+write_fake_npm laggy
+run_step12 >/dev/null
+if grep -q -- '--prefer-online' "$TMPBASE/argv"; then
+  ok "every npm view read passes --prefer-online"
+else
+  no "npm view reads missing --prefer-online"
+fi
+
+echo ""
+echo "$pass passed, $fail_count failed."
+[ "$fail_count" -eq 0 ]

package/lib/test-version-write.sh

@@ -16,6 +16,11 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 PUBLISH="$SCRIPT_DIR/publish-npm.sh"
 
+# Target the next patch after the repo's current version. (A hardcoded target
+# goes stale the moment the repo releases it: writing the version that's
+# already there produces no diff and the preservation check fails closed.)
+TARGET_VERSION="$(node -e 'const fs=require("fs");const v=JSON.parse(fs.readFileSync(process.argv[1],"utf8")).version.split(".");v[v.length-1]=String(Number(v[v.length-1])+1);console.log(v.join("."))' "$REPO_DIR/package.json")"
+
 pass=0
 fail_count=0
 ok() { echo "PASS: $1"; pass=$((pass + 1)); }
@@ -58,7 +63,7 @@ RUNNER="$TMPBASE/run.sh"
 } > "$RUNNER"
 chmod +x "$RUNNER"
 
-if REPO_PATH="$FIX" TARGET_VERSION="0.4.4" bash "$RUNNER" >/dev/null 2>&1; then
+if REPO_PATH="$FIX" TARGET_VERSION="$TARGET_VERSION" bash "$RUNNER" >/dev/null 2>&1; then
   ok "shipped step-8 block exits 0 on escape-carrying package.json"
 else
   no "shipped step-8 block failed closed on escape-carrying package.json"
@@ -66,10 +71,10 @@ fi
 
 # --- Assertions on the result ---
 VER="$(node -p "JSON.parse(require('fs').readFileSync('$FIX/package.json','utf8')).version")"
-if [ "$VER" = "0.4.4" ]; then
-  ok "package.json version is 0.4.4 after write"
+if [ "$VER" = "$TARGET_VERSION" ]; then
+  ok "package.json version is $TARGET_VERSION after write"
 else
-  no "package.json version is $VER, expected 0.4.4"
+  no "package.json version is $VER, expected $TARGET_VERSION"
 fi
 
 NUMSTAT="$(git -C "$FIX" diff --numstat -- package.json | tr '\t' ' ')"

package/package.json

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

package/workflows/bugfix.js

@@ -36,6 +36,9 @@ const PUBLISH_NPM_SRC = crewHome + "/lib/publish-npm.sh";
 const PUBLISH_NPM = RUN_LIB + "/publish-npm.sh";
 const ORPHAN_SWEEP_SRC = crewHome + "/lib/orphan-sweep.sh";
 const ORPHAN_SWEEP = RUN_LIB + "/orphan-sweep.sh";
+// The four 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, ORPHAN_SWEEP].map(function (p) { return p.split("/").pop(); });
 
 // Project config — passed by dispatcher, falls back to dashboard defaults
 const projectConfig = inputs.project_config || {};
@@ -172,6 +175,27 @@ function workRetryKey(stepName, reworkSuffix, attempt) {
 function attemptKey(base, reworkCount) {
   return base + (reworkCount > 0 ? "-r" + reworkCount : "");
 }
+// pinLifecycle(key) — snapshot the lifecycle scripts into RUN_LIB and return
+// the verbatim `ls -1` listing so WORKFLOW CODE asserts the four 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 " + ORPHAN_SWEEP_SRC + " " + ORPHAN_SWEEP + " && chmod +x " + LIFECYCLE + " " + MERGE_LOCK + " " + PUBLISH_NPM + " " + ORPHAN_SWEEP + " && 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; });
+}
 function buildTransportRetryTrailer(stepName, repoPath, taskId, attempt, reason) {
   // reason: "discarded" (the runtime threw the output away — it could not be
   // machine-read) or "empty" (agent() returned without throwing but produced
@@ -474,12 +498,17 @@ async function parkTask(reason) {
 }
 let i = startStepIndex;
 
-// Pin lifecycle scripts
-await 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 " + ORPHAN_SWEEP_SRC + " " + ORPHAN_SWEEP + " && chmod +x " + LIFECYCLE + " " + MERGE_LOCK + " " + PUBLISH_NPM + " " + ORPHAN_SWEEP,
-  { key: "pin-lifecycle", label: "Pinning lifecycle scripts", schema: { type: "object" } }
-);
+// ── 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 four basenames from the verbatim listing —
+// the agent cannot self-certify. Any miss parks the task before Triage.
+const initialPins = parsePinListing(await pinLifecycle("pin-lifecycle"));
+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);
 
 while (i < STEPS.length) {
   const step = STEPS[i];
@@ -525,6 +554,33 @@ while (i < STEPS.length) {
     }
   }
 
+  // ── Pre-Publish pin guard ──────────────────────────────────────────
+  // Verify the pinned lifecycle scripts still exist on every Publish
+  // pass (first pass and rework passes): the pin step trusted agent
+  // prose instead of a mechanical check, so task 24be1cd6 walked to
+  // Publish on an empty pin dir. One re-pin and re-verify on a miss;
+  // still missing parks the task. Keys are attemptKey-scoped so a
+  // rework Publish never re-mints a first-pass key.
+  if (step.name === "Publish") {
+    let publishPins = parsePinListing(await agent(
+      "Verify the pinned lifecycle scripts are present.\n" +
+      "Run: ls -1 " + RUN_LIB + " 2>/dev/null || echo PIN_DIR_MISSING\n" +
+      "Return the verbatim output as { \"listing\": \"<verbatim output>\" } and nothing else.",
+      { key: attemptKey("pins-verify-publish", totalReworkCount), label: "Verifying pinned lifecycle scripts",
+        schema: { type: "object", properties: { listing: { type: "string" } }, required: ["listing"] } }
+    ));
+    let missingAtPublish = PIN_BASENAMES.filter(function (b) { return publishPins.indexOf(b) === -1; });
+    if (missingAtPublish.length > 0) {
+      log("Pin guard at Publish: missing " + missingAtPublish.join(", ") + " — re-pinning once");
+      publishPins = parsePinListing(await pinLifecycle(attemptKey("pin-lifecycle-republish", totalReworkCount)));
+      missingAtPublish = PIN_BASENAMES.filter(function (b) { return publishPins.indexOf(b) === -1; });
+    }
+    if (missingAtPublish.length > 0) {
+      return await parkTask("Pinned lifecycle scripts missing at Publish even after re-pin: " + missingAtPublish.join(", ") + " in " + RUN_LIB + ".");
+    }
+    log("Pin guard: all four lifecycle scripts present at Publish");
+  }
+
   // Publish is optional and target-based. Empty target = prototyping project: skip the phase.
   // Unknown target (incl. legacy "repo") = config error: block.
   if (step.name === "Publish" && !PUBLISH_TYPE) {

package/workflows/chore.js

@@ -34,6 +34,9 @@ const PUBLISH_NPM_SRC = crewHome + "/lib/publish-npm.sh";
 const PUBLISH_NPM = RUN_LIB + "/publish-npm.sh";
 const ORPHAN_SWEEP_SRC = crewHome + "/lib/orphan-sweep.sh";
 const ORPHAN_SWEEP = RUN_LIB + "/orphan-sweep.sh";
+// The four 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, ORPHAN_SWEEP].map(function (p) { return p.split("/").pop(); });
 
 // Project config — passed by dispatcher, falls back to dashboard defaults
 const projectConfig = inputs.project_config || {};
@@ -170,6 +173,27 @@ function workRetryKey(stepName, reworkSuffix, attempt) {
 function attemptKey(base, reworkCount) {
   return base + (reworkCount > 0 ? "-r" + reworkCount : "");
 }
+// pinLifecycle(key) — snapshot the lifecycle scripts into RUN_LIB and return
+// the verbatim `ls -1` listing so WORKFLOW CODE asserts the four 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 " + ORPHAN_SWEEP_SRC + " " + ORPHAN_SWEEP + " && chmod +x " + LIFECYCLE + " " + MERGE_LOCK + " " + PUBLISH_NPM + " " + ORPHAN_SWEEP + " && 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; });
+}
 function buildTransportRetryTrailer(stepName, repoPath, taskId, attempt, reason) {
   // reason: "discarded" (the runtime threw the output away — it could not be
   // machine-read) or "empty" (agent() returned without throwing but produced
@@ -432,12 +456,17 @@ async function parkTask(reason) {
 }
 let i = startStepIndex;
 
-// Pin lifecycle scripts
-await 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 " + ORPHAN_SWEEP_SRC + " " + ORPHAN_SWEEP + " && chmod +x " + LIFECYCLE + " " + MERGE_LOCK + " " + PUBLISH_NPM + " " + ORPHAN_SWEEP,
-  { key: "pin-lifecycle", label: "Pinning lifecycle scripts", schema: { type: "object" } }
-);
+// ── 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 four basenames from the verbatim listing —
+// the agent cannot self-certify. Any miss parks the task before Triage.
+const initialPins = parsePinListing(await pinLifecycle("pin-lifecycle"));
+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);
 
 while (i < STEPS.length) {
   const step = STEPS[i];
@@ -483,6 +512,33 @@ while (i < STEPS.length) {
     }
   }
 
+  // ── Pre-Publish pin guard ──────────────────────────────────────────
+  // Verify the pinned lifecycle scripts still exist on every Publish
+  // pass (first pass and rework passes): the pin step trusted agent
+  // prose instead of a mechanical check, so task 24be1cd6 walked to
+  // Publish on an empty pin dir. One re-pin and re-verify on a miss;
+  // still missing parks the task. Keys are attemptKey-scoped so a
+  // rework Publish never re-mints a first-pass key.
+  if (step.name === "Publish") {
+    let publishPins = parsePinListing(await agent(
+      "Verify the pinned lifecycle scripts are present.\n" +
+      "Run: ls -1 " + RUN_LIB + " 2>/dev/null || echo PIN_DIR_MISSING\n" +
+      "Return the verbatim output as { \"listing\": \"<verbatim output>\" } and nothing else.",
+      { key: attemptKey("pins-verify-publish", reworkCount), label: "Verifying pinned lifecycle scripts",
+        schema: { type: "object", properties: { listing: { type: "string" } }, required: ["listing"] } }
+    ));
+    let missingAtPublish = PIN_BASENAMES.filter(function (b) { return publishPins.indexOf(b) === -1; });
+    if (missingAtPublish.length > 0) {
+      log("Pin guard at Publish: missing " + missingAtPublish.join(", ") + " — re-pinning once");
+      publishPins = parsePinListing(await pinLifecycle(attemptKey("pin-lifecycle-republish", reworkCount)));
+      missingAtPublish = PIN_BASENAMES.filter(function (b) { return publishPins.indexOf(b) === -1; });
+    }
+    if (missingAtPublish.length > 0) {
+      return await parkTask("Pinned lifecycle scripts missing at Publish even after re-pin: " + missingAtPublish.join(", ") + " in " + RUN_LIB + ".");
+    }
+    log("Pin guard: all four lifecycle scripts present at Publish");
+  }
+
   // Publish is optional and target-based. Empty target = prototyping project: skip the phase.
   // Unknown target (incl. legacy "repo") = config error: block.
   if (step.name === "Publish" && !PUBLISH_TYPE) {

package/workflows/standard.js

@@ -36,6 +36,9 @@ const PUBLISH_NPM_SRC = crewHome + "/lib/publish-npm.sh";
 const PUBLISH_NPM = RUN_LIB + "/publish-npm.sh";
 const ORPHAN_SWEEP_SRC = crewHome + "/lib/orphan-sweep.sh";
 const ORPHAN_SWEEP = RUN_LIB + "/orphan-sweep.sh";
+// The four 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, ORPHAN_SWEEP].map(function (p) { return p.split("/").pop(); });
 
 // Project config — passed by dispatcher, falls back to dashboard defaults
 const projectConfig = inputs.project_config || {};
@@ -172,6 +175,27 @@ function workRetryKey(stepName, reworkSuffix, attempt) {
 function attemptKey(base, reworkCount) {
   return base + (reworkCount > 0 ? "-r" + reworkCount : "");
 }
+// pinLifecycle(key) — snapshot the lifecycle scripts into RUN_LIB and return
+// the verbatim `ls -1` listing so WORKFLOW CODE asserts the four 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 " + ORPHAN_SWEEP_SRC + " " + ORPHAN_SWEEP + " && chmod +x " + LIFECYCLE + " " + MERGE_LOCK + " " + PUBLISH_NPM + " " + ORPHAN_SWEEP + " && 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; });
+}
 function buildTransportRetryTrailer(stepName, repoPath, taskId, attempt, reason) {
   // reason: "discarded" (the runtime threw the output away — it could not be
   // machine-read) or "empty" (agent() returned without throwing but produced
@@ -475,19 +499,14 @@ let i = startStepIndex;
 
 // ── 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.
-await agent(
-  "Snapshot lifecycle scripts for version pinning.\n" +
-  "Run these shell commands:\n" +
-  "  mkdir -p " + RUN_LIB + "\n" +
-  "  cp " + LIFECYCLE_SRC + " " + LIFECYCLE + "\n" +
-  "  cp " + MERGE_LOCK_SRC + " " + MERGE_LOCK + "\n" +
-  "  cp " + PUBLISH_NPM_SRC + " " + PUBLISH_NPM + "\n" +
-  "  cp " + ORPHAN_SWEEP_SRC + " " + ORPHAN_SWEEP + "\n" +
-  "  chmod +x " + LIFECYCLE + " " + MERGE_LOCK + " " + PUBLISH_NPM + " " + ORPHAN_SWEEP + "\n" +
-  "Confirm the files exist by listing " + RUN_LIB + ".",
-  { key: "pin-lifecycle", label: "Pinning lifecycle scripts", schema: { type: "object" } }
-);
+// to upgrades that land while it's in flight. Verified mechanically:
+// workflow code asserts the four basenames from the verbatim listing —
+// the agent cannot self-certify. Any miss parks the task before Triage.
+const initialPins = parsePinListing(await pinLifecycle("pin-lifecycle"));
+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);
 
 while (i < STEPS.length) {
@@ -534,6 +553,33 @@ while (i < STEPS.length) {
     }
   }
 
+  // ── Pre-Publish pin guard ──────────────────────────────────────────
+  // Verify the pinned lifecycle scripts still exist on every Publish
+  // pass (first pass and rework passes): the pin step trusted agent
+  // prose instead of a mechanical check, so task 24be1cd6 walked to
+  // Publish on an empty pin dir. One re-pin and re-verify on a miss;
+  // still missing parks the task. Keys are attemptKey-scoped so a
+  // rework Publish never re-mints a first-pass key.
+  if (step.name === "Publish") {
+    let publishPins = parsePinListing(await agent(
+      "Verify the pinned lifecycle scripts are present.\n" +
+      "Run: ls -1 " + RUN_LIB + " 2>/dev/null || echo PIN_DIR_MISSING\n" +
+      "Return the verbatim output as { \"listing\": \"<verbatim output>\" } and nothing else.",
+      { key: attemptKey("pins-verify-publish", totalReworkCount), label: "Verifying pinned lifecycle scripts",
+        schema: { type: "object", properties: { listing: { type: "string" } }, required: ["listing"] } }
+    ));
+    let missingAtPublish = PIN_BASENAMES.filter(function (b) { return publishPins.indexOf(b) === -1; });
+    if (missingAtPublish.length > 0) {
+      log("Pin guard at Publish: missing " + missingAtPublish.join(", ") + " — re-pinning once");
+      publishPins = parsePinListing(await pinLifecycle(attemptKey("pin-lifecycle-republish", totalReworkCount)));
+      missingAtPublish = PIN_BASENAMES.filter(function (b) { return publishPins.indexOf(b) === -1; });
+    }
+    if (missingAtPublish.length > 0) {
+      return await parkTask("Pinned lifecycle scripts missing at Publish even after re-pin: " + missingAtPublish.join(", ") + " in " + RUN_LIB + ".");
+    }
+    log("Pin guard: all four lifecycle scripts present at Publish");
+  }
+
   // Publish is optional and target-based. Empty target = prototyping project: skip the phase.
   // Unknown target (incl. legacy "repo") = config error: block.
   if (step.name === "Publish" && !PUBLISH_TYPE) {