@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.1

package/pipeline/scripts/localize-commands.mjs

@@ -112,10 +112,9 @@ export function localizeCommands(dir, mode) {
   return changed;
 }
 
-// Windows-safe entry-point check: compare file URLs. The old
-// `.split("/").pop()` never split a backslash path, so on Windows this was
-// always false - `restore` exited 0 doing nothing and /multi-agent:sync then
-// mirrored localized descriptions into the repo, the one thing it must prevent.
+// Entry-point check: compare file URLs, never string-split a path. A false
+// negative here makes `restore` exit 0 doing nothing, and /multi-agent:sync then
+// mirrors localized descriptions into the repo, the one thing it must prevent.
 const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (invokedDirectly) {
   const args = process.argv.slice(2);
@@ -124,12 +123,7 @@ if (invokedDirectly) {
     console.error("usage: localize-commands.mjs <apply|restore> [--dir <commandsDir>]");
     process.exit(2);
   }
-  let dir = join(
-    process.env.HOME || process.env.USERPROFILE || "",
-    ".claude",
-    "commands",
-    "multi-agent",
-  );
+  let dir = join(process.env.HOME || "", ".claude", "commands", "multi-agent");
   const dirFlag = args.indexOf("--dir");
   if (dirFlag >= 0) {
     if (!args[dirFlag + 1]) {

package/pipeline/scripts/log-metric.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # log-metric.sh  -  append a single event to the pipeline metrics log.
 #
-# Append-only JSONL at $METRICS_FILE (default $HOME/.claude/logs/multi-agent/metrics.jsonl).
+# Append-only JSONL at $METRICS_FILE (default $LOGS_ROOT/metrics.jsonl, LOGS_ROOT defaulting to $HOME/.claude/logs/multi-agent).
 # One event per line. Schema:
 #   {
 #     "ts":      "<ISO 8601 timestamp>",
@@ -28,9 +28,10 @@
 #   log-metric.sh PROJ-1234 3 rework.started iteration=2 accepted_blocking=2
 #   log-metric.sh #316 5 task.completed phases=6 review_cycles=2 lang=tr
 #
-# Atomic append: each call uses `>> "$file"` which the kernel guarantees
-# atomic for writes ≤ PIPE_BUF (4 KB on macOS/Linux). One JSONL line is well
-# under that limit, so concurrent pipeline runs don't interleave.
+# Atomic append: each call uses `>> "$file"`, which opens with O_APPEND, and
+# writes the whole line in one `echo`. On a local filesystem an O_APPEND write
+# lands at the end of the file in one piece, so concurrent pipeline runs do not
+# interleave.
 #
 # Failure mode: if the metrics directory is unwritable, we WARN to stderr but
 # do NOT fail the pipeline. Telemetry is best-effort, never load-bearing.
@@ -46,7 +47,7 @@ TASK_ID="$1"; shift
 PHASE="$1"; shift
 EVENT="$1"; shift
 
-METRICS_FILE="${METRICS_FILE:-$HOME/.claude/logs/multi-agent/metrics.jsonl}"
+METRICS_FILE="${METRICS_FILE:-${LOGS_ROOT:-$HOME/.claude/logs/multi-agent}/metrics.jsonl}"
 METRICS_DIR="$(dirname "$METRICS_FILE")"
 
 mkdir -p "$METRICS_DIR" 2>/dev/null || {

package/pipeline/scripts/maturity-followup.mjs

@@ -10,8 +10,9 @@
  * reason.
  *
  * This module decides the follow-up. It is PURE - no network, no git, no issue
- * API, no clock unless one is handed to it - because the decision is the part
- * worth testing and the I/O around it is the part that differs per host.
+ * API, no clock and no language unless one is handed to it - because the
+ * decision is the part worth testing and the I/O around it is the part that
+ * differs per host.
  *
  * THE RULE THAT SHAPES EVERYTHING: an edit is a reason to look again, never
  * proof that the gap closed. A reply reading "will do later" moves the
@@ -27,6 +28,8 @@
  * @module pipeline/scripts/maturity-followup
  */
 
+import { outputLanguage } from "../lib/user-facing.mjs";
+
 /**
  * The first line of any comment this pipeline writes about maturity.
  *
@@ -38,6 +41,10 @@
  * BOTH a human skimming the thread and the next scan looking for its own prior
  * comment, because posting the same question twice is how an unattended queue
  * turns an issue into a wall of identical bot comments.
+ *
+ * It carries both languages and does not follow `outputLanguage`: it is matched,
+ * not read, and the scan that finds it may run under a different preference from
+ * the one that wrote it.
  */
 export const MARKER = "multi-agent: Bu madde geliştirmeye hazır değil / not ready to develop yet";
 
@@ -232,10 +239,12 @@ export function decide({ maturity, mode, prior = null, artifact = {}, prefs = {}
  * @param {string} [input.taskRef] what to point back at, e.g. `PROJ-1234`
  * @param {string[]} [input.gaps]  the codes, recorded on the item so the NEXT run
  *                                 can tell what was already asked without our state file
- * @param {"tr"|"en"} [input.lang]
+ * @param {"tr"|"en"} [input.lang] - defaults to `prefs.global.outputLanguage`,
+ *                                   which is the only value this module reads
+ *                                   from outside its arguments.
  * @returns {string}
  */
-export function commentBody({ summary, taskRef = "", lang = "tr", gaps = [] } = {}) {
+export function commentBody({ summary, taskRef = "", lang = outputLanguage(), gaps = [] } = {}) {
   const body = String(summary || "").trim();
   const codes = [...new Set((gaps || []).filter(isCode))].sort();
   const tr = [

package/pipeline/scripts/memory-save.sh

@@ -7,18 +7,43 @@
 #
 # Usage:
 #   memory-save.sh <project-root> <type> <slug> <body-file>
+#   memory-save.sh <project-root> --from-json <synthesis.json>
 #
 #   type     = user | feedback | project | reference
 #   slug     = kebab-case filename fragment (e.g. "audit-exhaustiveness")
 #   body-file= path to a file containing the frontmatter-wrapped memory body
 #              (or "-" to read body from stdin)
 #
+# --from-json saves every {type, slug, body} entry of a JSON array, in order,
+# exactly as one call per entry would. Phase 5's synthesis step uses it so the
+# save is one command rather than a shell loop over the array.
+#
 # Writes to $PROJECT_ROOT/.multi-agent/memory/<type>_<slug>.md and prepends
 # a bullet to MEMORY.md. Idempotent  -  overwriting an existing slug replaces
 # the file but leaves the index entry position unchanged.
 
 set -euo pipefail
 
+if [ "${2:-}" = "--from-json" ]; then
+  root="${1:?usage: memory-save.sh <project-root> --from-json <synthesis.json>}"
+  syn="${3:?usage: memory-save.sh <project-root> --from-json <synthesis.json>}"
+  command -v jq >/dev/null 2>&1 || { echo "memory-save: jq is required for --from-json" >&2; exit 1; }
+  n=$(jq 'if type == "array" then length else error("not an array") end' "$syn") || {
+    echo "memory-save: $syn is not a JSON array" >&2
+    exit 1
+  }
+  rc=0
+  i=0
+  while [ "$i" -lt "$n" ]; do
+    body=$(jq -r ".[$i].body" "$syn")
+    type=$(jq -r ".[$i].type" "$syn")
+    slug=$(jq -r ".[$i].slug" "$syn")
+    printf '%s\n' "$body" | bash "${BASH_SOURCE[0]}" "$root" "$type" "$slug" - || rc=1
+    i=$((i + 1))
+  done
+  exit "$rc"
+fi
+
 PROJECT_ROOT="${1:?usage: memory-save.sh <project-root> <type> <slug> <body-file|->}"
 TYPE="${2:?missing type}"
 SLUG="${3:?missing slug}"

package/pipeline/scripts/migrate-prefs.mjs

@@ -15,6 +15,7 @@ import path from "node:path";
 import os from "node:os";
 import { fileURLToPath } from "node:url";
 import { runMain } from "../lib/fatal.mjs";
+import { lockTimeoutFrom, withFileLockSync, writeJsonAtomicSync } from "../lib/json-file-lock.mjs";
 
 const DEFAULT_FILE = path.join(os.homedir(), ".claude", "multi-agent-preferences.json");
 
@@ -522,9 +523,9 @@ function migrateReportChannels(out, changes) {
 }
 
 function atomicWrite(filePath, data) {
-  const tmp = filePath + ".tmp." + process.pid;
-  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
-  fs.renameSync(tmp, filePath);
+  withFileLockSync(filePath, () => writeJsonAtomicSync(filePath, data, { mode: 0o600 }), {
+    timeoutMs: lockTimeoutFrom(process.env),
+  });
 }
 
 function main() {

package/pipeline/scripts/open-questions-gate.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+/**
+ * open-questions-gate.mjs  -  an unattended run does not build on a question
+ * nobody answered.
+ *
+ * Phase 1 Step 5 asks each open Section 20 row; autopilot cannot ask, so it
+ * defers every row into `state.analysis.openQuestions[]`. An attended run then
+ * flags those rows at review. An unattended run has no reviewer who can answer
+ * them either, and development built on a guessed answer is the work most
+ * likely to be thrown away. So at the Phase 1 -> Phase 2 transition, a
+ * non-empty list parks the run instead: `waitingFor: "question"`,
+ * `status: "awaiting_input"` and a `pendingQuestion` (stepId
+ * phase-1/open-questions) that `resume <id> --answer <optionId>` or a client
+ * answers through answer-question.mjs. The runner reports it as
+ * awaiting-answer and never re-runs it on its own.
+ *
+ * Re-entry. Once the question is answered (`state.lastAnswer`, stepId
+ * phase-1/open-questions, recorded after the gate's latest `fail` entry), the
+ * re-entered step runs this gate again and the gate applies the answer, so the
+ * ledger's latest entry reflects it:
+ *
+ *   assume   every row moves to `state.analysis.assumptions[]`, the list is
+ *            emptied, the run is no longer awaiting input: `pass`.
+ *   ask-now  with MULTI_AGENT_UNATTENDED=1 nobody is in the session to ask, so
+ *            the run parks again on the same question: `fail`. Without it the
+ *            step asks each row first and empties the list, and the gate then
+ *            evaluates the list as usual.
+ *   abort    the run stops as verification-failed at open-questions: `fail`.
+ *
+ * Runs only while the quality gates are active (lib/unattended.mjs,
+ * gatesActive): MULTI_AGENT_UNATTENDED=1, or a run in autopilot mode, which
+ * cannot ask either. Otherwise it prints a not-applicable verdict, exits 0 and
+ * touches nothing.
+ *
+ * Usage:
+ *   node open-questions-gate.mjs [--state <agent-state.json>] [--repo <dir>] [--json]
+ *
+ * Exit: 0 no open question (or not-applicable) · 1 parked, or stopped by `abort` · 2 usage ·
+ * 3 no state
+ *
+ * @module pipeline/scripts/open-questions-gate
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { attendedVerdict, isUnattended } from "../lib/unattended.mjs";
+import { gateContext, park, recordQuietly, updateState } from "./gate-ledger.mjs";
+
+const GATE = "open-questions";
+export const STEP_ID = "phase-1/open-questions";
+export const OPTIONS = Object.freeze([
+  { id: "ask-now", label: "Ask each question in this session, then continue" },
+  { id: "assume", label: "Continue, recording each question as a stated assumption" },
+  { id: "abort", label: "Stop this run" },
+]);
+const TEXT_MAX = 2000;
+
+/**
+ * The question the run parks on, in the shape answer-question.mjs answers.
+ *
+ * @param {string[]} questions
+ */
+export function pendingQuestionFor(questions) {
+  const head = `${questions.length} analysis question(s) are open; development has not started.`;
+  let text = head;
+  for (const q of questions) {
+    const line = `\n- ${q}`;
+    if (text.length + line.length > TEXT_MAX) break;
+    text += line;
+  }
+  return {
+    id: "open-questions",
+    stepId: STEP_ID,
+    text,
+    kind: "single-select",
+    options: OPTIONS.map((o) => ({ ...o })),
+  };
+}
+
+/**
+ * @param {object|null} state
+ * @returns {{gate: string, verdict: string, open: number, questions: string[], reason?: string}}
+ */
+export function evaluateOpenQuestions(state) {
+  const list = state?.analysis?.openQuestions;
+  if (!Array.isArray(list)) {
+    return {
+      gate: GATE,
+      verdict: "not-applicable",
+      open: 0,
+      questions: [],
+      reason: "no state.analysis.openQuestions[] recorded (no Phase 1 analysis in this mode)",
+    };
+  }
+  const questions = list.map((q) =>
+    typeof q === "string" ? q : q?.question || q?.title || q?.id || JSON.stringify(q),
+  );
+  return { gate: GATE, verdict: list.length ? "fail" : "pass", open: list.length, questions };
+}
+
+/**
+ * The option answered for this gate's latest park, or null. An answer older
+ * than the latest `fail` entry, or one for another step, is not this park's.
+ *
+ * @param {object|null} state
+ * @returns {string|null}
+ */
+export function pendingAnswer(state) {
+  const a = state?.lastAnswer;
+  if (!a || a.stepId !== STEP_ID || !Array.isArray(a.optionIds)) return null;
+  const mine = (Array.isArray(state.gates) ? state.gates : []).filter((g) => g?.gate === GATE);
+  const last = mine.at(-1);
+  if (!last || last.verdict !== "fail") return null;
+  if (!(Date.parse(a.answeredAt) >= Date.parse(last.at))) return null;
+  const id = a.optionIds[0];
+  return OPTIONS.some((o) => o.id === id) ? id : null;
+}
+
+/**
+ * The verdict once an answer is applied. Pure.
+ *
+ * @param {object} state
+ * @param {string} answer  one of OPTIONS[].id
+ * @param {{unattended: boolean, now?: Date}} opts
+ * @returns {{result: object, next: object|null, stop: boolean}}
+ */
+export function applyOpenAnswer(state, answer, { unattended, now = new Date() }) {
+  const base = evaluateOpenQuestions(state);
+  if (answer === "abort") {
+    return {
+      result: {
+        ...base,
+        verdict: "fail",
+        answer,
+        reason: "stopped by the answer abort; nothing developed",
+      },
+      next: null,
+      stop: true,
+    };
+  }
+  if (answer === "assume" && base.open > 0) {
+    const at = now.toISOString();
+    const prior = Array.isArray(state.analysis?.assumptions) ? state.analysis.assumptions : [];
+    const next = {
+      ...state,
+      status: state.status === "awaiting_input" ? "in_progress" : state.status,
+      analysis: {
+        ...state.analysis,
+        openQuestions: [],
+        assumptions: [
+          ...prior,
+          ...base.questions.map((question) => ({ question, source: STEP_ID, assumedAt: at })),
+        ],
+      },
+    };
+    delete next.haltReason;
+    return {
+      result: { gate: GATE, verdict: "pass", open: 0, questions: [], answer, assumed: base.open },
+      next,
+      stop: false,
+    };
+  }
+  if (answer === "ask-now" && unattended && base.open > 0) {
+    return {
+      result: {
+        ...base,
+        answer,
+        reason: "ask-now needs a person in the session, and MULTI_AGENT_UNATTENDED=1 has none",
+      },
+      next: null,
+      stop: false,
+    };
+  }
+  return { result: { ...base, answer }, next: null, stop: false };
+}
+
+function out(json, result) {
+  if (json) writeFileSync(1, `${JSON.stringify(result, null, 2)}\n`);
+  else if (result.verdict === "fail" && result.answer) {
+    writeFileSync(1, `open-questions: fail (${result.reason || `answer ${result.answer}`})\n`);
+  } else if (result.verdict === "fail") {
+    writeFileSync(
+      1,
+      `open-questions: ${result.open} open question(s); development does not start, the run parks awaiting an answer:\n${result.questions.map((q) => `  - ${q}`).join("\n")}\n`,
+    );
+  } else
+    writeFileSync(
+      1,
+      `open-questions: ${result.verdict}${result.reason ? ` (${result.reason})` : ""}\n`,
+    );
+}
+
+async function main(argv) {
+  const opts = { json: argv.includes("--json") };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--json") continue;
+    if (argv[i] === "--state" || argv[i] === "--repo") {
+      if (argv[i + 1] === undefined) {
+        process.stderr.write(`open-questions-gate: ${argv[i]} needs a value\n`);
+        return 2;
+      }
+      opts[argv[i].slice(2)] = argv[++i];
+    } else {
+      process.stderr.write(`open-questions-gate: unexpected argument ${argv[i]}\n`);
+      return 2;
+    }
+  }
+  const ctx = gateContext({ statePath: opts.state || null, repo: opts.repo || process.cwd() });
+  if (!ctx.active) {
+    out(opts.json, attendedVerdict(GATE));
+    return 0;
+  }
+  const path = ctx.statePath;
+  if (!path || !existsSync(path)) {
+    process.stderr.write(
+      "open-questions-gate: no run state found; cannot tell whether a question is open\n",
+    );
+    return 3;
+  }
+  let state;
+  try {
+    state = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    process.stderr.write(`open-questions-gate: ${path} is not JSON: ${err.message}\n`);
+    return 3;
+  }
+  const answer = pendingAnswer(state);
+  let result = evaluateOpenQuestions(state);
+  let stop = false;
+  if (answer) {
+    const applied = applyOpenAnswer(state, answer, { unattended: isUnattended() });
+    result = applied.result;
+    stop = applied.stop;
+    if (applied.next) {
+      const next = applied.next;
+      await updateState(path, (s) => {
+        const n = { ...s, status: next.status, analysis: next.analysis };
+        delete n.haltReason;
+        return n;
+      });
+    }
+  }
+  const repo =
+    opts.repo ||
+    (typeof state.worktreePath === "string" && existsSync(state.worktreePath)
+      ? state.worktreePath
+      : process.cwd());
+  await recordQuietly(
+    GATE,
+    result.verdict,
+    {
+      open: result.open,
+      ...(result.answer ? { answer: result.answer } : {}),
+      ...(result.assumed ? { assumed: result.assumed } : {}),
+      ...(result.reason ? { reason: result.reason } : {}),
+    },
+    { repo, statePath: path },
+  );
+  if (stop) {
+    await park(path, { outcome: "verification-failed", gate: GATE, reason: result.reason });
+  } else if (result.verdict === "fail") {
+    await park(path, {
+      outcome: "awaiting-answer",
+      waitingFor: "question",
+      pendingQuestion: pendingQuestionFor(result.questions),
+      reason: `${result.open} open question(s) from analysis Section 20; development did not start`,
+    });
+  }
+  out(opts.json, result);
+  return result.verdict === "fail" ? 1 : 0;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  main(process.argv.slice(2)).then((code) => process.exit(code));
+}

package/pipeline/scripts/phase-tracker.sh

@@ -9,7 +9,7 @@
 #
 # State persists to a per-task JSON file so multiple shell invocations
 # share the same task list:
-#   $HOME/.claude/logs/multi-agent/<task_id>/tracker-state.json
+#   ${LOGS_ROOT:-$HOME/.claude/logs/multi-agent}/<task_id>/tracker-state.json
 # (override with $TRACKER_FILE env var)
 #
 # `init` writes that flat path. READS go through pipeline/lib/run-paths.sh,
@@ -33,7 +33,7 @@
 # OTel span emission (v6.1.0+, opt-in):
 #   Set $MULTI_AGENT_OTEL_SPANS=1 to make every `update`, `sub`, and `tokens`
 #   action append one JSON line to:
-#     $HOME/.claude/logs/multi-agent/<task_id>/otel-spans.jsonl
+#     ${LOGS_ROOT:-$HOME/.claude/logs/multi-agent}/<task_id>/otel-spans.jsonl
 #   Each line is an OTLP-compatible JSON span with trace_id/span_id derived
 #   from the task_id, phase_id, and timestamp. Format intentionally simple
 #   so an OTel Collector's `filelog` receiver can tail + forward without a
@@ -59,7 +59,18 @@ set -uo pipefail
 # Run-state path resolution: pipeline/lib/run-paths.sh owns both layouts.
 _MA_RP_HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
-. "$_MA_RP_HERE/../lib/run-paths.sh" 2>/dev/null || . "$HOME/.claude/lib/run-paths.sh"
+if [ -f "$_MA_RP_HERE/../lib/run-paths.sh" ]; then . "$_MA_RP_HERE/../lib/run-paths.sh"; else . "$HOME/.claude/lib/run-paths.sh"; fi
+# The card's column headings are script chrome and stay English; the dependency
+# annotation inside a sub-phase name is prose, so it follows outputLanguage.
+# shellcheck source=/dev/null
+if [ -f "$_MA_RP_HERE/../lib/user-facing.sh" ]; then . "$_MA_RP_HERE/../lib/user-facing.sh"; else . "$HOME/.claude/lib/user-facing.sh"; fi
+
+waiting_word() {
+  case "$(ma_output_lang)" in
+    tr) printf 'bekliyor' ;;
+    *) printf 'waiting on' ;;
+  esac
+}
 
 
 if [ "$#" -lt 1 ]; then
@@ -108,7 +119,7 @@ if [ -z "$TRACKER_FILE" ]; then
     # `phase-tracker.sh init <other-task>`. In concurrent multi-agent runs (two terminals,
     # two parallel pipelines), the pointer becomes the wrong task. Always pass
     # MULTI_AGENT_TASK_ID per shell invocation for reliable per-session resolution.
-    POINTER="$HOME/.claude/logs/multi-agent/.tracker-current"
+    POINTER="${LOGS_ROOT:-$HOME/.claude/logs/multi-agent}/.tracker-current"
     if [ -f "$POINTER" ]; then
       TRACKER_FILE="$(cat "$POINTER")"
       if [ "${MULTI_AGENT_QUIET:-0}" != "1" ]; then
@@ -126,7 +137,7 @@ if [ -z "$TRACKER_FILE" ]; then
     # A run that does not exist yet resolves to the flat path, which is exactly
     # where `init` will create it - so new-run behaviour is unchanged.
     TRACKER_FILE="$(ma_resolve_run_file "$TASK_ID_FROM_ENV" tracker-state.json 2>/dev/null \
-      || echo "$HOME/.claude/logs/multi-agent/${TASK_ID_FROM_ENV}/tracker-state.json")"
+      || echo "${LOGS_ROOT:-$HOME/.claude/logs/multi-agent}/${TASK_ID_FROM_ENV}/tracker-state.json")"
   fi
 fi
 TRACKER_DIR="$(dirname "$TRACKER_FILE")"
@@ -138,11 +149,12 @@ need_jq() {
   }
 }
 
-# Live usage ping (best-effort). Emits one per-phase update to the private
-# dashboard via usage-report.mjs, always status=running so per-phase updates
-# never fold the run into rollup counters - the terminal fold comes only from
-# the Phase 5 / halt emit that reads the real run status. The emitter no-ops
-# unless prefs.global.usageLog.enabled; detached so it never blocks a boundary.
+# Live usage ping (best-effort). Emits one update per phase transition to the
+# private dashboard via usage-report.mjs (`--event phase`). The emitter derives
+# the run status from agent-state.json and the current phase from this tracker;
+# the completed / halted / parked events come from the phase docs that end,
+# halt or park a run. It no-ops unless prefs.global.usageLog.enabled; detached
+# so it never blocks a boundary.
 usage_live_ping() {
   # Smoke runs exercise this script's state handling, never the live dashboard -
   # a test gate must not leave phantom "running" rows on the timeline.
@@ -166,7 +178,7 @@ usage_live_ping() {
   # user who never enabled it pays nothing per phase boundary. jq is already a
   # hard dependency of this script.
   jq -e '.global.usageLog.enabled == true' "$prefs" >/dev/null 2>&1 || return 0
-  ( node "$script" --task-id "$task" --phase "$phase" --status running >/dev/null 2>&1 & ) 2>/dev/null || true
+  ( node "$script" --task-id "$task" --phase "$phase" --event phase >/dev/null 2>&1 & ) 2>/dev/null || true
 }
 
 # Decode HTML entities in a tile title.
@@ -293,8 +305,7 @@ emit_otel_span() {
   # Deterministic 128-bit trace_id from task_id, 64-bit span_id from event+phase+timestamp.
   #
   # sha256_hex, not `shasum` directly: this runs on every phase on every host, and
-  # `shasum` is a perl script that is absent from minimal Linux images and many
-  # containers. Without a fallback the ids came back empty and the span was written with
+  # `shasum` is a perl script and a trimmed toolchain may lack perl. Without a fallback the ids came back empty and the span was written with
   # blank trace/span - valid JSON, useless telemetry, and no error to notice.
   local trace_id span_id
   trace_id=$(printf "%s" "$task_id" | sha256_hex | awk '{print substr($1,1,32)}')
@@ -480,13 +491,13 @@ state_lock_stale() {
     kill -0 "$pid" 2>/dev/null && return 1
     return 0
   fi
-  # GNU form first, and not because of style. On GNU coreutils `stat -f` is a valid
-  # flag meaning --file-system, where `%m` prints the MOUNT POINT - so a BSD-first
-  # chain succeeds on Linux, returns something like `/`, never reaches the `||`, and
-  # then the arithmetic below fails on a path. The effect was that a stale lock with
-  # no pid file was never reclaimed on Linux: every tracker call spun the full ~5s
-  # bound and fell open with a warning. macOS `stat -c` is simply invalid, so it
-  # errors and falls through cleanly - which is why this order works on both.
+  # GNU form first, and not because of style. GNU coreutils can sit first on PATH on a
+  # mac (Homebrew gnubin), and there `stat -f` is a valid flag meaning --file-system,
+  # where `%m` prints the MOUNT POINT - so a BSD-first chain succeeds, returns
+  # something like `/`, never reaches the `||`, and the arithmetic below fails on a
+  # path: a stale lock with no pid file would never be reclaimed. BSD `stat -c` is
+  # simply invalid, so it errors and falls through cleanly - which is why this order
+  # works with either stat.
   mtime=$(stat -c %Y "$TRACKER_LOCK_DIR" 2>/dev/null || stat -f %m "$TRACKER_LOCK_DIR" 2>/dev/null || echo "")
   # Guard the arithmetic anyway: a non-numeric value here must not abort the caller
   # under `set -u`, and treating it as "not stale" is the conservative branch.
@@ -616,7 +627,7 @@ tracker_next_hint() {
     # `subjects` now carries Phase 1's plan steps as indented rows, and
     # update_plan takes the whole list anyway, so re-reading it is what puts
     # those steps on the Codex plan without a second mechanism. Codex has no
-    # dependency concept; the "(bekliyor: ...)" suffix inside the step text is
+    # dependency concept; the "(waiting on: ...)" suffix inside the step text is
     # where that information survives on this host.
     codex) mirror="update_plan: set step \"Phase $pid $name\" to $status, re-reading the FULL list from \`phase-tracker.sh subjects\` (it is not a delta, and the indented rows are plan steps that belong in it)" ;;
     *) mirror="no task widget on this host - reprint the card above inside your reply text" ;;
@@ -785,12 +796,12 @@ subjects() {
     # exactly one string per row and has no parent field - there is no nesting
     # to ask for, so the only place a hierarchy can be expressed is the string.
     if [ -z "$want" ] || [ "$want" = "$pid" ]; then
-      echo "$state" | jq -r --arg pid "$pid" '
+      echo "$state" | jq -r --arg pid "$pid" --arg waiting "$(waiting_word)" '
         ([.phases[] | select(.id == $pid)][0].subs) // []
         | .[]
         | "  " + (.id // "") + " " + (.name // "")
           + (if ((.deps // []) | length) > 0
-             then " (bekliyor: " + ((.deps // []) | join(", ")) + ")"
+             then " (" + $waiting + ": " + ((.deps // []) | join(", ")) + ")"
              else "" end)'
     fi
   done <<< "$rows"
@@ -1053,7 +1064,7 @@ render() {
         while IFS=$'\x1f' read -r sid sname sstatus sdeps; do
           # The card is the only surface a Copilot session has, so a dependency
           # that is invisible here is invisible to that user entirely.
-          [ -n "$sdeps" ] && sname="$sname (bekliyor: $sdeps)"
+          [ -n "$sdeps" ] && sname="$sname ($(waiting_word): $sdeps)"
           sg=$(glyph_for "$sstatus")
           connector="├─"
           if [ "$j" = "$((sub_count - 1))" ]; then connector="└─"; fi
@@ -1095,7 +1106,7 @@ case "$ACTION" in
     # Honor an explicit $TRACKER_FILE (tests, isolated runs); only derive the
     # canonical home path when the caller did not supply one.
     if [ "$TRACKER_FILE_FROM_ENV" != "1" ]; then
-      TRACKER_FILE="$HOME/.claude/logs/multi-agent/${TASK_ID}/tracker-state.json"
+      TRACKER_FILE="${LOGS_ROOT:-$HOME/.claude/logs/multi-agent}/${TASK_ID}/tracker-state.json"
     fi
     TRACKER_DIR="$(dirname "$TRACKER_FILE")"
     mkdir -p "$TRACKER_DIR" 2>/dev/null
@@ -1113,7 +1124,7 @@ case "$ACTION" in
     # (Smoke isolation is handled by a sandbox HOME, so it still writes a pointer
     # inside its own tree - which its later calls depend on.)
     if [ "$TRACKER_FILE_FROM_ENV" != "1" ]; then
-      echo "$TRACKER_FILE" > "$HOME/.claude/logs/multi-agent/.tracker-current"
+      echo "$TRACKER_FILE" > "${LOGS_ROOT:-$HOME/.claude/logs/multi-agent}/.tracker-current"
     fi
     render
     usage_live_ping "$TASK_ID" 0
@@ -1210,7 +1221,10 @@ GATE
     emit_otel_span "phase.update" "$PID" "$STATUS" "{\"status\": \"$STATUS\"}"
     render
     tracker_next_hint "$PID" "$STATUS"
-    usage_live_ping "$(basename "$TRACKER_DIR")" "$PID"
+    if [ "$STATUS" = "completed" ] && command -v node >/dev/null 2>&1; then
+      node "$(dirname "$0")/record-phase.mjs" --task-id "$(basename "$TRACKER_DIR")" --phase "$PID" >/dev/null 2>&1 || true
+    fi
+    [ "$STATUS" = "pending" ] || usage_live_ping "$(basename "$TRACKER_DIR")" "$PID"
     ;;
 
   plan)