@mmerterden/multi-agent-pipeline 11.4.0 → 12.0.0

package/pipeline/scripts/smoke-workflow-audit.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+#
+# smoke-workflow-audit.sh  -  security + correctness audit of
+# `.github/workflows/` with the two dedicated external linters:
+#
+#   - zizmor      GitHub Actions security auditor (template injection,
+#                 credential persistence, unpinned actions, ...). Runs in
+#                 offline mode so the smoke never touches the network.
+#   - actionlint  workflow correctness linter (expression syntax, matrix
+#                 typos, shellcheck of run: blocks, ...).
+#
+# Both tools are optional: each is skipped with a SKIP line when its binary
+# is not on PATH (billing-friendly CI runners install neither; run locally
+# via `brew install zizmor actionlint` for full coverage). Structural
+# baseline checks that need no external binary live in
+# smoke-ci-workflows.sh - this smoke is the deeper, tool-backed layer.
+#
+# Any finding from either tool fails the smoke.
+#
+# Exit codes: 0=pass or all tools skipped, 1=findings, 2=workflows missing
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+WF_DIR="$REPO_ROOT/.github/workflows"
+
+[ -d "$WF_DIR" ] || { echo "FAIL: .github/workflows/ missing"; exit 2; }
+
+PASS=0
+FAIL=0
+SKIPPED=0
+pass() { PASS=$((PASS + 1)); echo "  ✓ $1"; }
+fail() { FAIL=$((FAIL + 1)); echo "  ✗ $1"; }
+skip() { SKIPPED=$((SKIPPED + 1)); echo "  ↷ SKIP: $1"; }
+
+# ──────────────────────────────────────────────────────────────────────────
+echo "→ 1. zizmor (security audit, offline)"
+if command -v zizmor >/dev/null 2>&1; then
+  # Flag names shifted across zizmor releases (--offline vs --no-online-audits);
+  # probe --help so the smoke works with whichever is installed.
+  HELP=$(zizmor --help 2>&1 || true)
+  OFFLINE_FLAG="--offline"
+  echo "$HELP" | grep -q -- '--offline' || OFFLINE_FLAG="--no-online-audits"
+  if OUT=$(zizmor "$WF_DIR" --min-severity medium "$OFFLINE_FLAG" 2>&1); then
+    pass "zizmor: no findings at medium+ severity"
+  else
+    fail "zizmor reported findings (medium+ severity)"
+    echo "$OUT" | sed 's/^/    /'
+  fi
+else
+  skip "zizmor not on PATH (brew install zizmor)"
+fi
+
+# ──────────────────────────────────────────────────────────────────────────
+echo "→ 2. actionlint (workflow correctness)"
+if command -v actionlint >/dev/null 2>&1; then
+  if OUT=$(cd "$REPO_ROOT" && actionlint 2>&1); then
+    pass "actionlint: no findings"
+  else
+    fail "actionlint reported findings"
+    echo "$OUT" | sed 's/^/    /'
+  fi
+else
+  skip "actionlint not on PATH (brew install actionlint)"
+fi
+
+echo ""
+echo "══ smoke-workflow-audit: $PASS passed, $FAIL failed, $SKIPPED skipped ══"
+[ "$FAIL" -gt 0 ] && exit 1 || exit 0

package/pipeline/scripts/test-gap-scan.mjs

@@ -114,7 +114,18 @@ function isExcluded(path) {
     if (pat.endsWith("/")) {
       if (path.includes(pat) || path.startsWith(pat)) return true;
     } else if (pat.includes("**")) {
-      const re = new RegExp("^" + pat.replace(/\./g, "\\.").replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*") + "$");
+      // Tokenize ** before the single-* pass so the * rewrite cannot mangle
+      // the already-translated .* (which broke cross-directory matches).
+      const DOUBLE_STAR = "\u0000";
+      const re = new RegExp(
+        "^" +
+          pat
+            .replace(/\./g, "\\.")
+            .replace(/\*\*/g, DOUBLE_STAR)
+            .replace(/\*/g, "[^/]*")
+            .replace(new RegExp(DOUBLE_STAR, "g"), ".*") +
+          "$",
+      );
       if (re.test(path)) return true;
     } else if (path.endsWith(pat)) return true;
   }

package/pipeline/scripts/triage-memory.mjs

@@ -110,7 +110,16 @@ function score(queryTokens, row) {
 }
 
 function globToRegExp(glob) {
-  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*").replace(/\?/g, ".");
+  // Tokenize ** before the single-* pass: a sequential replace would turn
+  // ** into .* and then the global * pass would rewrite it to .[^/]*,
+  // breaking cross-directory matches (src/**/x vs src/a/b/x).
+  const DOUBLE_STAR = "\u0000";
+  const escaped = glob
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*/g, DOUBLE_STAR)
+    .replace(/\*/g, "[^/]*")
+    .replace(/\?/g, ".")
+    .replace(new RegExp(DOUBLE_STAR, "g"), ".*");
   return new RegExp("^" + escaped + "$", "i");
 }
 

