@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.0

package/pipeline/lib/model-rung.sh

@@ -24,6 +24,11 @@
 set -uo pipefail
 
 PREFS="${MULTI_AGENT_PREFS:-$HOME/.claude/multi-agent-preferences.json}"
+
+_MA_MR_HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+if [ -f "$_MA_MR_HERE/user-facing.sh" ]; then . "$_MA_MR_HERE/user-facing.sh"; else . "$HOME/.claude/lib/user-facing.sh"; fi
+
 ACTION="${1:-report}"
 
 case "$ACTION" in
@@ -43,7 +48,7 @@ if ! command -v jq >/dev/null 2>&1; then
 fi
 
 if [ ! -f "$PREFS" ]; then
-  echo "model-rung: preferences not found at $PREFS  -  run /multi-agent:setup first" >&2
+  echo "model-rung: preferences not found at $PREFS  -  run $(ma_command setup) first" >&2
   exit 3
 fi
 

package/pipeline/lib/multi-repo-pipeline.sh

@@ -334,7 +334,7 @@ for r in (state.get("readonlySiblings") or []) + extras:
     })
 agent_state["siblings"] = siblings
 
-logs_dir = os.path.expanduser(os.path.join("~/.claude/logs/multi-agent", primary["name"], state["taskId"]))
+logs_dir = os.path.join(os.environ.get("LOGS_ROOT") or os.path.expanduser("~/.claude/logs/multi-agent"), primary["name"], state["taskId"])
 os.makedirs(logs_dir, exist_ok=True)
 out_path = os.path.join(logs_dir, "agent-state.json")
 tmp_path = out_path + ".tmp"

package/pipeline/lib/outbound-gate.mjs

@@ -9,24 +9,27 @@
  * error messages and file excerpts, any of which can contain a token that was
  * on the machine a second earlier.
  *
- * SCOPE, and the part the plan for this got wrong: corporate names are NOT
- * checked here. A Jira comment on a corporate ticket legitimately contains the
- * corporate project key, the repo name and the hostname - refusing those would
- * make the gate fire on every correct publish, and a gate that cries wolf is
- * turned off. Repo genericity and run-output hygiene are different jobs with
- * different lists, and only the second one ships.
+ * SCOPE: credentials and run-environment leaks, not corporate names. A Jira
+ * comment on a corporate ticket legitimately contains the project key, the
+ * repo name and the hostname; refusing those would make the gate fire on every
+ * correct publish. Repo genericity is smoke-personal-data.sh's job, with a
+ * different list.
  *
- * WIRED INTO, and the honest limit: the three SHELL publishers -
- * lib/jira-publish.sh (which is also how `channels` posts to Jira),
- * lib/post-pr-review.sh (per-finding comments and the request-changes body),
- * and scripts/update-issue-progress.sh. That is every publish this repo makes
- * from a script.
+ * SURFACES (exported below, each with the file that enforces it): the PR body
+ * an unattended run hands the runner (scripts/pr-request.mjs, which refuses to
+ * write pr-request.json and whose `validate` the runner re-runs), the PR text
+ * and the post-PR reports the autopilot runner publishes
+ * (scripts/autopilot-publish.mjs), Jira comments
+ * and descriptions (lib/jira-publish.sh, also the path `channels` posts
+ * through), Jira issue creation (lib/analysis-jira-write.sh), Confluence pages
+ * (lib/md2confluence-v3.py, the only create/update path), PR reviews
+ * (lib/post-pr-review.sh) and GitHub issue progress comments
+ * (scripts/update-issue-progress.sh).
  *
- * It is NOT every publish. `channels` also writes a Confluence page and a PR
- * description, and those are composed and posted by the agent following the
- * skill rather than by a script, so nothing in shell can intercept them. A
- * gate that claimed four paths while covering three would be worse than one
- * that covers three and says so.
+ * The limit: an attended run's agent can still compose text and post it with a
+ * raw `gh` or `curl` call that no script intercepts. An unattended run cannot:
+ * agent-guard blocks every such call under MULTI_AGENT_UNATTENDED=1, so there
+ * the runner, publishing from pr-request.json, is the only path out.
  *
  * WHAT IT NEVER DOES: print the thing it found. A gate that echoes the secret
  * into a terminal, a log and a CI transcript has moved it somewhere new.
