@mmerterden/multi-agent-pipeline 13.3.0 → 13.5.0

package/CHANGELOG.md

@@ -16,6 +16,137 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [13.5.0] - 2026-07-28
+
+### Fixed
+
+- **Every fetcher died on a Copilot-only or Codex-only install.** Eleven runtime scripts
+  loaded `credential-store-resolver.sh` as `. "$HOME/.claude/lib/..." || . <next> || {
+  error }`, all of them under `set -e`. Sourcing a file that does not exist aborts the
+  shell outright - `||` included - so on a host without `~/.claude/lib` the chain reached
+  neither its later candidates nor its error branch: bare exit 1, no message. Reordering
+  does not help, because whichever candidate is absent aborts at that point. All eleven
+  now check `[ -f ]` before sourcing and decide on `$CRED_STORE`, and the resolver ends
+  with `resolve_credential_store || :` so sourcing it can never trip a caller's `set -e`.
+- The resolver only knew about `~/.claude` and `~/.copilot`. A Codex-only install could
+  not locate the credential helper at all, while the file sat in `~/.codex/lib`.
+- **Copilot CLI registered no MCP server.** Codex had registration from the day its
+  installer was written; Copilot never did, so it carried all 257 pipeline skills and
+  could not call one of the 80 dev-toolkit tools those skills depend on. Both hosts now
+  go through the shared `install/_mcp-register.mjs`, which also treats Copilot's
+  `already exists` (exit 1, unlike Codex's replace-and-exit-0) as the desired end state
+  rather than reporting a working registration as a failed install. Uninstall deregisters
+  on both.
+- **`figma-mcp-refresh.sh` called macOS `security` directly**, so silent Figma MCP token
+  renewal - the path that keeps every Figma consumer on Tier 1 - never worked on Linux or
+  Windows, and surfaced as an unexplained expired-token prompt. It now goes through
+  `credential-store.sh` with the `set <key> -` stdin form, which keeps the secret off
+  argv on every platform, the property the old `security -i` call was preserving.
+- **`phase-tracker.sh` hashed with a bare `shasum`** - a perl script absent from slim
+  Linux images. Where it was missing, OTel trace and span ids came back empty: valid
+  JSON, useless telemetry, no error. Same for `post-pr-review.sh`, where an empty
+  fingerprint made every finding look new and re-posted the whole review each iteration.
+- `audit-log.sh` fell back to printing `unhashed:<url>` when no hasher was available,
+  writing the plaintext remote - credentials included, if the URL carried any - into the
+  audit log that hashing exists to protect. It emits a marker instead.
+- `smoke-write-state.sh` counted an honest exit-2 lock timeout as data loss, because it
+  read the final state without looking at exit codes. That made it fail once inside a
+  fully loaded suite run while passing 12/12 in isolation - a flake that read as a
+  data-loss bug and would eventually have been "fixed" by lowering the writer count,
+  removing the regression detection the test exists for. It now asserts the real
+  invariant: no writer reports success while losing its update.
+- `smoke-token-preflight.sh` asserted the literal `security add-generic-password`, which
+  pinned the implementation to macOS. It now asserts the portable route and fails if a
+  direct platform keychain call comes back.
+- `multi-agent-refs/rules.md` pointed at `~/.claude/scripts/vercel-deploy.sh`; the
+  wrapper installs to `lib/` with the other shell libraries.
+
+### Added
+
+- **`smoke-shell-portability.sh`** (8 assertions) over every shell file that ships to a
+  user tree: single-platform hashing without a fallback, unguarded BSD/GNU-divergent
+  constructs, hardcoded absolute home paths, direct platform keychain calls, and the
+  `.`-chain-under-`set -e` trap above. It found the `post-pr-review.sh` hasher and the
+  `figma-mcp-refresh.sh` keychain call on its first run.
+- `smoke-install-layout.sh --update-fixture` regenerates the layout fixture from the tree
+  the gate itself installs, probe plugin included. The documented hand-rolled recipe
+  omitted it, so following it baked a three-file shortfall into the fixture.
+
+## [13.4.0] - 2026-07-28
+
+### Added
+
+- **`credential-inventory.sh`** - one command that answers "what can I reach right now?"
+  A run asked the user to paste a Crashlytics stack trace by hand, offering the manual
+  path as the fastest route, while a valid Firebase service-account JSON sat in the
+  Keychain mapped as `firebase` and resolving fine. Nothing had failed: the pipeline
+  simply never asked itself whether it already held a credential that answered the
+  question. The tool reports `present` / `mapped-but-missing` / `unmapped` per logical
+  key plus what each one unlocks, and `keychain.md` Rule 2 now binds every question that
+  requests external data to its output - ask for the pointer (the issue URL), never for
+  the payload. Values are never printed.
+- `--probe` verifies that configured credentials actually answer, because "the key is in
+  the Keychain" and "the service replies" are different claims that the user fixes in
+  different ways. The verdicts stay separate on purpose: `auth-rejected` (refresh the
+  token), `unreachable` (on a corporate host, almost always the VPN),
+  `no-host-configured` (a token with nowhere to point), `well-formed` (valid shape,
+  liveness needs more input), `not-probeable`. Collapsing them into one "failed" bucket
+  is what led the user to three different wrong actions. Only configured credentials are
+  probed - an unmapped key is a capability the user chose not to enable.
+- `smoke-credential-awareness.sh` (32 assertions) and `test/phase0-exit-gate.test.mjs`
+  (20 cases) lock all of the above, including two secret-leak checks and the rule that
+  the credential reaches curl through a stdin config rather than argv, where any `ps`
+  could read it.
+- `smoke-install-layout.sh --update-fixture` regenerates the layout fixture from the
+  tree the gate itself installs. The documented hand-rolled recipe omitted the seeded
+  probe plugin, so following it baked a three-file shortfall into the fixture and the
+  next run failed on a drift that was really a bad regen.
+
+### Fixed
+
+- **The Phase 0 exit gate now asserts that the pickers ran.** It checked `taskType` and
+  the Figma access tier only, so a run that skipped the project and branch pickers and
+  developed straight on the local checkout passed cleanly - which is exactly what a
+  reported run did with a Jira ID. The gate now also requires `baseBranch`,
+  a `baseFetchStatus` from the known set, and a worktree path distinct from the project
+  root. Branch selection is marked non-skippable in `phase-0-init.md`, in every mode:
+  `--dev` skips the LLM phases, not Phase 0's pickers.
+- **An unreachable external source is announced instead of absorbed.** Exit code `3`
+  used to mean "mark it failed and continue", so an expired token and a VPN-off remote
+  both reached the analysis phase as *no data*, indistinguishable from a ticket that
+  referenced nothing. The run then planned from a partial picture and reported success.
+  `external-context-injection.md` now classifies the stderr and surfaces a decision -
+  refresh the credential, connect the VPN and retry, supply a current URL, or continue
+  without - records `userDecision` in state, and requires autopilot to report what it
+  skipped rather than hide it. Retry is a real branch, not a label.
+- The base-branch and fetch-failure pickers were still written as ASCII numbered menus
+  in `phase-0-init.md`, against the picker contract's native-widget rule. Both are now
+  expressed as picker options, and the fetch-failure question names the corporate host
+  when the remote points at one - a host that will not resolve is almost always the VPN,
+  and saying so is the difference between a five-second fix and a run built on a stale ref.
+- `credential-inventory.sh --json` returned empty arrays while the table mode looked
+  correct: `python3 - <<EOF` takes its script from stdin, so the piped payload never
+  reached `sys.stdin`. Caught by the new gate on its first run.
+- The probe read hosts from `global.<service>Host`; the real path is
+  `global.hosts.<service>`, so every self-hosted service reported
+  `no-host-configured`. Found by running the probe against the real preferences instead
+  of trusting the field name.
+- `figma_mcp` is an OAuth token for the MCP server, not a REST PAT: probing it against
+  `api.figma.com` returned 403 for a healthy token and would have sent the user to
+  regenerate something that worked. It is now reported as not-probeable, with liveness
+  left to `figma-mcp-refresh.sh`, which owns the grant.
+- A failed `curl` wrote `000` through `write-out` *and* triggered the `|| echo "000"`
+  fallback, producing `000000` and a bogus verdict for what was simply a closed VPN.
+  Any non-three-digit status now reads as `probe-error` rather than being dressed up as
+  a service verdict.
+- `multi-agent-refs/rules.md` pointed at `~/.claude/scripts/vercel-deploy.sh`; the
+  wrapper installs to `lib/` with the other shell libraries. It had been reported as a
+  dangling reference for several releases.
+- `/multi-agent:setup` no longer describes an unreachable discovery source as skipped
+  "silently". Setup is where the user is configuring things, so a source that could not
+  be reached is precisely what they need told, with the classification that decides
+  their next move.
+
 ## [13.3.0] - 2026-07-28
 
 ### Added

package/install/_mcp-register.mjs

@@ -0,0 +1,125 @@
+/**
+ * Register the companion MCP server with a host CLI.
+ *
+ * WHY THIS IS SHARED
+ *
+ * Codex got MCP registration when its installer was written; Copilot never did. The
+ * result was a host that carried all 257 pipeline skills and could not call a single
+ * one of the 80 dev-toolkit tools those skills depend on - `design-check`, every
+ * `ios_*` / `android_*` simulator call, the archive audits. Nothing failed at install
+ * time, and the skills only fail when a run actually reaches for a tool.
+ *
+ * Both CLIs take the same shape (`<cli> mcp add <name> -- <command> [args...]`) and
+ * both write their own user-level config, so the difference was purely that one
+ * installer called it and the other did not. One implementation, two callers.
+ *
+ * @module install/_mcp-register
+ */
+
+import { execFileSync } from "child_process";
+import { existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+import { isDryRun } from "./_common.mjs";
+
+export const MCP_SERVER_NAME = "dev-toolkit";
+export const MCP_SERVER_PACKAGE = "@mmerterden/dev-toolkit-mcp";
+
+/**
+ * Where each host's CLI might live.
+ *
+ * A bare name is resolved through PATH by execFileSync. The explicit paths matter for
+ * Copilot: `copilot` is frequently a *shell alias* for `gh copilot`, and an alias is
+ * invisible to execFileSync - so a PATH-only lookup reports "not on PATH" on a machine
+ * where the user runs `copilot` every day. `gh` installs the real binary under
+ * ~/.local/share/gh/copilot/.
+ */
+const CLI_CANDIDATES = Object.freeze({
+  codex: ["codex"],
+  copilot: ["copilot", join(homedir(), ".local", "share", "gh", "copilot", "copilot")],
+});
+
+/**
+ * First candidate that exists as a file, or the first bare name to let PATH resolution
+ * try. Returning a bare name rather than null keeps the "not on PATH" diagnosis in one
+ * place: the execFileSync catch.
+ *
+ * @param {"codex"|"copilot"} host
+ * @returns {string}
+ */
+function resolveCli(host) {
+  const candidates = CLI_CANDIDATES[host] || [host];
+  for (const c of candidates) {
+    if (c.includes("/") && existsSync(c)) return c;
+  }
+  return candidates[0];
+}
+
+/**
+ * Register the MCP server. Idempotent from the caller's point of view, though the two
+ * CLIs get there differently:
+ *
+ * - `codex mcp add` replaces an existing entry and exits 0.
+ * - `copilot mcp add` refuses, printing `Server "<name>" already exists` and exiting 1.
+ *
+ * So a non-zero exit is not automatically a failure. An already-registered server is
+ * the desired end state, and reporting it as "skipped MCP registration (Command
+ * failed)" would send the user to fix something that is already correct - which is
+ * exactly what the first version of this did.
+ *
+ * The existing entry is left alone rather than removed and re-added: a user may have
+ * added env vars or switched the command to a local checkout, and an installer has no
+ * business discarding that.
+ *
+ * Never fatal: a missing CLI or a failed write must not fail the install, because the
+ * rest of the tree is still correct and useful. It prints the manual command instead.
+ *
+ * @param {"codex"|"copilot"} host
+ * @param {string} label - host label for log lines
+ * @returns {{registered: boolean, alreadyPresent?: boolean, reason?: string}}
+ */
+export function registerMcpServer(host, label) {
+  const cli = resolveCli(host);
+  const manual = `${host} mcp add ${MCP_SERVER_NAME} -- npx -y ${MCP_SERVER_PACKAGE}`;
+
+  if (isDryRun()) {
+    console.log(`    [dry-run] would run: ${manual}`);
+    return { registered: false, reason: "dry-run" };
+  }
+
+  // Opt-out for hermetic installs. Registration shells out to the host CLI, so its
+  // result depends on whether that binary is present - which makes the install layout
+  // non-deterministic across machines and CI. The layout smoke sets this so its
+  // fingerprint stays stable.
+  if (process.env.MULTI_AGENT_SKIP_MCP_REGISTER === "1") {
+    console.log(`    -> ${label}: skipped MCP registration (MULTI_AGENT_SKIP_MCP_REGISTER=1)`);
+    return { registered: false, reason: "opted out" };
+  }
+
+  try {
+    // Bounded: an installer must never hang on a child process. This is a local config
+    // write and returns in milliseconds.
+    execFileSync(cli, ["mcp", "add", MCP_SERVER_NAME, "--", "npx", "-y", MCP_SERVER_PACKAGE], {
+      stdio: "pipe",
+      timeout: 20_000,
+    });
+    console.log(`    -> ${label}: registered the ${MCP_SERVER_NAME} MCP server`);
+    return { registered: true };
+  } catch (e) {
+    // The CLI writes its diagnosis to stderr, which execFileSync parks on the error
+    // rather than in `message`. Read both, or "already exists" is invisible.
+    const out = `${e?.stderr?.toString() ?? ""}\n${e?.stdout?.toString() ?? ""}\n${e?.message ?? ""}`;
+    if (/already exists/i.test(out)) {
+      console.log(`    -> ${label}: ${MCP_SERVER_NAME} MCP server already registered, left as-is`);
+      return { registered: true, alreadyPresent: true };
+    }
+    const why =
+      e?.code === "ENOENT"
+        ? `${host} not on PATH`
+        : (out.split("\n").find((l) => l.trim()) || "unknown error").trim();
+    console.log(`    -> ${label}: skipped MCP registration (${why})`);
+    console.log(`       run manually: ${manual}`);
+    return { registered: false, reason: why };
+  }
+}

package/install/codex.mjs

@@ -19,7 +19,6 @@
 
 import { existsSync, readFileSync, readdirSync, rmSync } from "fs";
 import { join } from "path";
-import { execFileSync } from "child_process";
 
 import {
   copyDir,
@@ -32,6 +31,7 @@ import {
   writeFile,
 } from "./_common.mjs";
 import { DEV_ONLY_SCRIPTS, countDevOnlyFiles } from "./_dev-only-files.mjs";
+import { registerMcpServer } from "./_mcp-register.mjs";
 import { installCodexAgents } from "./_codex-agents.mjs";
 import { existingSkillNames, installAuthoredPluginSkills } from "./_plugin-skills.mjs";
 import { generateCodexInstructions } from "./_codex-instructions.mjs";
@@ -43,9 +43,8 @@ export const AGENTS_MD_START_MARKER = "# Multi-Agent Development Pipeline";
 /** Explicit end marker written after the pipeline section. */
 export const AGENTS_MD_END_MARKER = "<!-- multi-agent-pipeline:codex-instructions:end -->";
 
-/** MCP server the pipeline's `/multi-agent:test` + design-check flows depend on. */
-export const MCP_SERVER_NAME = "dev-toolkit";
-const MCP_SERVER_PACKAGE = "@mmerterden/dev-toolkit-mcp";
+/** Re-exported for the uninstaller and the Codex install smoke. */
+export { MCP_SERVER_NAME } from "./_mcp-register.mjs";
 
 /**
  * `$HOME/.claude/...` path rewrites applied to every file installed into the
@@ -200,7 +199,7 @@ export function installCodex(ctx) {
   installTree("rules", pipelineSrc, CODEX_RULES, useSymlinks);
   writeAgentsMd(join(CODEX_DIR, "AGENTS.md"));
   ensureSharedPreferences(home, pipelineSrc);
-  registerMcpServer();
+  registerMcpServer("codex", "Codex CLI");
 
   console.log("");
 }
@@ -482,37 +481,4 @@ function ensureSharedPreferences(home, pipelineSrc) {
  * it. Hand-merging TOML here would be the riskiest write in this installer for
  * no benefit.
  */
-function registerMcpServer() {
-  if (isDryRun()) {
-    console.log(
-      `    [dry-run] would run: codex mcp add ${MCP_SERVER_NAME} -- npx -y ${MCP_SERVER_PACKAGE}`,
-    );
-    return;
-  }
-  // Opt-out for hermetic installs. Registration shells out to `codex`, so its
-  // result depends on whether the binary is present - which makes the install
-  // layout non-deterministic across machines and CI. The layout smoke sets this
-  // so its fingerprint stays stable.
-  if (process.env.MULTI_AGENT_SKIP_MCP_REGISTER === "1") {
-    console.log("    -> skipped MCP registration (MULTI_AGENT_SKIP_MCP_REGISTER=1)");
-    return;
-  }
-  try {
-    // Bounded: an installer must never hang on a child process. `codex mcp add`
-    // is a local config write and returns in milliseconds.
-    execFileSync("codex", ["mcp", "add", MCP_SERVER_NAME, "--", "npx", "-y", MCP_SERVER_PACKAGE], {
-      stdio: "pipe",
-      timeout: 20_000,
-    });
-    console.log(`    -> registered the ${MCP_SERVER_NAME} MCP server`);
-  } catch (e) {
-    const why =
-      e?.code === "ENOENT" ? "codex not on PATH" : (e?.message || "unknown error").split("\n")[0];
-    console.log(`    -> skipped MCP registration (${why})`);
-    console.log(
-      `       run manually: codex mcp add ${MCP_SERVER_NAME} -- npx -y ${MCP_SERVER_PACKAGE}`,
-    );
-  }
-}
-
 export { generateCodexInstructions };

package/install/copilot.mjs

@@ -26,6 +26,7 @@ import { DEV_ONLY_SCRIPTS, countDevOnlyFiles } from "./_dev-only-files.mjs";
 import { generateCopilotInstructions } from "./_copilot-instructions.mjs";
 import { legacyTrailingContent, mergeManagedBlock } from "./_managed-block.mjs";
 import { existingSkillNames, installAuthoredPluginSkills } from "./_plugin-skills.mjs";
+import { registerMcpServer } from "./_mcp-register.mjs";
 
 /**
  * @param {{
@@ -56,6 +57,13 @@ export function installCopilot(ctx) {
   installSchemas(pipelineSrc, COPILOT_SCHEMAS, useSymlinks);
   installLib(pipelineSrc, COPILOT_LIB, useSymlinks);
   installSkills({ home, pipelineSrc, dest: COPILOT_SKILLS, indexOnly, useSymlinks, platformFlag });
+
+  // Copilot never registered the companion MCP server, while Codex did from the day its
+  // installer was written. So Copilot carried every pipeline skill and could not call a
+  // single one of the tools those skills depend on: design-check, the ios_* / android_*
+  // simulator calls, the archive audits. Nothing failed at install time - the skills
+  // only fail once a run reaches for a tool that is not there.
+  registerMcpServer("copilot", "Copilot CLI");
 }
 
 /** Start of the pipeline-managed span in copilot-instructions.md. */

package/install/index.mjs

@@ -182,11 +182,16 @@ function printSummary(opts) {
     console.log("");
   }
 
-  console.log("  For UI testing, also install the mobile MCP server:");
+  console.log("  For UI testing, the mobile MCP server:");
   if (forCodex) {
-    console.log("    Codex: registered automatically (codex mcp add dev-toolkit)");
+    console.log("    Codex CLI:   registered automatically (codex mcp add dev-toolkit)");
+  }
+  if (forCopilot) {
+    console.log("    Copilot CLI: registered automatically (copilot mcp add dev-toolkit)");
+  }
+  if (forClaude) {
+    console.log("    Claude Code: add it yourself - claude mcp add dev-toolkit -- npx -y @mmerterden/dev-toolkit-mcp");
   }
-  console.log("    Otherwise add to your MCP config: npx @mmerterden/dev-toolkit-mcp");
   console.log("");
   console.log("  Uninstall everything: npx @mmerterden/multi-agent-pipeline uninstall");
   console.log("  (Personal access tokens in keychain are preserved.)");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "13.3.0",
+  "version": "13.5.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/commands/multi-agent/setup/SKILL.md

@@ -633,7 +633,8 @@ Entries are objects (not bare strings). The schema `recentProjects.items` is a `
 
 **7g. Skip / degrade rules**
 
-- Source failure (network, VPN, 401, rate-limit) skips that source silently; the others still run. Failure is recorded in `serviceStatus.{service} = { ok: false, checkedAt: <now>, reason: <short> }` so Phase 0 can also read that cache.
+- Source failure (network, VPN, 401, rate-limit) skips that source; the others still run. Failure is recorded in `serviceStatus.{service} = { ok: false, checkedAt: <now>, reason: <short> }` so Phase 0 can also read that cache.
+- **Report the skip, do not swallow it.** Setup is where the user is actively configuring things, so a source that could not be reached is exactly what they need to hear about, and the reason decides their next move: a 401 means refresh that token, no response at all on a corporate host means connect the VPN, and a missing `global.hosts.<service>` means the token has nowhere to point. Print one line per skipped source with its classification (see `refs/keychain.md` Rule 2) before moving on. A discovery pass that quietly returned three repos out of forty reads as "you only have three repos".
 - If all three sources yield zero hits, Step 5 is a no-op  -  the picker in Phase 0 falls back to manual path entry.
 - Discovery is **never destructive**: it never modifies git state, never writes outside `PREFS_FILE`.
 - Step 5 is idempotent. Re-running it refreshes `recentProjects` and `serviceStatus` but preserves user-curated entries unless explicitly deselected.

package/pipeline/lib/account-resolver.sh

@@ -69,10 +69,21 @@ except Exception:
 # A pre-set CRED_STORE (tests, custom installs) is honored as-is.
 if [ -z "${CRED_STORE:-}" ]; then
   # shellcheck disable=SC1090,SC1091
-  . "$(cd "$(dirname "$0")" && pwd)/credential-store-resolver.sh" 2>/dev/null \
-    || . "$HOME/.claude/lib/credential-store-resolver.sh" 2>/dev/null \
-    || . "$HOME/.copilot/lib/credential-store-resolver.sh" 2>/dev/null \
-    || true
+  # Existence check before sourcing: `. <missing>` aborts the shell under `set -e`,
+  # `||` included, so a `.`-chain reaches neither its later candidates nor its error
+  # branch. The loop also covers all three hosts - the chain it replaced knew only
+  # .claude and .copilot, so a Codex-only install could not resolve at all.
+  for _cred_resolver in \
+    "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/credential-store-resolver.sh" \
+    "$HOME/.claude/lib/credential-store-resolver.sh" \
+    "$HOME/.copilot/lib/credential-store-resolver.sh" \
+    "$HOME/.codex/lib/credential-store-resolver.sh"; do
+    [ -f "$_cred_resolver" ] || continue
+    # shellcheck source=/dev/null
+    . "$_cred_resolver" 2>/dev/null || true
+    if [ -n "${CRED_STORE:-}" ]; then break; fi
+  done
+  unset _cred_resolver
 fi
 services=""
 if [ -n "${CRED_STORE:-}" ]; then