package/pipeline/scripts/uninstall.mjs

@@ -12,30 +12,63 @@
  *   node uninstall.mjs                  # interactive, removes from all installed targets
  *   node uninstall.mjs --yes            # skip prompts, remove from all
  *   node uninstall.mjs --claude         # only Claude Code
+ *   node uninstall.mjs --all-data       # ALSO remove pipeline settings + logs/state/metrics
  *   node uninstall.mjs --cursor --target=/path/to/repo   # legacy adapter-file cleanup
  *   node uninstall.mjs --dry-run        # report what would be removed, change nothing
  *
  * Targeted by:
- *   - `/multi-agent:delete` slash command (Claude Code)
- *   - `multi-agent-delete` skill (Copilot CLI)
+ *   - `/multi-agent:uninstall` slash command (Claude Code)
+ *   - `multi-agent-uninstall` skill (Copilot CLI)
  *   - `npx @mmerterden/multi-agent-pipeline uninstall` (direct CLI)
  *
- * Always preserved:
- *   - $HOME/.claude/CLAUDE.md (user customizations)
- *   - $HOME/.claude/multi-agent-preferences.json
+ * Always preserved (both modes):
  *   - Personal access tokens in the OS credential store
+ *   - $HOME/.claude/CLAUDE.md (user customizations)
+ *   - $HOME/.claude/rules/ (user-owned; installed write-if-missing)
  *   - User content outside the `<!-- multi-agent-pipeline:begin/end -->` markers
  *     in shared rules files (copilot-instructions.md)
  *
+ * Preserved by default, removed with --all-data:
+ *   - $HOME/.claude/multi-agent-preferences.json (pipeline settings)
+ *   - $HOME/.claude/logs/multi-agent/ (task logs, state, metrics, audit trail)
+ *
  * @module pipeline/scripts/runtime/uninstall
  */
 
 import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "fs";
 import { join } from "path";
+import { pathToFileURL } from "url";
 import { createInterface } from "readline";
 
 const HOME = process.env.HOME || process.env.USERPROFILE;
 