@@ -117,6 +120,33 @@ export const RULES = [
   },
 ];
 
+/**
+ * Where published text is scanned. `enforcedBy` is the repo-relative file that
+ * calls the gate before anything is sent; `call` is what that file must contain.
+ * test/outbound-gate.test.mjs reads each file and holds it to this list.
+ */
+export const SURFACES = [
+  { id: "pr-request-body", enforcedBy: "pipeline/scripts/pr-request.mjs", call: /\bscan\(/ },
+  {
+    id: "runner-publish",
+    enforcedBy: "pipeline/scripts/autopilot-publish.mjs",
+    call: /\bscan\(/,
+  },
+  { id: "jira-comment", enforcedBy: "pipeline/lib/jira-publish.sh", call: /ma_outbound_gate "/ },
+  { id: "jira-issue", enforcedBy: "pipeline/lib/analysis-jira-write.sh", call: /outbound_gate/ },
+  {
+    id: "confluence-page",
+    enforcedBy: "pipeline/lib/md2confluence-v3.py",
+    call: /outbound_gate\(md_text\)/,
+  },
+  { id: "pr-review", enforcedBy: "pipeline/lib/post-pr-review.sh", call: /outbound_gate/ },
+  {
+    id: "issue-progress-comment",
+    enforcedBy: "pipeline/scripts/update-issue-progress.sh",
+    call: /outbound_gate/,
+  },
+];
+
 /**
  * @param {string} text
  * @returns {{rule: string, certain: boolean, line: number}[]}

package/pipeline/lib/parse-complaints.sh

@@ -34,7 +34,8 @@
 #   13-19 digit card-like runs         -> [REDACTED:card]
 #   11 digit national-id-like numbers  -> [REDACTED:national-id]
 #   9+ digit phone-like runs           -> [REDACTED:phone]
-#   6-char PNR-like tokens (A-Z0-9 mix)-> [REDACTED:pnr]
+#   6-char reservation/order reference codes (A-Z0-9 mix, or 6 letters
+#   right after a reference-code label) -> [REDACTED:reference]
 #
 # Output (stdout, single JSON object):
 #   {
@@ -147,18 +148,24 @@ def extract_ids(text):
 
 # Order matters: card (13-19 digits, separators allowed) before national-id
 # (exactly 11) before phone (9+); a 16-digit card must not survive as a
-# "phone". PNR-like runs last so redacted placeholders are not re-matched.
+# "phone". Reference codes last so redacted placeholders are not re-matched.
+REFERENCE_LABELS = (
+    r"reference (?:code|number|no)|ref (?:code|no)"
+    r"|(?:booking|reservation|order|confirmation) (?:code|number|no|ref|reference)"
+    r"|rezervasyon (?:kodu|no)|sipari[s\u015f] (?:kodu|no)|pnr"
+)
+
 REDACTIONS = [
     (re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}"), "[REDACTED:email]"),
     (re.compile(r"\b\d(?:[ -]?\d){12,18}\b"), "[REDACTED:card]"),
     (re.compile(r"\b\d{11}\b"), "[REDACTED:national-id]"),
     (re.compile(r"(?<![\w.-])\+?\d(?:[ ()-]?\d){8,14}\b"), "[REDACTED:phone]"),
-    (re.compile(r"\b(?=[A-Z0-9]{6}\b)(?=[A-Z0-9]*[A-Z])(?=[A-Z0-9]*\d)[A-Z0-9]{6}\b"), "[REDACTED:pnr]"),
-    # All-letter PNRs exist too, but a bare 6-letter uppercase word is far too
-    # common to redact blind - only take one that follows a PNR-ish keyword.
+    (re.compile(r"\b(?=[A-Z0-9]{6}\b)(?=[A-Z0-9]*[A-Z])(?=[A-Z0-9]*\d)[A-Z0-9]{6}\b"), "[REDACTED:reference]"),
+    # An all-letter code is only taken after a reference-code label: a bare
+    # 6-letter uppercase word is far too common to redact blind.
     (
-        re.compile(r"\b(?P<kw>pnr|rezervasyon kodu|booking (?:ref|reference|code))(?P<sep>[^A-Za-z0-9\n]{0,3})[A-Z]{6}\b", re.IGNORECASE),
-        lambda m: m.group("kw") + m.group("sep") + "[REDACTED:pnr]",
+        re.compile(r"\b(?P<kw>" + REFERENCE_LABELS + r")(?P<sep>[^A-Za-z0-9\n]{0,3})[A-Z]{6}\b", re.IGNORECASE),
+        lambda m: m.group("kw") + m.group("sep") + "[REDACTED:reference]",
     ),
 ]
 

package/pipeline/lib/plan-todos.sh

@@ -6,8 +6,8 @@
 # step-by-step as Phase 3 works through it.
 #
 # State lives in `agent-state.json` under `.plan.todos[]` per
-# pipeline/schemas/plan-todos.schema.json. Phase 2 (Planning) emits the
-# initial plan; Phase 3 (Dev) iterates step-by-step; Phase 4 (Review)
+# pipeline/schemas/plan-todos.schema.json. Phase 1 (Plan) emits the
+# initial plan; Phase 2 (Dev) iterates step-by-step; Phase 3 (Review)
 # inspects completion; Phase 5 (Report) renders the rollup.
 #
 # Subcommands:
@@ -52,7 +52,7 @@ ma_require_jq "read or write the plan" || exit 3
 # (nested <root>/<project>/<id>/ and flat <root>/<id>/) and every id spelling.
 _MA_RP_HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
-. "$_MA_RP_HERE/run-paths.sh" 2>/dev/null || . "$HOME/.claude/lib/run-paths.sh"
+if [ -f "$_MA_RP_HERE/run-paths.sh" ]; then . "$_MA_RP_HERE/run-paths.sh"; else . "$HOME/.claude/lib/run-paths.sh"; fi
 
 
 CMD="${1:-}"

package/pipeline/lib/post-pr-review.sh

@@ -90,7 +90,9 @@ ma_outbound_gate_text() {
 # (nested <root>/<project>/<id>/ and flat <root>/<id>/) and every id spelling.
 _MA_RP_HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
-. "$_MA_RP_HERE/run-paths.sh" 2>/dev/null || . "$HOME/.claude/lib/run-paths.sh"
+if [ -f "$_MA_RP_HERE/run-paths.sh" ]; then . "$_MA_RP_HERE/run-paths.sh"; else . "$HOME/.claude/lib/run-paths.sh"; fi
+# shellcheck source=/dev/null
+if [ -f "$_MA_RP_HERE/user-facing.sh" ]; then . "$_MA_RP_HERE/user-facing.sh"; else . "$HOME/.claude/lib/user-facing.sh"; fi
 
 
 # Basic-auth via a curl config fed through process substitution so the
@@ -119,12 +121,11 @@ if [ -z "$AGENT_STATE" ]; then
 fi
 
 if ! jq -e '.review' "$AGENT_STATE" >/dev/null; then
-  echo "post-pr-review: agent-state has no .review field  -  run /multi-agent:review first" >&2
+  echo "post-pr-review: agent-state has no .review field  -  run $(ma_command review) first" >&2
   exit 2
 fi
 
-OUT_LANG=$(jq -r '.global.outputLanguage // "en"' "$HOME/.claude/multi-agent-preferences.json" 2>/dev/null || echo "en")
-case "$OUT_LANG" in tr|en) ;; *) OUT_LANG=en ;; esac
+OUT_LANG=$(ma_output_lang)
 
 PROVIDER=$(jq -r '.review.input.provider // empty' "$AGENT_STATE")
 PR_NUM=$(jq -r '.review.input.prNumber // empty' "$AGENT_STATE")
@@ -162,9 +163,9 @@ echo "post-pr-review: decision=$DECISION (blocking=$ACCEPTED_BLOCKING, important
 # when the suggested fix wording changes slightly between iterations.
 finding_fingerprint() {
   local path="$1" line="$2" issue="$3"
-  # sha256sum (coreutils) or shasum (perl), whichever this platform has. A bare
-  # `shasum` produced an empty fingerprint on slim Linux images, which made every
-  # finding look new and re-posted the whole review on each iteration.
+  # sha256sum (coreutils) or shasum (perl), whichever this machine has. An empty
+  # fingerprint would make every finding look new and re-post the whole review on
+  # each iteration.
   if command -v sha256sum >/dev/null 2>&1; then
     printf '%s|%s|%s' "$path" "$line" "$issue" | sha256sum | cut -c1-16
   else
@@ -379,8 +380,7 @@ post_bitbucket_server() {
     return 4
   fi
 
-  # Resolve via the cross-platform credential helper (macOS Keychain / Windows
-  # Credential Manager / Linux libsecret)  -  sourced lazily so this script keeps
+  # Resolve via the credential helper (macOS Keychain)  -  sourced lazily so this script keeps
   # working when run from either ~/.claude/lib or ~/.copilot/lib.
   # shellcheck disable=SC1090
   # Existence check before sourcing: `. <missing>` aborts the shell under `set -e`,

package/pipeline/lib/pr-request-location.mjs

@@ -0,0 +1,85 @@
+/**
+ * pr-request-location.mjs  -  where an unattended run leaves its PR request,
+ * and where the runner records what it decided about it.
+ *
+ * Under MULTI_AGENT_UNATTENDED=1 a run does not push and does not open a PR.
+ * Phase 4 writes one file instead, through scripts/pr-request.mjs, and the
+ * autopilot runner is the only process that pushes the branch and creates the
+ * PR, after it has verified that file. Both sides import this module so they
+ * cannot disagree on the path.
+ *
+ *   <run root>/pr-requests/<session id>.json                 the run writes it
+ *   <autopilot root>/pr-requests/<session id>.verdict.json   the runner writes it
+ *
+ * The run root is MA_UNATTENDED_RUN_ROOT, else ~/.multi-agent-unattended: the
+ * one directory outside the worktree the unattended profile's OS sandbox lets
+ * a run write, since Claude Code keeps every command out of ~/.claude. The
+ * autopilot root is MA_AUTOPILOT_ROOT, else ~/.claude/autopilot, the same root
+ * the runner and launch-request.mjs use, and a run cannot write there. The
+ * session id is the one the runner generated and passed as
+ * MULTI_AGENT_SESSION_ID.
+ *
+ * Everything under the autopilot root, and every other session's request, is
+ * a protected path for an unattended run (scripts/unattended_policy.py). The
+ * Python twin of these paths lives there, and test/pr-request.test.mjs holds
+ * the two to the same answer.
+ *
+ * @module pipeline/lib/pr-request-location
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const PR_REQUESTS_SUBDIR = "pr-requests";
+export const UNATTENDED_RUN_DIR = ".multi-agent-unattended";
+export const PR_REQUEST_FILE_SUFFIX = ".json";
+export const PR_VERDICT_FILE_SUFFIX = ".verdict.json";
+export const SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/** @param {Record<string,string|undefined>} [env] */
+export function autopilotRoot(env = process.env) {
+  return env.MA_AUTOPILOT_ROOT || join(env.HOME || homedir(), ".claude", "autopilot");
+}
+
+/**
+ * Where an unattended run writes what the runner reads back: its logs and its
+ * PR request.
+ *
+ * @param {Record<string,string|undefined>} [env]
+ */
+export function unattendedRunRoot(env = process.env) {
+  return env.MA_UNATTENDED_RUN_ROOT || join(env.HOME || homedir(), UNATTENDED_RUN_DIR);
+}
+
+/** @param {Record<string,string|undefined>} [env] */
+export function runRequestsDir(env = process.env) {
+  return join(unattendedRunRoot(env), PR_REQUESTS_SUBDIR);
+}
+
+/** The log root an unattended run writes its state under. */
+export function unattendedLogsRoot(env = process.env) {
+  return join(unattendedRunRoot(env), "logs");
+}
+
+/** @param {Record<string,string|undefined>} [env] */
+export function prRequestsDir(env = process.env) {
+  return join(autopilotRoot(env), PR_REQUESTS_SUBDIR);
+}
+
+/**
+ * @param {string} sessionId
+ * @param {Record<string,string|undefined>} [env]
+ */
+export function prRequestPath(sessionId, env = process.env) {
+  if (!SESSION_ID_RE.test(String(sessionId || ""))) throw new Error("session id is not a UUID");
+  return join(runRequestsDir(env), `${sessionId}${PR_REQUEST_FILE_SUFFIX}`);
+}
+
+/**
+ * @param {string} sessionId
+ * @param {Record<string,string|undefined>} [env]
+ */
+export function prVerdictPath(sessionId, env = process.env) {
+  if (!SESSION_ID_RE.test(String(sessionId || ""))) throw new Error("session id is not a UUID");
+  return join(prRequestsDir(env), `${sessionId}${PR_VERDICT_FILE_SUFFIX}`);
+}

package/pipeline/lib/regular-file.mjs

@@ -0,0 +1,153 @@
+/**
+ * regular-file.mjs  -  read a file an agent could have written, without letting
+ * it choose what the read does.
+ *
+ * A synchronous read of a path an unattended run controls is a lever on the
+ * process doing the reading. A FIFO under that name blocks the read forever, a
+ * character device never ends, a symlink points anywhere, and a large file is
+ * read into memory whole. The autopilot runner and its publish step read such
+ * paths on the one thread that supervises every run, so a single planted FIFO
+ * would stop the queue.
+ *
+ * readRegularFile opens the resolved path non-blocking and without following a
+ * final symlink, checks the open descriptor (not the name) is a regular file
+ * no larger than the cap, and reads at most the cap. `within` restricts the
+ * resolved path to one of the given directories.
+ *
+ * O_NOFOLLOW covers only the last path component, so a directory swapped for a
+ * symlink between resolving and opening would still be followed. After the
+ * open, the descriptor's device and inode are compared with a fresh lstat of
+ * the resolved path; a mismatch means the name no longer points at what was
+ * opened, and the read is refused. A swap that is made and undone entirely
+ * between the open and that lstat is not seen; Node exposes no portable way to
+ * ask the kernel for a descriptor's path.
+ *
+ * @module pipeline/lib/regular-file
+ */
+
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readSync,
+  realpathSync,
+} from "node:fs";
+import { sep } from "node:path";
+
+export const DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
+
+export class RegularFileError extends Error {
+  /**
+   * @param {"missing"|"not-regular"|"outside"|"too-large"|"unreadable"} code
+   * @param {string} message
+   */
+  constructor(code, message) {
+    super(message);
+    this.name = "RegularFileError";
+    this.code = code;
+  }
+}
+
+function realOr(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+function inside(path, dir) {
+  const d = dir.endsWith(sep) ? dir : dir + sep;
+  return path === dir || path.startsWith(d);
+}
+
+/**
+ * Throws unless `fd` is the same file the path names right now, reached
+ * without a symlink at its last component.
+ *
+ * @param {number} fd
+ * @param {string} path
+ */
+export function assertOpenedIsPath(fd, path) {
+  let now;
+  try {
+    now = lstatSync(path);
+  } catch (err) {
+    throw new RegularFileError("unreadable", `${path}: ${err.code || err.message}`);
+  }
+  const opened = fstatSync(fd);
+  if (now.isSymbolicLink() || now.dev !== opened.dev || now.ino !== opened.ino) {
+    throw new RegularFileError("unreadable", `${path} changed while it was being opened`);
+  }
+}
+
+/**
+ * The file's text, or a RegularFileError naming why it was refused.
+ *
+ * @param {string} path
+ * @param {{maxBytes?: number, within?: string[]|null}} [opts]
+ * @returns {string}
+ */
+export function readRegularFile(path, { maxBytes = DEFAULT_MAX_BYTES, within = null } = {}) {
+  let real;
+  try {
+    real = realpathSync(path);
+  } catch (err) {
+    throw new RegularFileError(
+      err.code === "ENOENT" ? "missing" : "unreadable",
+      `${path}: ${err.code || err.message}`,
+    );
+  }
+  if (Array.isArray(within) && !within.filter(Boolean).some((d) => inside(real, realOr(d)))) {
+    throw new RegularFileError("outside", `${path} resolves outside the directories it may be in`);
+  }
+  let fd;
+  try {
+    fd = openSync(
+      real,
+      constants.O_RDONLY | (constants.O_NONBLOCK ?? 0) | (constants.O_NOFOLLOW ?? 0),
+    );
+  } catch (err) {
+    throw new RegularFileError("unreadable", `${path}: ${err.code || err.message}`);
+  }
+  try {
+    assertOpenedIsPath(fd, real);
+    const st = fstatSync(fd);
+    if (!st.isFile()) throw new RegularFileError("not-regular", `${path} is not a regular file`);
+    if (st.size > maxBytes) {
+      throw new RegularFileError("too-large", `${path} is larger than ${maxBytes} bytes`);
+    }
+    const buf = Buffer.alloc(Math.min(st.size, maxBytes) + 1);
+    let n = 0;
+    for (;;) {
+      const got = readSync(fd, buf, n, buf.length - n, null);
+      if (got === 0) break;
+      n += got;
+      if (n > maxBytes) {
+        throw new RegularFileError("too-large", `${path} is larger than ${maxBytes} bytes`);
+      }
+      if (n === buf.length) break;
+    }
+    return buf.subarray(0, n).toString("utf8");
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Parsed JSON from a regular file, or `fallback` for anything that is not one,
+ * is too large, or does not parse.
+ *
+ * @param {string} path
+ * @param {*} [fallback]
+ * @param {{maxBytes?: number, within?: string[]|null}} [opts]
+ */
+export function readRegularJson(path, fallback = null, opts = {}) {
+  try {
+    return JSON.parse(readRegularFile(path, opts));
+  } catch {
+    return fallback;
+  }
+}

package/pipeline/lib/repo-hygiene.sh

@@ -22,6 +22,10 @@
 #   ma_hygiene_prune_empty <repo-root>         rmdir the artefact parents when
 #                                              their last child is gone.
 #
+# Run as a command, the same four take the repo root as an argument:
+#   bash repo-hygiene.sh ensure|release|gitignore|prune <repo-root>
+# so a phase doc calls one simple command instead of sourcing the library.
+#
 # Every function is best-effort: a read-only or non-git directory is not an
 # error, because refusing to run a pipeline over a repo we cannot tidy is worse
 # than leaving it untidy. Callers do not check the return value.
@@ -167,3 +171,16 @@ ma_hygiene_prune_empty() {
   fi
   return 0
 }
+
+if [ "${BASH_SOURCE[0]:-$0}" = "$0" ]; then
+  case "${1:-}" in
+    ensure) ma_hygiene_ensure_exclusions "${2:-}" ;;
+    release) ma_hygiene_release_exclusions "${2:-}" ;;
+    gitignore) ma_hygiene_local_gitignore "${2:-}" ;;
+    prune) ma_hygiene_prune_empty "${2:-}" ;;
+    *)
+      echo "usage: repo-hygiene.sh ensure|release|gitignore|prune <repo-root>" >&2
+      exit 2
+      ;;
+  esac
+fi

