muse-crew 0.17.2 → 0.17.3

package/lib/bugfix/phases/publish.js

@@ -0,0 +1,592 @@
+// lib/bugfix/phases/publish.js — Publish (wren) phase module (sandbox
+// exit, Phase D). Import-safe: no side effects on import, bare `node`
+// exits 0.
+//
+// Bugfix's Publish is NOT the standard workflow's Publish: a rigorous
+// source comparison (hidden_files/phase-d/extract-integrate-publish.md,
+// 15 deltas D1–D15) found behavioral differences that change observable
+// task outcomes, so this is a dedicated specialization sharing only the
+// workflow-neutral helpers. Deliberate bugfix behaviors preserved here:
+//
+// - D1/D14: pin guard, empty-target skip, unknown-target park, and the
+//   npm release-decision/version computation all run BEFORE the
+//   self-claim. The empty-target and release:no skips hold no claim and
+//   record no session/event (D2/D3) — the phase advances silently.
+// - D4: the release decision is re-derived from durable Build notes at
+//   every entry (the worker layer has no run-local variable to reuse; a
+//   dispatcher retry resumed at Publish must work).
+// - D5: the npm package name is hardcoded to "muse-crew" (the source
+//   hardcodes it; there is no env.npmPackage indirection in bugfix).
+// - D6: the skip note is truthful per reason (the source's closeout
+//   collapsed both skips into "skipped: no-lock-held"; the QA backstop
+//   is updated to recognize both markers).
+// - D7: the verified re-entry guard runs BEFORE lock-status (a verified
+//   re-entry with no lock held takes the verified framing, never the
+//   empty-diff skip note).
+// - D8: ledger entries carry attempt: rebuildAttemptKey (minted once per
+//   phase entry as attemptKey("publish-artifact-rebuild-"+taskId,
+//   reworkCount)); preflight entries record commit: null — the source's
+//   var-hoisting quirk (P4), preserved deliberately via the shared
+//   recordPublishLedger.
+// - D9: the .files.json write parks fail-closed on error (strict).
+// - D10: intent-anchor failure parks ("Deterministic artifact publish
+//   failed: ..."), it does not return FAILED.
+// - D11: on the artifact no-lock skip path, post-deploy is strict — a
+//   missing DEPLOYED parks fail-closed.
+// - D12: vercel parks honestly (the source's vercel branch is dead code
+//   that dispatched an agent with empty instructions).
+// - D13: published_at is left null for the server default (no clock read
+//   in the module).
+// - D15: the npm publish script's markers are classified mechanically
+//   (no creative agent runs the publish).
+//
+// Reads: claim/session context (only once publish work actually starts),
+//   the release decision re-derived from durable Build notes,
+//   env.publishType, merge-lock state, npm registry base version,
+//   dashboard provenance.
+// Writes: completed/failed session + event (machine-readable marker lines
+//   appended after the summary slice — QA's npm backstop reads
+//   TARGET_VERSION=, published: muse-crew@, and the skipped: markers),
+//   ~/.publish-diffs/<taskId>.files.json (the complete file list of what
+//   the task changed — QA classifies content findings against it),
+//   publish-attempt ledger intent entries, post-deploy cleanup (lock
+//   release + worktree reclaim).
+// Transitions: ADVANCE → QA on success or honest skip. FAILED on
+//   operational failure (retryable under the dispatcher's cap). PARK on:
+//   unknown publish target, missing/unparseable release decision, publish
+//   verification failure, artifact publish intent (one-party: issuance
+//   belongs to the parent layer — the phase parks at intent), vercel
+//   (declared but unimplemented — fails honestly), intent-anchor failure,
+//   strict post-deploy failure on the artifact skip path.
+
+import {
+  runCmd, crewApi, recordPhase, ensureClaimed,
+  latestSessionNotes, lifecycle, parkTask, pinLifecycle, PIN_BASENAMES, log,
+  recordPublishLedger,
+} from "../../workflow-lib.js";
+import {
+  extractReleaseDecision, bumpVersion, extractMarkerLines,
+} from "../../extract.js";
+import { join, basename } from "path";
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, readlinkSync } from "fs";
+
+export const PHASE = { name: "Publish", identity: "wren" };
+const EMPTY_TREE_SHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+
+// buildInstructions — pure function of ctx. The deterministic publish
+// procedure for the configured publish type (the worker layer runs the
+// pinned scripts directly — no creative agent is dispatched by this
+// phase; the text documents the mechanical procedure). The npm package is
+// hardcoded to muse-crew (D5), matching the source.
+export function buildInstructions(ctx) {
+  var env = ctx.env;
+  var taskId = env.taskId;
+  if (!env.publishType) {
+    return "Publish is skipped: no publish target is configured for this project (deploy_type empty). Run post-deploy cleanup (release the merge lock, reclaim the worktree) and advance to QA. Nothing is shipped. No session is recorded for this skip.";
+  }
+  if (env.publishType === "npm") {
+    return "Deterministic npm publish. The release decision was already made and recorded by the workflow — there is no decision to make.\n" +
+      "1. Read the registry base version (npm view muse-crew version, falling back to the repo's package.json), validate it is semver, and compute the target version as base + version_bump (the scope from the Build report's release decision).\n" +
+      "2. Run exactly one command — the pinned publish script at " + join(env.runLib, "publish-npm.sh") + " with TASK_ID=" + taskId + " REPO_PATH=" + env.repoPath + " PKG=muse-crew TARGET_VERSION=<target> CREW_HOME=" + env.crewHome + " LIFECYCLE=" + env.lifecycle + " RELEASE_SCRIPT=" + env.releaseScript + ".\n" +
+      "3. Parse the script's marker lines: PUBLISH_SKIPPED=no-lock-held (empty-diff Integrate — nothing merged, nothing to ship, an honest skip), PUBLISH_SKIPPED=no-npm-publish (npm publish not configured — honest skip), PUBLISH_FAILED=<reason> (operational failure), PUBLISH_COMPLETE=<version> (shipped).\n" +
+      "4. On PUBLISH_COMPLETE, verify mechanically: the registry version must equal the target. A mismatch parks fail-closed — the publish did not land.\n" +
+      "Do NOT run npm, npm pack, npm publish, or the python publish script directly. Do NOT compare local and registry versions by judgment. Do NOT decide whether to publish.";
+  }
+  if (env.publishType === "artifact") {
+    return "Deterministic artifact publish (one-party: this phase stages the intent; issuance belongs to the parent layer).\n" +
+      "1. Verified re-entry guard FIRST: if the dashboard provenance stamps this task's merge commit as the repo's current HEAD, the parent already published and verified it — skip issuance entirely and advance to QA.\n" +
+      "2. Read the merge-lock state explicitly (lock-status). UNLOCKED means an empty-diff Integrate — skip gracefully: nothing merged, nothing to ship; post-deploy must report DEPLOYED or the phase parks fail-closed. Otherwise refresh the lock; a refresh failure parks fail-closed.\n" +
+      "3. Preflight: the artifact target directory ~/workspace/ts-spaces/" + (env.publishSlug || "<deploy_slug>") + "/ must exist (conclusive). A missing target parks with a ledger 'rejected' entry; an inconclusive preflight parks with 'unknown'.\n" +
+      "4. Compute the publish diff deterministically (compute-publish-diff.js from the stamped provenance base), persist the file list to " + env.publishDiffsDir + "/" + taskId + ".files.json for QA attribution, anchor the intent in the publish-attempt ledger (attempt key minted once per phase entry), and park at publish intent. An unconfirmed intent anchor parks fail-closed — never an orphan intent.\n" +
+      "This phase never issues an artifact_edit and never writes an issuance ledger entry — the outcome is 'publish-intent', never 'submitted'.";
+  }
+  return "Publish target '" + env.publishType + "' is not a known publish type — the phase parks fail-closed. Expected 'npm', 'artifact', 'vercel', or empty (skip publish).";
+}
+
+// pinGuard — the Publish preflight from the source: all pinned lifecycle
+// scripts must be present (re-pin once, then park honestly). Runs BEFORE
+// the self-claim (D1): a pin failure parks without ever claiming.
+async function pinGuard(env) {
+  var present = [];
+  try {
+    present = readdirSync(env.runLib);
+  } catch (e) {
+    present = [];
+  }
+  var missing = PIN_BASENAMES.filter(function (b) { return present.indexOf(b) === -1; });
+  if (missing.length > 0) {
+    log("Pin guard at Publish: missing " + missing.join(", ") + " — re-pinning once");
+    try {
+      pinLifecycle(env);
+      present = readdirSync(env.runLib);
+    } catch (e) {
+      present = [];
+    }
+    missing = PIN_BASENAMES.filter(function (b) { return present.indexOf(b) === -1; });
+  }
+  if (missing.length > 0) {
+    return { parked: await parkTask(env, "Pinned lifecycle scripts missing at Publish even after re-pin: " + missing.join(", ") + " in " + env.runLib + ".") };
+  }
+  log("Pin guard: all four lifecycle scripts present at Publish");
+  return { ok: true };
+}
+
+// postDeploy — STEP 2 (mechanical, always — skip path included):
+// post-deploy commits builder leftovers if any, removes the worktree, and
+// releases the merge lock (forgiving when none is held) — even when the
+// publish itself failed, so a skipped or failed publish can never leave the
+// lock held. Best-effort hygiene: never a gate, never a park — EXCEPT on
+// the artifact no-lock skip path, where the source gates on DEPLOYED
+// (D11); that path uses postDeployStrict below.
+async function postDeploy(env) {
+  try {
+    var res = await lifecycle(env, "post-deploy", [env.taskId]);
+    var out = String((res && res.stdout) || "");
+    log("Publish post-deploy for task " + env.taskId + ": " + (/DEPLOYED/.test(out) ? "DEPLOYED" : "output: " + out.slice(0, 120)));
+  } catch (e) {
+    log("Publish post-deploy threw for task " + env.taskId + " (" + ((e && e.message) || e) + ") — forgiving, continuing");
+  }
+}
+
+// postDeployStrict — the artifact no-lock skip path (D11): the source's
+// skip-cleanup agent reported {deployed, output} and the workflow parked
+// fail-closed when DEPLOYED was absent. Returns {deployed, output}.
+async function postDeployStrict(env) {
+  var out = "";
+  try {
+    out = String((await lifecycle(env, "post-deploy", [env.taskId])).stdout || "");
+  } catch (e) {
+    out = String((e && e.stdout) || "");
+    log("Publish strict post-deploy threw for task " + env.taskId + " (" + ((e && e.message) || e) + ")");
+  }
+  var deployed = /DEPLOYED/.test(out);
+  log("Publish strict post-deploy for task " + env.taskId + ": " + (deployed ? "DEPLOYED" : "no DEPLOYED in output: " + out.slice(0, 120)));
+  return { deployed: deployed, output: out.trim() };
+}
+
+// computeNpmTarget — deterministic pre-publish: read the registry base,
+// validate semver, compute target = base + scope. Fail-closed parks. The
+// package name is hardcoded to muse-crew (D5), matching the source.
+async function computeNpmTarget(env, releaseDecision) {
+  var pkg = "muse-crew";
+  var base = "";
+  try {
+    base = String((await runCmd(["npm", "view", pkg, "version"], {})).stdout || "").trim();
+  } catch (e) {
+    base = "";
+  }
+  if (!base) {
+    try {
+      base = String((await runCmd(["node", "-p", "require('" + join(env.repoPath, "package.json") + "').version"], {})).stdout || "").trim();
+    } catch (e) {
+      base = "";
+    }
+  }
+  if (!/^\d+\.\d+\.\d+$/.test(base)) {
+    return { parked: await parkTask(env, "Publish base version unreadable: '" + base + "'. Fail-closed.") };
+  }
+  var scope = (releaseDecision && releaseDecision.version_bump) || "patch";
+  var target = { base: base, scope: scope, target: bumpVersion(base, scope) };
+  log("Publish target for task " + env.taskId + ": " + base + " + " + scope + " -> " + target.target);
+  return { target: target, pkg: pkg };
+}
+
+// runNpmPublish — the deterministic publish script, run directly (the
+// source had the Publish agent run exactly this one command; the worker
+// layer skips the agent and runs it mechanically). PKG is hardcoded to
+// muse-crew (D5).
+async function runNpmPublish(env, pkg, target) {
+  var script = join(env.runLib, "publish-npm.sh");
+  var scriptEnv = Object.assign({}, process.env, {
+    CREW_HOME: env.crewHome, CREW_REPO: env.repoPath,
+    TASK_ID: env.taskId, REPO_PATH: env.repoPath, PKG: pkg,
+    TARGET_VERSION: target.target, LIFECYCLE: env.lifecycle,
+    RELEASE_SCRIPT: env.releaseScript,
+  });
+  var out = "";
+  try {
+    out = String((await runCmd([script], { env: scriptEnv })).stdout || "");
+  } catch (e) {
+    out = String((e && e.stdout) || "");
+    var failLine = /^PUBLISH_FAILED=(.+)$/m.exec(out);
+    return { failed: "publish script failed: " + (failLine ? failLine[1].trim() : ((e && e.message) || e).slice(0, 200)), output: out };
+  }
+  var skip = /^PUBLISH_SKIPPED=(no-lock-held|no-npm-publish)$/m.exec(out);
+  if (skip) return { skipped: skip[1], output: out };
+  var complete = /^PUBLISH_COMPLETE=(.+)$/m.exec(out);
+  if (complete) return { complete: complete[1].trim(), output: out };
+  var failed = /^PUBLISH_FAILED=(.+)$/m.exec(out);
+  if (failed) return { failed: "publish script reported PUBLISH_FAILED=" + failed[1].trim(), output: out };
+  return { failed: "publish script produced no usable marker (no PUBLISH_COMPLETE/PUBLISH_FAILED/PUBLISH_SKIPPED)", output: out };
+}
+
+// verifyNpmPublish — the parent verifies the publish (publish-path.md:
+// the agent cannot verify publish; the parent does). Registry version
+// must equal the target, else park fail-closed.
+async function verifyNpmPublish(env, pkg, target) {
+  var regVer = "";
+  try {
+    regVer = String((await runCmd(["npm", "view", pkg, "version"], {})).stdout || "").trim();
+  } catch (e) {
+    return { parked: await parkTask(env, "Publish verification failed: could not read the registry version (" + ((e && e.message) || e).slice(0, 200) + "). Fail-closed.") };
+  }
+  if (regVer !== target.target) {
+    return { parked: await parkTask(env, "Publish verification failed: registry shows " + regVer + " but the release decision required " + target.target + " (" + target.base + " + " + target.scope + "). The publish did not land.") };
+  }
+  return { ok: true };
+}
+
+// refreshProvenance — provenance-refresh (publish-verification.md): refresh
+// crew_release after a landed publish, preserving source_commit.
+// published_at defaults server-side (stampProvenance: published_at ?? now())
+// so this module never reads the clock (D13).
+async function refreshProvenance(env) {
+  var taskId = env.taskId;
+  var prov;
+  try {
+    prov = await crewApi(env, "get-provenance", { project_id: env.projectId });
+  } catch (e) {
+    return { parked: await parkTask(env, "Provenance refresh failed: could not read dashboard provenance after a verified npm publish (" + ((e && e.message) || e).slice(0, 200) + "). Fail-closed.") };
+  }
+  var existing = prov && prov.provenance;
+  if (!existing) {
+    log("Provenance refresh skipped for task " + taskId + ": no existing record to refresh (fresh instance — the dashboard's first artifact publish will create it)");
+    return { ok: true, skipped: true };
+  }
+  var rel;
+  try {
+    rel = basename(readlinkSync(env.crewHome + "/current"));
+  } catch (e) {
+    return { parked: await parkTask(env, "Provenance refresh failed: could not resolve the active release symlink (" + ((e && e.message) || e).slice(0, 200) + "). Fail-closed.") };
+  }
+  try {
+    var res = await crewApi(env, "set-provenance", {
+      project_id: env.projectId, source_commit: existing.source_commit,
+      crew_release: rel, published_at: null, task_id: taskId,
+    });
+    var ok = res && (res.ok === true || /ok:\s*true/i.test(JSON.stringify(res)));
+    if (!ok) {
+      return { parked: await parkTask(env, "Provenance refresh failed after a verified npm publish (crew_release " + rel + "). The release is live but the dashboard record is stale — fail-closed.") };
+    }
+    log("Provenance refreshed for task " + taskId + ": crew_release " + rel);
+    return { ok: true };
+  } catch (e) {
+    return { parked: await parkTask(env, "Provenance refresh failed: could not refresh dashboard provenance after a verified npm publish (" + ((e && e.message) || e).slice(0, 200) + "). Fail-closed.") };
+  }
+}
+
+// checkArtifactReentry — the verified re-entry guard (blocker 22): if the
+// stamped provenance names THIS task and its source_commit is the repo's
+// current HEAD, the merge commit was already published and verified by the
+// parent — issuance is skipped entirely. A guard failure never claims
+// verification — the task proceeds down the normal path. Runs BEFORE
+// lock-status (D7): a verified re-entry with no lock held (the normal
+// case — the intent park's terminal cleanup released the lock) takes the
+// verified framing, never the empty-diff skip note.
+async function checkArtifactReentry(env) {
+  try {
+    var prov = await crewApi(env, "get-provenance", { project_id: env.projectId });
+    var head = String((await runCmd(["git", "-C", env.repoPath, "rev-parse", "HEAD"], {})).stdout || "").trim();
+    var p = prov && prov.provenance;
+    if (p && p.source_commit && p.source_commit === head && p.task_id === env.taskId) {
+      log("Publish verified re-entry for task " + env.taskId + ": provenance stamps " + p.source_commit + " == HEAD for this task — the parent already published and verified it; issuance skipped");
+      return true;
+    }
+  } catch (e) {
+    log("Publish re-entry guard threw for task " + env.taskId + " (" + ((e && e.message) || e).slice(0, 200) + ") — proceeding with the normal publish path; a guard failure never claims verification");
+  }
+  return false;
+}
+
+// publishArtifact — the one-party artifact publish path. Everything through
+// the intent anchor is read-only and deterministic (direct calls, no agent
+// couriers — the worker layer has no ferry constraint). Parks at intent:
+// issuance belongs to the parent layer, which issues the edit directly and
+// whose acknowledgement scan owns the task from there.
+//
+// Ordering (D7): the verified re-entry guard runs BEFORE lock-status.
+// Ledger entries carry attempt: rebuildAttemptKey, minted once per phase
+// entry (D8). Preflight entries record commit: null — the source's
+// var-hoisting quirk (P4), preserved deliberately by the shared
+// recordPublishLedger.
+async function publishArtifact(env, state, rebuildAttemptKey) {
+  var taskId = env.taskId;
+  var slug = env.publishSlug;
+
+  // Verified re-entry FIRST (D7): the intent park's terminal cleanup
+  // already released the lock and reclaimed the worktree. Post-deploy below
+  // is best-effort hygiene on this branch — never a gate, never a park.
+  if (await checkArtifactReentry(env)) {
+    await postDeploy(env);
+    await recordPhase(env, {
+      task_id: taskId,
+      session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "completed",
+        notes: "Publish verified re-entry: provenance stamps this task's merge commit as HEAD — the parent already published and verified it; issuance skipped." },
+      event: { task_id: taskId, type: "completed", identity: PHASE.identity, message: PHASE.name + " completed by " + PHASE.identity },
+    });
+    return { type: "ADVANCE", next: "QA" };
+  }
+
+  // STEP 0 (mechanical): read the merge-lock state explicitly — never infer
+  // it from prose. An empty-diff Integrate (MERGED_EMPTY) intentionally
+  // takes no lock: nothing merged, nothing to ship. When no lock is held,
+  // Publish skips gracefully instead of failing closed on refresh-lock —
+  // but post-deploy is strict here (D11): a missing DEPLOYED parks
+  // fail-closed, because worktree cleanup and lock state would be unknown.
+  var lockOut = "";
+  try {
+    lockOut = String((await lifecycle(env, "lock-status", [taskId])).stdout || "").trim();
+  } catch (e) {
+    return { parked: await parkTask(env, "Publish lock state unreadable: " + ((e && e.message) || e).slice(0, 200) + ". Fail-closed — lock state unknown.") };
+  }
+  if (lockOut === "UNLOCKED") {
+    var pd = await postDeployStrict(env);
+    if (!pd.deployed) {
+      return { parked: await parkTask(env, "Post-deploy failed after a skipped publish: " + (pd.output || "no output") + ". Nothing was published; worktree cleanup and lock state unknown — human attention needed.") };
+    }
+    log("Publish skipped cleanly for task " + taskId + " (no lock held) — post-deploy step finished");
+    await recordPhase(env, {
+      task_id: taskId,
+      session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "completed",
+        notes: "skipped: no-lock-held (empty-diff Integrate — nothing merged, nothing to ship)" },
+      event: { task_id: taskId, type: "completed", identity: PHASE.identity, message: PHASE.name + " completed by " + PHASE.identity },
+    });
+    return { type: "ADVANCE", next: "QA" };
+  }
+  try {
+    await lifecycle(env, "refresh-lock", [taskId]);
+  } catch (e) {
+    return { parked: await parkTask(env, "Publish lock refresh failed: " + ((e && e.message) || e).slice(0, 200) + ". Fail-closed — lock state unknown.") };
+  }
+
+  // Artifact preflight: the project is classified artifact but the target
+  // must provably exist. Conclusive missing -> ledger "rejected" + park;
+  // inconclusive -> ledger "unknown" + park. (Publish edits an existing
+  // artifact; it never creates one.)
+  if (!slug) {
+    await recordPublishLedger(env, { commit: null, attempt: rebuildAttemptKey, outcome: "rejected", detail: "artifact surface with empty deploy_slug (preflight): the project is classified as artifact but has no deploy_slug — misconfiguration, not a missing artifact. No edit was issued." });
+    return { parked: await parkTask(env, "Publish cannot proceed for task " + taskId + ": the project is classified as an artifact surface but has no deploy_slug. This is a project configuration defect — set a deploy_slug for the project, then re-run Publish. Human attention needed.") };
+  }
+  if (!/^[a-zA-Z0-9_-]+$/.test(slug)) {
+    await recordPublishLedger(env, { commit: null, attempt: rebuildAttemptKey, outcome: "unknown", detail: "artifact preflight inconclusive: PUBLISH_SLUG has an unsafe shape — fail-closed, no edit issued." });
+    return { parked: await parkTask(env, "Publish cannot proceed for task " + taskId + ": the artifact target preflight was inconclusive (deploy_slug has an unsafe shape). Target existence is unproven, so no edit was issued and nothing was retried blindly. Human attention needed.") };
+  }
+  var artifactTargetDir = join(process.env.HOME || "", "workspace/ts-spaces", slug);
+  var targetPresent = false;
+  try {
+    targetPresent = readdirSync(artifactTargetDir).length >= 0;
+  } catch (e) {
+    targetPresent = false;
+  }
+  if (!targetPresent) {
+    await recordPublishLedger(env, { commit: null, attempt: rebuildAttemptKey, outcome: "rejected", detail: "artifact target directory missing (preflight): " + artifactTargetDir + " does not exist — setup never provisioned the artifact for deploy_slug " + slug + ". The edit provably did not go through: no trigger issued, no blind retry" });
+    return { parked: await parkTask(env, "Publish cannot proceed for task " + taskId + ": the artifact target directory " + artifactTargetDir + " does not exist. The project is classified as an artifact surface (deploy_slug " + slug + ") but setup never provisioned the artifact — this is conclusive (rejected, not unknown): no edit was issued. Create the artifact via the Muse UI (Publish edits an existing artifact; it never creates one), then re-run init and Publish. Human attention needed.") };
+  }
+  log("Publish artifact preflight for task " + taskId + ": target " + artifactTargetDir + " present");
+
+  // Stamped publish base (per-project provenance; empty tree = first publish).
+  var publishBase = "";
+  try {
+    var provResult = await crewApi(env, "get-provenance", { project_id: env.projectId });
+    publishBase = String((provResult && provResult.provenance && provResult.provenance.source_commit) || "").trim();
+  } catch (e) {
+    return { parked: await parkTask(env, "Publish cannot proceed for task " + taskId + ": the stamped publish base is unreadable (" + ((e && e.message) || e).slice(0, 200) + "). Human attention needed.") };
+  }
+  if (!publishBase) {
+    publishBase = EMPTY_TREE_SHA;
+    log("Publish base for task " + taskId + ": no provenance stamped yet — using empty tree (first publish)");
+  } else if (!/^[0-9a-f]{40}$/.test(publishBase)) {
+    return { parked: await parkTask(env, "Publish base '" + publishBase + "' is not a valid commit SHA — cannot compute the publish diff. Human attention needed.") };
+  }
+
+  // Deterministic diff (diff travels via file, never through an LLM).
+  var diffFile = env.publishDiffsDir + "/" + taskId + (state.reworkCount > 0 ? "-r" + state.reworkCount : "") + ".diff";
+  var diffSummary = null;
+  try {
+    mkdirSync(env.publishDiffsDir, { recursive: true });
+    var diffOut = String((await runCmd(["node", join(env.runLib, "compute-publish-diff.js"),
+      "--repo-path", env.repoPath, "--base", publishBase,
+      "--task-id", taskId, "--attempt", "1", "--out", diffFile], {})).stdout || "").trim();
+    diffSummary = JSON.parse(diffOut);
+  } catch (e) {
+    return { parked: await parkTask(env, "Publish diff computation returned unparseable output — cannot verify application. Human attention needed.") };
+  }
+  if (!diffSummary || diffSummary.ok !== true) {
+    if (diffSummary && diffSummary.error === "not-ancestor") {
+      return { parked: await parkTask(env, "Publish base " + publishBase.slice(0, 12) + " is not an ancestor of HEAD " + String(diffSummary.commit || "").slice(0, 12) + " — the stamped provenance does not lead to the integrated commit. Human attention needed.") };
+    }
+    return { parked: await parkTask(env, "Publish diff computation failed (" + ((diffSummary && diffSummary.error) || "unknown error") + ") — cannot verify application. Human attention needed.") };
+  }
+  if (diffSummary.base !== publishBase) {
+    return { parked: await parkTask(env, "Publish diff base mismatch: script reported '" + String(diffSummary.base || "").slice(0, 12) + "' but the stamped base is '" + publishBase.slice(0, 12) + "'. Human attention needed.") };
+  }
+  var mergeCommitForPublish = String(diffSummary.commit || "").trim();
+  var publishVersion = String(diffSummary.version || "");
+  if (!/^[0-9a-f]{40}:[1-9][0-9]*$/.test(publishVersion)) {
+    return { parked: await parkTask(env, "Publish diff for commit " + (mergeCommitForPublish || "unknown") + " carries no usable publish version — cannot stage a verifiable intent. Human attention needed.") };
+  }
+  if (!diffSummary.bytes) {
+    return { parked: await parkTask(env, "Publish diff is empty for commit " + (mergeCommitForPublish || "unknown") + " — a merge lock was held but there is no change to carry. Human attention needed.") };
+  }
+  if (diffSummary.has_binary) {
+    return { parked: await parkTask(env, "Publish diff contains binary files — the diff transport cannot carry them. Human attention needed.") };
+  }
+  if (diffSummary.has_rename) {
+    return { parked: await parkTask(env, "Publish diff contains a rename — the diff transport cannot carry renames. Human attention needed.") };
+  }
+  // Persist the publish-diff file set for QA content-finding attribution
+  // (blocker 38): the complete record of what the task changed. Direct fs
+  // write — the worker layer needs no agent courier. A write failure parks
+  // fail-closed (D9): QA attribution would be blind.
+  var filesPath = env.publishDiffsDir + "/" + taskId + ".files.json";
+  try {
+    writeFileSync(filesPath, JSON.stringify(diffSummary.files || []) + "\n", "utf8");
+  } catch (e) {
+    return { parked: await parkTask(env, "Publish diff file list could not be persisted (" + ((e && e.message) || e).slice(0, 200) + ") — QA attribution would be blind. Human attention needed.") };
+  }
+  // Budget counts CHANGED lines (added + removed), not raw unified-diff
+  // output lines. The count comes from the deterministic script summary,
+  // never from an LLM.
+  var changedLines = diffSummary.changed_lines || 0;
+  if (changedLines > 200) {
+    return { parked: await parkTask(env, "Publish diff changes " + changedLines + " lines (budget 200) — too large for the diff transport. Human attention needed.") };
+  }
+  if (!diffSummary.file_count) {
+    return { parked: await parkTask(env, "Publish diff parsed to zero files for commit " + (mergeCommitForPublish || "unknown") + " — cannot verify application. Human attention needed.") };
+  }
+
+  // Anchor the intent. The entry is issuer-written BY THE WORKFLOW and
+  // names the intent: outcome "publish-intent", never "submitted" — the
+  // workflow issued nothing. The parent claims it via the park note below.
+  var intentAnchored = await recordPublishLedger(env, {
+    commit: mergeCommitForPublish,
+    attempt: rebuildAttemptKey,
+    publish_attempt: 1,
+    version: publishVersion,
+    agent_id: null,
+    applied_report: null,
+    outcome: "publish-intent",
+    issuer: "workflow",
+    diff_path: diffFile,
+    diff_sha256: String(diffSummary.sha256 || ""),
+    base: publishBase,
+    detail: "publish intent: preflight and checksummed diff are complete; issuance is owned by the parent layer. The workflow performed no artifact_edit and wrote no issuance.",
+  });
+  if (!intentAnchored) {
+    // Fail loudly by parking (D10) — never an orphan intent. Best-effort
+    // post-deploy first so the failure cannot wedge the next run.
+    await postDeploy(env);
+    return { parked: await parkTask(env, "Deterministic artifact publish failed: publish-intent ledger anchor write unconfirmed. Fail-closed.") };
+  }
+  return { parked: await parkTask(env, "publish: publish-requested " + mergeCommitForPublish + " attempt=1 — Publish intent recorded for task " + taskId + ": the merged change is staged as a checksummed diff (" + diffFile + ", sha256 " + String(diffSummary.sha256 || "") + ") carrying the per-attempt publish version for the parent layer to issue. The parent issues the edit directly and the acknowledgement scan owns the task from there; no action needed.") };
+}
+
+export async function runPhase(ctx) {
+  var env = ctx.env, state = ctx.state;
+  var taskId = env.taskId;
+
+  // D1/D14: the pin guard, the target checks, and the npm
+  // release-decision/version computation all run BEFORE the self-claim.
+  // The skip paths hold no claim and record no session (D2/D3).
+  var pg = await pinGuard(env);
+  if (pg.parked) return pg.parked;
+
+  // Publish is optional and target-based. Empty target = prototyping
+  // project: skip the phase (no record — D2). Unknown target (incl.
+  // legacy "repo") = config error: block.
+  if (!env.publishType) {
+    log("Publish skipped for task " + taskId + " — no publish target configured (deploy_type empty)");
+    await postDeploy(env);
+    return { type: "ADVANCE", next: "QA" };
+  }
+  if (env.publishType !== "npm" && env.publishType !== "artifact" && env.publishType !== "vercel") {
+    log("Unknown publish target for task " + taskId + ": " + env.publishType);
+    return { parked: await parkTask(env, "Unknown publish target '" + env.publishType + "' — expected 'npm', 'artifact', 'vercel', or empty (skip publish).") };
+  }
+  if (env.publishType === "vercel") {
+    return { parked: await parkTask(env, "Vercel publish is declared but has no implementation path. Human attention needed: implement the Vercel publish path or change the project's publish type.") };
+  }
+
+  // Merge-time versioning, decided deterministically: the release decision
+  // is re-derived from the durable Build notes at every Publish entry (a
+  // dispatcher retry resumed at Publish never re-runs Build). release: no
+  // skips like the no-target case (no record — D3); an unparseable
+  // decision blocks fail-closed.
+  var releaseDecision = extractReleaseDecision(await latestSessionNotes(env, "Build", "completed"));
+  state.memo.releaseDecision = releaseDecision;
+
+  if (env.publishType === "npm") {
+    if (!releaseDecision) {
+      return { parked: await parkTask(env, "Build report has no machine-readable release:/version_bump: declaration — cannot assign version at publish time.") };
+    }
+    if (releaseDecision.release === "no") {
+      log("Publish skipped for task " + taskId + " — accepted Build report declared release: no");
+      await postDeploy(env);
+      return { type: "ADVANCE", next: "QA" };
+    }
+    var ct = await computeNpmTarget(env, releaseDecision);
+    if (ct.parked) return ct.parked;
+    var target = ct.target, pkg = ct.pkg;
+
+    // Self-claim: only now that publish work actually starts (D1).
+    var claimed = await ensureClaimed(env, state, PHASE);
+    if (claimed.type !== "CLAIMED") return claimed;
+
+    var pub = await runNpmPublish(env, pkg, target);
+    await postDeploy(env);
+    var markerLines, status, eventType;
+    if (pub.failed) {
+      markerLines = "TARGET_VERSION=" + target.target + " computed as " + target.base + " + " + target.scope + " → " + target.target + "\n" +
+        "publish: FAILED — " + pub.failed;
+      status = "failed"; eventType = "failed";
+      await recordPhase(env, {
+        task_id: taskId,
+        session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: status, notes: markerLines },
+        event: { task_id: taskId, type: eventType, identity: PHASE.identity, message: PHASE.name + " failed by " + PHASE.identity },
+      });
+      return { type: "FAILED", reason: "npm publish failed: " + pub.failed };
+    }
+    if (pub.skipped) {
+      // The skip path records the computed target and the explicit skip —
+      // never "published:", which would be a false claim. The skip note is
+      // truthful per reason (D6): QA's backstop recognizes both markers.
+      var skipNote = pub.skipped === "no-npm-publish"
+        ? "skipped: no-npm-publish (npm publish not configured — helper or credential missing; nothing versioned or published)"
+        : "skipped: no-lock-held (empty-diff Integrate — nothing merged, nothing to ship)";
+      log("Publish skipped for task " + taskId + " (" + pub.skipped + "): publish verification vacuous, nothing was shipped");
+      markerLines = "TARGET_VERSION=" + target.target + " computed as " + target.base + " + " + target.scope + " → " + target.target + "\n" + skipNote;
+      await recordPhase(env, {
+        task_id: taskId,
+        session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "completed", notes: markerLines },
+        event: { task_id: taskId, type: "completed", identity: PHASE.identity, message: PHASE.name + " completed by " + PHASE.identity },
+      });
+      return { type: "ADVANCE", next: "QA" };
+    }
+    // Landed — the parent verifies (the agent cannot verify publish).
+    var pv = await verifyNpmPublish(env, pkg, target);
+    if (pv.parked) return pv.parked;
+    var pr = await refreshProvenance(env);
+    if (pr.parked) return pr.parked;
+    markerLines = "TARGET_VERSION=" + target.target + " computed as " + target.base + " + " + target.scope + " → " + target.target + "\n" +
+      "published: " + pkg + "@" + target.target;
+    var workerMarkers = extractMarkerLines(pub.output || "");
+    await recordPhase(env, {
+      task_id: taskId,
+      session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "completed",
+        notes: markerLines + (workerMarkers ? "\n" + workerMarkers : "") },
+      event: { task_id: taskId, type: "completed", identity: PHASE.identity, message: PHASE.name + " completed by " + PHASE.identity },
+    });
+    log("Publish complete for task " + taskId + ": " + pkg + "@" + target.target);
+    return { type: "ADVANCE", next: "QA" };
+  }
+
+  // Artifact path (one-party publish). The claim precedes the artifact
+  // flow (D1); the verified re-entry guard inside publishArtifact runs
+  // before lock-status (D7).
+  var claimedArtifact = await ensureClaimed(env, state, PHASE);
+  if (claimedArtifact.type !== "CLAIMED") return claimedArtifact;
+  // Mint the attempt key once per phase entry (D8): the exact key the
+  // ledger records at every site, preflight parks included.
+  var rebuildAttemptKey = "publish-artifact-rebuild-" + taskId + (state.reworkCount > 0 ? "-r" + state.reworkCount : "");
+  return await publishArtifact(env, state, rebuildAttemptKey);
+}