+/**
+ * Agent definition files the pipeline ships (pipeline/agents/). This runs
+ * standalone from ~/.claude/scripts, so the list is static here; a unit test
+ * (test/uninstall.test.mjs) asserts it matches the source tree so it cannot
+ * go stale. Only these file names are removed from the installed agents
+ * dirs - user-authored agent files are never touched.
+ */
+export const PIPELINE_AGENT_FILES = [
+  "android-architect.md",
+  "backend-architect.md",
+  "code-reviewer.md",
+  "dev-critic.md",
+  "explorer.md",
+  "ios-architect.md",
+  "security-auditor.md",
+  "task-clarifier.md",
+];
+
+/**
+ * Non-multi-agent core skills the installer ships from
+ * pipeline/skills/shared/core/ (the multi-agent* dirs are matched by prefix).
+ */
+export const PIPELINE_CORE_SKILL_DIRS = [
+  "apple-archive-compliance",
+  "google-play-compliance",
+];
+
 const flags = process.argv.slice(2).filter((a) => a !== "uninstall");
 
 const TOOL_FLAGS = [
@@ -58,6 +91,9 @@ const forCodex = flags.includes("--codex") || flags.includes("--all") || !explic
 
 const dryRun = flags.includes("--dry-run");
 const skipPrompt = flags.includes("--yes") || flags.includes("-y");
+// Full cleanup: also remove pipeline settings + the multi-agent log root
+// (task logs, state, metrics, audit). Tokens, CLAUDE.md and rules/ stay.
+const allData = flags.includes("--all-data");
 
 const adapterTarget = (() => {
   const raw = flags.find((f) => f.startsWith("--target="));
@@ -122,6 +158,33 @@ function rmMatchingFiles(parent, predicate) {
   return count;
 }
 
+// Explicit terminator install/copilot.mjs writes after the pipeline section
+// (v11.4.1+). Must stay in sync with INSTRUCTIONS_END_MARKER there.
+const COPILOT_END_MARKER = "<!-- multi-agent-pipeline:copilot-instructions:end -->";
+
+/**
+ * Legacy copilot-instructions files (written before the end marker existed)
+ * have no explicit terminator. Bound the pipeline span at the next top-level
+ * "# " heading after the start marker when one exists OUTSIDE fenced code
+ * blocks (the pipeline body carries bash comments like "# Bootstrap once ..."
+ * inside fences); otherwise the span runs to EOF (pre-marker behavior).
+ * Mirrors install/copilot.mjs legacyTrailingContent.
+ * @param {string} section - content from the start marker onward
+ * @returns {string} user content trailing the pipeline span ("" if none)
+ */
+function legacyTrailingContent(section) {
+  const lines = section.split("\n");
+  let inFence = false;
+  for (let i = 1; i < lines.length; i++) {
+    if (/^\s*(```|~~~)/.test(lines[i])) {
+      inFence = !inFence;
+      continue;
+    }
+    if (!inFence && /^# /.test(lines[i])) return lines.slice(i).join("\n");
+  }
+  return "";
+}
+
 /**
  * Strip a marker-wrapped `<!-- multi-agent-pipeline:begin/end -->` block from
  * a user-owned file. Preserves everything outside the markers. Deletes the
@@ -135,25 +198,33 @@ function stripManagedBlock(filePath) {
     /\s*<!-- multi-agent-pipeline:begin -->[\s\S]*?<!-- multi-agent-pipeline:end -->\s*/m;
   if (!re.test(content)) {
     // Copilot's install (install/copilot.mjs) does not wrap the block in
-    // begin/end markers; it always writes the pipeline section LAST, from the
-    // `# Multi-Agent Development Pipeline` heading to EOF, keeping any user
-    // content ABOVE it. So slicing from that heading to EOF reliably removes
-    // only our section regardless of file size (no arbitrary size cap - a cap
-    // used to orphan the block in files >50 KB).
+    // begin/end markers. v11.4.1+ writes an explicit end marker after the
+    // pipeline section; strip only the start..end span so user content BELOW
+    // the section survives. Legacy files without the end marker are bounded
+    // at the next top-level heading outside code fences, else EOF.
     if (content.includes("# Multi-Agent Development Pipeline")) {
-      // Heuristic: Copilot's generateCopilotInstructions output. Only strip the
-      // pipeline section, not the whole file.
       const marker = "# Multi-Agent Development Pipeline";
       const idx = content.indexOf(marker);
       if (idx >= 0) {
         const before = content.slice(0, idx).trimEnd();
+        const fromStart = content.slice(idx);
+        const endIdx = fromStart.indexOf(COPILOT_END_MARKER);
+        const rawTrailing =
+          endIdx >= 0
+            ? fromStart.slice(endIdx + COPILOT_END_MARKER.length)
+            : legacyTrailingContent(fromStart);
+        const trailing = rawTrailing.replace(/^[\r\n]+/, "").trimEnd();
+        let remaining = before;
+        if (trailing.length > 0) {
+          remaining = before.length > 0 ? before + "\n\n" + trailing : trailing;
+        }
         if (dryRun) {
           report("would update", filePath);
-        } else if (before.length === 0) {
+        } else if (remaining.length === 0) {
           rmSync(filePath, { force: true });
           console.log(`    removed (was pipeline-only): ${filePath}`);
         } else {
-          writeFileSync(filePath, before + "\n");
+          writeFileSync(filePath, remaining + "\n");
           console.log(`    cleaned pipeline section: ${filePath}`);
         }
         return true;
@@ -200,9 +271,12 @@ function cleanClaudeSettings(settingsPath) {
 
   if (settings.hooks?.PreToolUse?.length) {
     const before = settings.hooks.PreToolUse.length;
+    // Match both the current matcher ("Bash") and the dead pre-v11.4.1 one
+    // ("Bash(git commit:*)"); the pre-commit-check.sh command identifies the
+    // entry as ours either way.
     settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
       (h) =>
-        !(h.matcher === "Bash(git commit:*)" &&
+        !((h.matcher === "Bash" || h.matcher === "Bash(git commit:*)") &&
           h.hooks?.some((sub) => sub.command?.includes("pre-commit-check.sh"))),
     );
     if (settings.hooks.PreToolUse.length < before) touched = true;
@@ -239,18 +313,24 @@ async function main() {
   if (dryRun) console.log("  [DRY-RUN] Nothing will be modified.");
   console.log("");
   console.log("  Targets:");
-  if (forClaude) console.log("    - Claude Code (~/.claude/{commands,skills,agents,rules,scripts}/multi-agent*)");
-  if (forCopilot) console.log("    - Copilot CLI (~/.copilot/{skills,agents,scripts}/multi-agent* + copilot-instructions.md section)");
+  if (forClaude) console.log("    - Claude Code (~/.claude/{commands/multi-agent, scripts, multi-agent-refs, schemas, lib} + pipeline skills + pipeline agent files)");
+  if (forCopilot) console.log("    - Copilot CLI (~/.copilot/{scripts, schemas, lib} + pipeline skills + pipeline agent files + copilot-instructions.md section)");
   if (forCursor) console.log(`    - Cursor (${adapterTarget}/.cursor/rules/multi-agent-* + .cursorrules)`);
   if (forCopilotChat) console.log(`    - GitHub Copilot Chat (${adapterTarget}/.github/copilot-instructions.md block + .github/instructions/multi-agent-*)`);
   if (forAntigravity) console.log(`    - Antigravity (${adapterTarget}/.agent/rules + .agent/workflows + AGENTS.md block + .agent/mcp_config.json)`);
   if (forCodex) console.log("    - OpenAI Codex CLI (~/.codex/prompts/multi-agent.md + AGENTS.md block + config.toml mcp block)");
   console.log("");
+  if (allData) {
+    console.log("  FULL CLEANUP (--all-data) also removes:");
+    console.log("    - ~/.claude/multi-agent-preferences.json (pipeline settings)");
+    console.log("    - ~/.claude/logs/multi-agent/ (task logs, state, metrics, audit trail)");
+    console.log("");
+  }
   console.log("  PRESERVED (never touched):");
   console.log("    - Personal access tokens in OS credential store (Keychain / Credential Manager / libsecret)");
   console.log("    - ~/.claude/CLAUDE.md (your customizations)");
   console.log("    - ~/.claude/rules/ (user-owned; installed write-if-missing, never overwritten)");
-  console.log("    - ~/.claude/multi-agent-preferences.json (your settings)");
+  if (!allData) console.log("    - ~/.claude/multi-agent-preferences.json (your settings)");
   console.log("    - Your own content in copilot-instructions.md above the pipeline section");
   console.log("");
 
@@ -265,6 +345,11 @@ async function main() {
     const CLAUDE = join(HOME, ".claude");
     rmIfExists(join(CLAUDE, "commands", "multi-agent"));
     rmIfExists(join(CLAUDE, "scripts"));
+    // Pipeline-managed trees the installer lays down alongside scripts/.
+    rmIfExists(join(CLAUDE, "multi-agent-refs"));
+    rmIfExists(join(CLAUDE, "schemas"));
+    rmIfExists(join(CLAUDE, "lib"));
+    rmIfExists(join(CLAUDE, ".pipeline-version"));
     // NOTE: ~/.claude/rules/ is USER-OWNED. install lays baseline rules down
     // write-if-missing and NEVER overwrites them (install/claude.mjs
     // installRules, skipExisting) so users can evolve their global rules
@@ -274,20 +359,14 @@ async function main() {
     const skills = join(CLAUDE, "skills");
     let n = rmMatchingDirs(skills, (name) => name === "multi-agent" || name.startsWith("multi-agent-"));
     n += rmMatchingDirs(skills, (name) => name === "figma-ios" || name === "figma-android" || name === "figma-common" || name === "figma-to-component");
+    n += rmMatchingDirs(skills, (name) => PIPELINE_CORE_SKILL_DIRS.includes(name));
     if (n > 0) console.log(`    removed ${n} skill dir(s) under ${skills}`);
     rmIfExists(join(skills, ".skills-index.json"));
     rmIfExists(join(skills, "skills-index.md"));
     rmIfExists(join(skills, "README.md"));
-    rmMatchingDirs(join(CLAUDE, "agents"), (name) =>
-      [
-        "code-reviewer.md",
-        "explorer.md",
-        "ios-architect.md",
-        "android-architect.md",
-        "backend-architect.md",
-        "security-auditor.md",
-      ].includes(name),
-    );
+    // Agent definitions are FILES; remove only the pipeline-shipped names so
+    // user-authored agents survive.
+    rmMatchingFiles(join(CLAUDE, "agents"), (name) => PIPELINE_AGENT_FILES.includes(name));
     cleanClaudeSettings(join(CLAUDE, "settings.json"));
   }
 
@@ -296,24 +375,34 @@ async function main() {
     console.log("  [Copilot CLI] Removing...");
     const COP = join(HOME, ".copilot");
     rmIfExists(join(COP, "scripts"));
+    // Pipeline-managed trees the installer lays down alongside scripts/.
+    rmIfExists(join(COP, "schemas"));
+    rmIfExists(join(COP, "lib"));
+    rmIfExists(join(COP, ".pipeline-version"));
     const skills = join(COP, "skills");
     let n = rmMatchingDirs(skills, (name) => name === "multi-agent" || name.startsWith("multi-agent-"));
     n += rmMatchingDirs(skills, (name) => name === "figma-ios" || name === "figma-android" || name === "figma-common" || name === "figma-to-component");
+    n += rmMatchingDirs(skills, (name) => PIPELINE_CORE_SKILL_DIRS.includes(name));
     if (n > 0) console.log(`    removed ${n} skill dir(s) under ${skills}`);
+    rmIfExists(join(skills, ".skills-index.json"));
+    rmIfExists(join(skills, "skills-index.md"));
     rmIfExists(join(skills, "README.md"));
-    rmMatchingDirs(join(COP, "agents"), (name) =>
-      [
-        "code-reviewer.md",
-        "explorer.md",
-        "ios-architect.md",
-        "android-architect.md",
-        "backend-architect.md",
-        "security-auditor.md",
-      ].includes(name),
-    );
+    // Agent definitions are FILES; remove only the pipeline-shipped names so
+    // user-authored agents survive.
+    rmMatchingFiles(join(COP, "agents"), (name) => PIPELINE_AGENT_FILES.includes(name));
     stripManagedBlock(join(COP, "copilot-instructions.md"));
   }
 
+  // Full cleanup: pipeline settings + the multi-agent log root. Both are
+  // pipeline-generated data (not user-authored like CLAUDE.md / rules), so
+  // --all-data removes them; the default run leaves them in place.
+  if (allData && HOME) {
+    console.log("");
+    console.log("  [Full cleanup] Removing pipeline settings + logs...");
+    rmIfExists(join(HOME, ".claude", "multi-agent-preferences.json"));
+    rmIfExists(join(HOME, ".claude", "logs", "multi-agent"));
+  }
+
   // Legacy adapter-file cleanup (adapters removed in v10.7.0). These blocks
   // delete files a pre-v10.7.0 install generated; they never touch user files
   // outside the multi-agent-* namespace / managed markers.
@@ -360,6 +449,15 @@ async function main() {
 
   console.log("");
   console.log("  ✓ Pipeline removed.");
+  if (!allData) {
+    console.log("");
+    console.log("  Kept your pipeline settings + logs. To remove those too, re-run with --all-data.");
+  } else {
+    console.log("");
+    console.log("  Full cleanup done. Still on disk (user-owned, remove by hand if you want a bare system):");
+    console.log("    - ~/.claude/CLAUDE.md");
+    console.log("    - ~/.claude/rules/");
+  }
   console.log("");
   console.log("  Personal access tokens were NOT touched. Inspect with:");
   console.log("    macOS:   security find-generic-password -s \"<service>\" -w");
@@ -370,7 +468,13 @@ async function main() {
   console.log("");
 }
 
-main().catch((e) => {
-  console.error("uninstall failed:", e.message);
-  process.exit(1);
-});
+// Run only when executed directly (node uninstall.mjs). Guard lets tests
+// import the exported constants without triggering the uninstall.
+const isMainModule =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMainModule) {
+  main().catch((e) => {
+    console.error("uninstall failed:", e.message);
+    process.exit(1);
+  });
+}

package/pipeline/scripts/update-check.sh

@@ -46,6 +46,15 @@ if [ -z "$LOCAL_VERSION" ]; then
     fi
   done
 fi
+# npx-only installs have no repo clone; the installer stamps the version here.
+if [ -z "$LOCAL_VERSION" ]; then
+  for marker in "$HOME/.claude/.pipeline-version" "$HOME/.copilot/.pipeline-version"; do
+    if [ -f "$marker" ]; then
+      LOCAL_VERSION=$(head -1 "$marker" 2>/dev/null | tr -d '[:space:]')
+      [ -n "$LOCAL_VERSION" ] && break
+    fi
+  done
+fi
 [ -z "$LOCAL_VERSION" ] && exit 0  # cannot determine local version -> silent no-op
 
 now=$(date +%s)

package/pipeline/scripts/update-issue-progress.sh

@@ -29,12 +29,63 @@
 
 set -euo pipefail
 
+# Rewrite the `### Progress` block of the body file ($2) with $1 and print the
+# result to stdout. The replaced region is bounded at the FIRST of:
+#   - a line starting with `<!--` (the legend comment, printed and kept), or
+#   - the next heading line (^#, printed and kept), or
+#   - EOF.
+# Bounding at the next heading matters: bodies without the legend comment used
+# to have everything from the table to EOF silently dropped and persisted.
+rewrite_progress_body() {
+  # Block passed via environment: BSD awk rejects literal newlines in -v
+  # assignments ("newline in string"), so -v cannot carry the table.
+  NEW_BLOCK_ENV="$1" awk '
+    BEGIN { new_block = ENVIRON["NEW_BLOCK_ENV"] }
+    BEGIN { in_progress = 0 }
+    /^### Progress/ {
+      print
+      print ""
+      print new_block
+      print ""
+      in_progress = 1
+      next
+    }
+    in_progress && /^<!--/ { in_progress = 0; print; next }
+    in_progress && /^#/    { in_progress = 0; print; next }
+    in_progress { next }
+    { print }
+  ' "$2"
+}
+
+build_progress_block() {
+  cat <<EOF
+| Flag | State |
+|---|---|
+| Implementation | ${1} |
+| Testing        | ${2} |
+| Code Connect   | ${3} |
+| Wiki           | ${4} |
+EOF
+}
+
 TASK_ID="${1:-}"
 if [ -z "$TASK_ID" ]; then
   echo "usage: update-issue-progress.sh <task-id>" >&2
   exit 64
 fi
 
+# Internal test seam: `--rewrite <body-file>` runs only the Progress-block
+# rewrite (placeholder glyphs) and prints the result. No state, no gh.
+if [ "$TASK_ID" = "--rewrite" ]; then
+  BODY_IN="${2:-}"
+  if [ -z "$BODY_IN" ] || [ ! -f "$BODY_IN" ]; then
+    echo "usage: update-issue-progress.sh --rewrite <body-file>" >&2
+    exit 64
+  fi
+  rewrite_progress_body "$(build_progress_block "⚪" "⚪" "⚪" "⚪")" "$BODY_IN"
+  exit 0
+fi
+
 # Resolve the project state directory (matches phase-tracker convention).
 STATE_GLOB="$HOME/.claude/projects/*"
 AGENT_STATE=""
@@ -75,9 +126,9 @@ F_WIKI=$(jq -r '.flags.wiki          // false' "$AGENT_STATE")
 # Each flag may be: true | false | "yellow" (validated against older impl).
 glyph_for() {
   case "$1" in
-    true|"true")    echo "🟢" ;;
-    yellow|"yellow") echo "🟡" ;;
-    *)              echo "⚪" ;;
+    true)   echo "🟢" ;;
+    yellow) echo "🟡" ;;
+    *)      echo "⚪" ;;
   esac
 }
 
@@ -87,49 +138,17 @@ G_CC=$(glyph_for "$F_CC")
 G_WIKI=$(glyph_for "$F_WIKI")
 
 # Fetch current body, replace the Progress table, write back.
-TMP_BODY=$(mktemp /tmp/issue-progress-${TASK_ID}-XXXXXX.md)
+TMP_BODY=$(mktemp /tmp/issue-progress-"${TASK_ID}"-XXXXXX.md)
 trap 'rm -f "$TMP_BODY"' EXIT
 
 gh issue view "$ISSUE_NUM" --repo "$ORG_REPO" --json body --jq .body > "$TMP_BODY"
 
 # Build the new Progress block.
-NEW_BLOCK=$(cat <<EOF
-| Flag | State |
-|---|---|
-| Implementation | ${G_IMPL} |
-| Testing        | ${G_TEST} |
-| Code Connect   | ${G_CC} |
-| Wiki           | ${G_WIKI} |
-EOF
-)
-
-# Replace the table between `### Progress` and the next `<!--` HTML comment.
-# Use awk to keep the legend comment in place.
-awk -v new_block="$NEW_BLOCK" '
-  BEGIN { in_progress = 0; replaced = 0 }
-  /^### Progress/ {
-    print
-    print ""
-    print new_block
-    print ""
-    in_progress = 1
-    replaced = 1
-    next
-  }
-  in_progress && /^<!--/ {
-    in_progress = 0
-    print
-    next
-  }
-  in_progress { next }
-  { print }
-  END {
-    if (replaced == 0) {
-      # Body had no Progress section; nothing to replace.
-      exit 0
-    }
-  }
-' "$TMP_BODY" > "${TMP_BODY}.new"
+NEW_BLOCK=$(build_progress_block "$G_IMPL" "$G_TEST" "$G_CC" "$G_WIKI")
+
+# Replace the table between `### Progress` and the first terminator (legend
+# comment, next heading, or EOF)  -  see rewrite_progress_body above.
+rewrite_progress_body "$NEW_BLOCK" "$TMP_BODY" > "${TMP_BODY}.new"
 
 # Check if body actually changed (idempotent no-op).
 if cmp -s "$TMP_BODY" "${TMP_BODY}.new"; then

package/pipeline/scripts/write-state.mjs

@@ -130,6 +130,10 @@ function isLockStale(lockPath, staleMs) {
   }
 }
 
+// Path whose lock this process currently holds (null when none). Lets the
+// top-level error handler release our lock on unexpected failures.
+let heldLockFor = null;
+
 /** @param {string} path */
 function releaseLock(path) {
   const lockPath = `${path}.lock`;
@@ -138,6 +142,7 @@ function releaseLock(path) {
   } catch {
     /* already gone  -  fine */
   }
+  if (heldLockFor === path) heldLockFor = null;
 }
 
 /**
@@ -178,6 +183,7 @@ async function main() {
 
   try {
     await acquireLock(path);
+    heldLockFor = path;
   } catch (err) {
     if (err.code === "LOCK_TIMEOUT") {
       console.error(err.message);
@@ -187,6 +193,10 @@ async function main() {
     process.exit(3);
   }
 
+  // process.exit() inside a try block skips `finally`, so every exit path in
+  // here must release OUR lock explicitly before exiting - otherwise a corrupt
+  // state file (or any I/O error) leaks agent-state.json.lock and blocks the
+  // next writer until the stale-lock window elapses.
   try {
     let next;
     if (replace) {
@@ -198,8 +208,7 @@ async function main() {
         try {
           current = JSON.parse(readFileSync(path, "utf-8"));
         } catch (err) {
-          console.error(`write-state: existing state unreadable  -  ${err.message}`);
-          process.exit(3);
+          throw new Error(`existing state unreadable  -  ${err.message}`, { cause: err });
         }
       }
       next = deepMerge(current, payload);
@@ -210,15 +219,16 @@ async function main() {
     renameSync(tmp, path); // atomic on POSIX
   } catch (err) {
     console.error(`write-state: ${err.message}`);
-    process.exit(3);
-  } finally {
     releaseLock(path);
+    process.exit(3);
   }
 
+  releaseLock(path);
   process.exit(0);
 }
 
 main().catch((err) => {
   console.error(`write-state: unhandled  -  ${err.message}`);
+  if (heldLockFor) releaseLock(heldLockFor);
   process.exit(3);
 });