package/pipeline/lib/route-state.sh

@@ -24,6 +24,10 @@ set -uo pipefail
 
 PREFS="${MULTI_AGENT_PREFS:-$HOME/.claude/multi-agent-preferences.json}"
 
+_MA_RS_HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+if [ -f "$_MA_RS_HERE/user-facing.sh" ]; then . "$_MA_RS_HERE/user-facing.sh"; else . "$HOME/.claude/lib/user-facing.sh"; fi
+
 # The scope values this accepts, spelled once. `host-session` is NOT here and
 # must never be added: it would mean rewriting the host's base URL, which routes
 # the user's whole session - work that has nothing to do with this pipeline
@@ -38,7 +42,7 @@ die() { echo "route-state: $1" >&2; exit "${2:-3}"; }
 # come back empty, `route-status` would report disabled, and a user with rules
 # armed would be told there are none.
 command -v jq >/dev/null 2>&1 || die "jq not found  -  cannot read or write preferences (install: brew install jq)"
-[ -f "$PREFS" ] || die "preferences not found at $PREFS  -  run /multi-agent:setup first"
+[ -f "$PREFS" ] || die "preferences not found at $PREFS  -  run $(ma_command setup) first"
 jq -e . "$PREFS" >/dev/null 2>&1 || die "$PREFS is not valid JSON  -  refusing to write over it"
 
 ACTION="${1:-status}"; shift 2>/dev/null || true

