muse-crew 0.17.2 → 0.17.3

package/lib/standard/phases/publish.js

@@ -0,0 +1,565 @@
+// lib/standard/phases/publish.js — Publish (wren) phase module (sandbox
+// exit, Phase C Piece 1). Import-safe: no side effects on import, bare
+// `node` exits 0.
+//
+// Reads: claim/session context, the release decision RE-DERIVED from
+//   durable Build notes at every entry (the run-local decision is null on
+//   a dispatcher retry resumed at Publish — this is the hydrate step the
+//   current source defines but never calls), 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 backstop reads TARGET_VERSION=),
+//   ~/.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).
+
+import {
+  runCmd, crewApi, recordPhase, summarizeReport, ensureClaimed,
+  latestSessionNotes, lifecycle, parkTask, pinLifecycle, PIN_BASENAMES, log,
+} from "../../workflow-lib.js";
+import {
+  extractReleaseDecision, bumpVersion, extractMarkerLines,
+} from "../../extract.js";
+import { join, basename, dirname } from "path";
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, readlinkSync, appendFileSync } 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).
+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.";
+  }
+  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 " + (env.npmPackage || "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=" + (env.npmPackage || "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. Read the merge-lock state explicitly (lock-status). UNLOCKED means an empty-diff Integrate — skip gracefully: nothing merged, nothing to ship. Otherwise refresh the lock; a refresh failure parks fail-closed.\n" +
+      "2. Verified re-entry guard: 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" +
+      "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, and park at publish 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).
+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 + ".") };
+  }
+  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.
+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");
+  }
+}
+
+// recordPublishLedger — append one line to the publish-attempt ledger
+// (best-effort observability, not a gate — except the intent entry, which
+// is the machine's anchor: the caller fails loudly instead of parking an
+// unclaimable intent). Direct fs append — no agent courier on the worker
+// layer. The ts is stamped as a real UTC instant via `date` (argv, no
+// shell) — the same substitution the sandbox source performs with sed.
+// The ack scan sorts intent entries by ts, so a literal "@LEDGER_TS@"
+// placeholder would mis-order the workflow's attempt-1 entry against the
+// tick worker's re-issues. The timestamp is observability data, never a
+// decision input: no decision branch reads it.
+async function recordPublishLedger(env, entry) {
+  var ledgerDir = env.crewHome + "/.publish-ledger";
+  var ts = "";
+  try {
+    ts = String((await runCmd(["date", "-u", "+%Y-%m-%dT%H:%M:%SZ"], {})).stdout || "").trim();
+  } catch (e) {
+    ts = "";
+  }
+  var line = JSON.stringify({
+    ts: ts || "@LEDGER_TS@",
+    task_id: env.taskId,
+    workflow: env.resolvedWorkflow || "standard",
+    slug: env.publishSlug || null,
+    commit: entry.commit || null,
+    attempt: entry.attempt || null,
+    agent_id: entry.agent_id || null,
+    applied_report: entry.applied_report || null,
+    manifest_before: entry.manifest_before || null,
+    outcome: entry.outcome,
+    detail: entry.detail || "",
+    issued_at: entry.issued_at || null,
+    issuer: entry.issuer || null,
+    diff_path: entry.diff_path || null,
+    diff_sha256: entry.diff_sha256 || null,
+    base: entry.base || null,
+    publish_attempt: entry.publish_attempt || null,
+    version: entry.version || null,
+  });
+  try {
+    mkdirSync(ledgerDir, { recursive: true });
+    appendFileSync(ledgerDir + "/" + (env.publishSlug || "unknown") + ".jsonl", line + "\n", "utf8");
+    log("Noted publish outcome '" + entry.outcome + "' for task " + env.taskId + " in ledger");
+    return true;
+  } catch (e) {
+    log("Publish ledger write UNCONFIRMED for task " + env.taskId + ": " + ((e && e.message) || e));
+    return false;
+  }
+}
+
+// computeNpmTarget — deterministic pre-publish: read the registry base,
+// validate semver, compute target = base + scope. Fail-closed parks.
+async function computeNpmTarget(env, releaseDecision) {
+  var pkg = env.npmPackage || "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 has the Publish agent run exactly this one command; the worker
+// layer skips the agent and runs it mechanically).
+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.
+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.
+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.
+async function publishArtifact(env, state) {
+  var taskId = env.taskId;
+  var slug = env.publishSlug;
+
+  // 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.
+  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") {
+    log("Publish skipped for task " + taskId + ": no merge lock held (empty-diff Integrate) — nothing to ship");
+    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: "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.") };
+  }
+
+  // Verified re-entry: 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" };
+  }
+
+  // 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, { 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, { 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, { 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.
+  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,
+    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 instead of parking an orphan intent.
+    await recordPhase(env, {
+      task_id: taskId,
+      session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "failed",
+        notes: "publish-intent ledger anchor write unconfirmed — refusing to park an unclaimable intent" },
+      event: { task_id: taskId, type: "failed", identity: PHASE.identity, message: PHASE.name + " failed by " + PHASE.identity },
+    });
+    return { type: "FAILED", reason: "publish-intent ledger anchor write unconfirmed for task " + taskId + " — refusing to park an unclaimable intent" };
+  }
+  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;
+  var claimed = await ensureClaimed(env, state, PHASE);
+  if (claimed.type !== "CLAIMED") return claimed;
+
+  // Publish is optional and target-based. Empty target = prototyping
+  // project: skip the phase. 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);
+    await recordPhase(env, {
+      task_id: taskId,
+      session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "completed",
+        notes: "Publish completed — no publish target configured (nothing to ship). Advancing to QA." },
+      event: { task_id: taskId, type: "completed", identity: PHASE.identity, message: PHASE.name + " completed by " + PHASE.identity },
+    });
+    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.") };
+  }
+
+  var pg = await pinGuard(env);
+  if (pg.parked) return pg.parked;
+
+  // 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; 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);
+      await recordPhase(env, {
+        task_id: taskId,
+        session: { id: state.activeSessionId, task_id: taskId, identity: PHASE.identity, step: PHASE.name, status: "completed",
+          notes: "Publish skipped — accepted Build report declared release: no (internal-only change, nothing to ship). Advancing to QA." },
+        event: { task_id: taskId, type: "completed", identity: PHASE.identity, message: PHASE.name + " completed by " + PHASE.identity },
+      });
+      return { type: "ADVANCE", next: "QA" };
+    }
+    var ct = await computeNpmTarget(env, releaseDecision);
+    if (ct.parked) return ct.parked;
+    var target = ct.target, pkg = ct.pkg;
+
+    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.
+      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).
+  return await publishArtifact(env, state);
+}