package/pipeline/lib/run-paths.sh

@@ -58,14 +58,15 @@ ma_is_run_dir() {
 
 ma_is_reserved() {
   case "$1" in
-    review-watch | jira-backups | shadow-git | _analysis-jira | prompts) return 0 ;;
+    review-watch | jira-backups | shadow-git | _analysis-jira | prompts | contract-server) return 0 ;;
   esac
   return 1
 }
 
 # Newest mtime across a run directory's markers, as epoch seconds. GNU-first
 # `stat -c` ordering is required: `stat -f` is a valid GNU flag
-# (--file-system) that SUCCEEDS, so BSD-first would silently win on Linux.
+# (--file-system) that SUCCEEDS, so BSD-first would silently win whenever GNU
+# coreutils is first on PATH (Homebrew gnubin).
 ma_run_mtime() {
   local d="$1" m t newest=0 b
   for b in "$d" "$d/$MA_ARTIFACTS_SUBDIR"; do

package/pipeline/lib/stack-detect.sh

@@ -181,6 +181,24 @@ EOF
   return 0
 }
 
+# JSON string escaping without jq, which this file does not otherwise need.
+# "why" can quote a caller-supplied path, so every character JSON reserves is
+# escaped: backslash and quote, then any control character as \uXXXX.
+_ma_json_str() {
+  local s="$1" out="" c i
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  if [[ "$s" == *[[:cntrl:]]* ]]; then
+    for ((i = 0; i < ${#s}; i++)); do
+      c="${s:i:1}"
+      [[ "$c" == [[:cntrl:]] ]] && printf -v c '\\u%04x' "'$c"
+      out+="$c"
+    done
+    s="$out"
+  fi
+  printf '"%s"' "$s"
+}
+
 if [ "${BASH_SOURCE[0]:-$0}" = "$0" ]; then
   _json=0
   case "${1:-}" in --json)
@@ -192,7 +210,7 @@ if [ "${BASH_SOURCE[0]:-$0}" = "$0" ]; then
   if [ "$_json" -eq 1 ]; then
     _arr=""
     for _s in $MA_STACKS; do _arr="${_arr:+$_arr,}\"$_s\""; done
-    printf '{"stacks":[%s],"why":"%s"}\n' "$_arr" "$MA_STACK_WHY"
+    printf '{"stacks":[%s],"why":%s}\n' "$_arr" "$(_ma_json_str "$MA_STACK_WHY")"
   else
     printf 'MA_STACKS=%s\n' "$(printf '%q' "$MA_STACKS")"
     printf 'MA_STACK_WHY=%s\n' "$(printf '%q' "$MA_STACK_WHY")"