@mmerterden/multi-agent-pipeline 20.34.0 → 20.36.0

package/pipeline/scripts/pre-push-check.sh

@@ -2,19 +2,13 @@
 # pre-push-check.sh  -  primary gate before every push.
 #
 # Purpose:
-#   The repo HAS workflows (test.yml, ci-lite.yml), but they have not executed
-#   since 2026-07-02: every attempt after that day - the last on 2026-07-25 -
-#   finished in about four seconds with zero steps recorded, which is a
-#   runner/quota block rather than a test failure. Both are now dormant by
-#   declaration too (ADR-0011: the push triggers are commented out). So this
-#   hook is not a second opinion - it is the only thing standing between a
-#   broken commit and npm.
+#   The local gate before every push. The repository's CI workflows are dormant
+#   (ADR-0011), so this is what stands between a commit and npm.
 #
-#   It therefore runs the CANONICAL chain, `npm test`, rather than a hand-picked
-#   subset. A subset drifts from the chain as steps are added, and a bare
-#   `for f in smoke-*.sh` loop cannot tell a passing suite from one that exited 0
-#   having asserted nothing; run-smokes.mjs can. A safety net with holes in it is worse than a known gap:
-#   it is trusted.
+#   It runs the canonical chain, `npm test`, rather than a hand-picked subset:
+#   a subset drifts from the chain as steps are added, and a bare
+#   `for f in smoke-*.sh` loop cannot tell a passing suite from one that exited
+#   0 having asserted nothing; run-smokes.mjs can.
 #
 # Two modes, because a gate that runs INSIDE the push is a gate that breaks
 # pushes. Git opens the connection to the remote before this hook fires, so a

package/pipeline/scripts/rework-base.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * @file rework-base.mjs  -  the tree a rework round started from.
+ *
+ * scope-check-gate.mjs --rejected compares the rework against the tree the
+ * review read, because rejected findings carry that tree's line numbers. Each
+ * review round rewrites triage-output.json, so the base is kept per round:
+ * `.pipeline/rework-base-<iteration>`. `record` writes HEAD for the round when
+ * the round has none yet (a resumed re-entry keeps the base it started from)
+ * and prints it; `get` only prints it.
+ *
+ * Usage:
+ *   rework-base.mjs record --worktree <dir> --iteration <N>
+ *   rework-base.mjs get    --worktree <dir> --iteration <N>
+ *
+ * Exit: 0 printed, 1 no base recorded for the round (get) or HEAD unreadable
+ * (record), 64 usage.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+const SHA = /^[0-9a-f]{40,64}$/;
+
+export function basePath(worktree, iteration) {
+  return join(worktree, ".pipeline", `rework-base-${iteration}`);
+}
+
+function read(path) {
+  if (!existsSync(path)) return null;
+  const sha = readFileSync(path, "utf8").trim();
+  return SHA.test(sha) ? sha : null;
+}
+
+export function record(worktree, iteration) {
+  const path = basePath(worktree, iteration);
+  const kept = read(path);
+  if (kept) return kept;
+  const head = execFileSync("git", ["-C", worktree, "rev-parse", "HEAD"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: 30_000,
+  }).trim();
+  if (!SHA.test(head)) throw new Error("HEAD is not a commit");
+  mkdirSync(join(worktree, ".pipeline"), { recursive: true });
+  writeFileSync(path, head + "\n");
+  return head;
+}
+
+export function get(worktree, iteration) {
+  return read(basePath(worktree, iteration));
+}
+
+function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const opt = (f) => {
+    const i = rest.indexOf(f);
+    return i >= 0 ? rest[i + 1] : undefined;
+  };
+  const worktree = opt("--worktree");
+  const iteration = Number(opt("--iteration"));
+  if (
+    !["record", "get"].includes(cmd) ||
+    rest.length !== 4 ||
+    !worktree ||
+    !Number.isInteger(iteration) ||
+    iteration < 1
+  ) {
+    console.error("usage: rework-base.mjs record|get --worktree <dir> --iteration <N>");
+    return 64;
+  }
+  let sha;
+  try {
+    sha = cmd === "record" ? record(worktree, iteration) : get(worktree, iteration);
+  } catch (err) {
+    console.error(`rework-base: ${err.message}`);
+    return 1;
+  }
+  if (!sha) return 1;
+  process.stdout.write(sha + "\n");
+  return 0;
+}
+
+if (invokedDirectly(import.meta.url)) process.exit(main());

package/pipeline/scripts/run-commit-check.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * @file run-commit-check.mjs  -  a commit inside a pipeline run is authored by
+ * the identity Phase 0 chose for it.
+ *
+ * Called by pre-commit-check.sh with the hook payload on stdin. For a `git
+ * commit` made in the session a live run is bound to, the author git will
+ * record (`--author`, `-c user.email=`, else `git var GIT_AUTHOR_IDENT` in the
+ * repository) must carry the run's identity email (`projects[].identity` for
+ * the repository's worktree, else `identity`). Outside a bound run, for a run
+ * that is not live, or with no identity recorded, it says nothing.
+ *
+ * Usage: run-commit-check.mjs --repo <dir> < hook-payload.json
+ * Exit: 0 fine or not judged; 2 the author is not the run's identity.
+ *
+ * @module pipeline/scripts/run-commit-check
+ */
+
+import { spawnSync } from "node:child_process";
+import { readFileSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { findActiveRun } from "./_active-run.mjs";
+
+const SESSION_BOUND = new Set(["session", "host-session"]);
+const LIVE = new Set(["in_progress", "awaiting_input"]);
+const COMMIT = /\bgit\b(?:\s+-[cC]\s+\S+|\s+--?[\w-]+(?:=\S+)?)*\s+commit\b/;
+
+const real = (p) => {
+  try {
+    return realpathSync(resolve(p));
+  } catch {
+    return resolve(p);
+  }
+};
+
+/** The author email this command makes git record, or null to ask git. */
+export function commandAuthor(command) {
+  const author = /--author[=\s]+(['"]?)[^<'"]*<([^>]+)>\1/.exec(command);
+  if (author) return author[2].trim();
+  const cfg = /-c\s+user\.email=(['"]?)([^\s'"]+)\1/.exec(command);
+  return cfg ? cfg[2].trim() : null;
+}
+
+/** The identity email the run expects for a commit in `repo`, or null. */
+export function expectedEmail(state, repo) {
+  const here = real(repo);
+  for (const p of Array.isArray(state.projects) ? state.projects : []) {
+    if (p?.worktreePath && real(p.worktreePath) === here && p.identity?.email)
+      return p.identity.email;
+  }
+  return typeof state.identity?.email === "string" && state.identity.email
+    ? state.identity.email
+    : null;
+}
+
+function gitAuthorEmail(repo) {
+  const r = spawnSync("git", ["-C", repo, "var", "GIT_AUTHOR_IDENT"], {
+    encoding: "utf8",
+    timeout: 5000,
+  });
+  return /<([^>]*)>/.exec(r.stdout || "")?.[1]?.trim() || null;
+}
+
+/** The refusal line, or null. */
+export function verdict(payload, repo, env = process.env) {
+  const command = payload?.tool_input?.command;
+  if (typeof command !== "string" || !COMMIT.test(command)) return null;
+  const run = findActiveRun({
+    sessionId: typeof payload.session_id === "string" ? payload.session_id : null,
+    cwd: typeof payload.cwd === "string" ? payload.cwd : repo,
+    env,
+  });
+  if (!run || !SESSION_BOUND.has(run.matchedBy) || !LIVE.has(run.state?.status)) return null;
+  const want = expectedEmail(run.state, repo);
+  if (!want) return null;
+  const got = commandAuthor(command) || gitAuthorEmail(repo);
+  if (!got || got.toLowerCase() === want.toLowerCase()) return null;
+  return `BLOCKED: this commit would be authored by ${got}, and run ${run.state.taskId || run.statePath} commits as ${want} (the identity chosen in Phase 0). Set the worktree's user.email to it, or drop the override.`;
+}
+
+function main(argv) {
+  const i = argv.indexOf("--repo");
+  const repo = i >= 0 && argv[i + 1] ? argv[i + 1] : process.cwd();
+  let payload;
+  try {
+    payload = JSON.parse(readFileSync(0, "utf8"));
+  } catch {
+    return 0;
+  }
+  const line = verdict(payload, repo);
+  if (!line) return 0;
+  process.stderr.write(`${line}\n`);
+  return 2;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  try {
+    process.exitCode = main(process.argv.slice(2));
+  } catch {
+    process.exitCode = 0;
+  }
+}

package/pipeline/scripts/run-scope-guard.mjs

@@ -51,6 +51,12 @@ const FIGMA_TOOL = /^mcp__.*figma/i;
 const SESSION_BOUND = new Set(["session", "host-session"]);
 const LIVE = new Set(["in_progress", "awaiting_input"]);
 const FILE_TOOLS = new Set(["Edit", "Write", "NotebookEdit", "MultiEdit"]);
+const STATE_FILES = new Set(["agent-state.json", "tracker-state.json"]);
+const STATE_REDIRECT =
+  /(?:>>?|\btee\s+(?:-a\s+)?)\s*['"]?[^\s'"|;&]*(?:agent|tracker)-state\.json\b/;
+const FIGMA_URL = /\bhttps?:\/\/(?:[\w-]+\.)*figma\.com(?=[/:?#\s'"]|$)/i;
+const ADD_ALL = /\bgit\s+(?:-C\s+\S+\s+)?add\s+(?:[^;&|\n]*\s)?(?:-A|--all|\.)(?=$|[\s;&|])/;
+const HTTP_CLIENT = /(?:^|[\s;&|(])(?:curl|wget|http|https|xh)\s/;
 
 const deny = (reason) => ({
   hookSpecificOutput: {
@@ -76,7 +82,39 @@ async function recordMcpCall(statePath, tool, phase) {
   });
 }
 
-async function figmaDecision(payload, run) {
+/** A Figma design read over HTTP: a WebFetch of figma.com, or curl and the like at it. */
+function figmaOverHttp(payload) {
+  const ti = payload.tool_input || {};
+  if (payload.tool_name === "WebFetch") return typeof ti.url === "string" && FIGMA_URL.test(ti.url);
+  if (payload.tool_name !== "Bash" || typeof ti.command !== "string") return false;
+  return HTTP_CLIENT.test(ti.command) && FIGMA_URL.test(ti.command);
+}
+
+/** An autopilot run answers its own questions: it derives, or it records a halt. */
+function askDecision(run) {
+  const s = run.state;
+  if (!LIVE.has(s.status) || modeOf(s) !== "autopilot") return null;
+  return deny(
+    `run ${s.taskId || run.statePath} is on autopilot, which asks nobody. Derive the answer from the analysis, the repo and the preferences, or record a halt (status "paused" with a haltReason) for a decision only the user can make.`,
+  );
+}
+
+/** A write to run state that bypasses write-state.mjs, or null. */
+function stateWriteDecision(payload) {
+  const ti = payload.tool_input || {};
+  const raw = FILE_TOOLS.has(payload.tool_name) ? ti.file_path || ti.notebook_path : null;
+  const byFile = typeof raw === "string" && STATE_FILES.has(basename(raw));
+  const byShell =
+    payload.tool_name === "Bash" &&
+    typeof ti.command === "string" &&
+    STATE_REDIRECT.test(ti.command);
+  if (!byFile && !byShell) return null;
+  return deny(
+    'run state is written through write-state.mjs only, which locks the file, merges the patch and refuses unearned phase moves; pipe the patch into node "$HOME/.claude/scripts/write-state.mjs" <path> instead.',
+  );
+}
+
+async function figmaDecision(payload, run, { record = true } = {}) {
   const tool = payload.tool_name;
   const state = run.state;
   // A finished, failed or abandoned run governs nothing and records nothing.
@@ -88,7 +126,7 @@ async function figmaDecision(payload, run) {
       `${tool} is a Figma call at Phase ${at} of run ${state.taskId || run.statePath}. The design is read during analysis only (through Phase ${figmaThroughPhase()}); later phases work from the analysis document and the repo's Code Connect mappings. If a variant or value is missing, halt and re-run /multi-agent:analysis.`,
     );
   }
-  await recordMcpCall(run.statePath, tool, Math.min(5, Math.max(0, at)));
+  if (record) await recordMcpCall(run.statePath, tool, Math.min(5, Math.max(0, at)));
   return null;
 }
 
@@ -152,8 +190,16 @@ function boundaryDecision(payload, run, env) {
 export async function decide(payload, env = process.env) {
   if (!payload || typeof payload !== "object") return null;
   const tool = typeof payload.tool_name === "string" ? payload.tool_name : "";
+  const stateWrite = stateWriteDecision(payload);
+  if (stateWrite) return stateWrite;
   const figma = FIGMA_TOOL.test(tool);
-  if (!figma && !FILE_TOOLS.has(tool)) return null;
+  const figmaHttp = !figma && figmaOverHttp(payload);
+  const asking = tool === "AskUserQuestion";
+  const addAll =
+    tool === "Bash" &&
+    typeof payload.tool_input?.command === "string" &&
+    ADD_ALL.test(payload.tool_input.command);
+  if (!figma && !figmaHttp && !asking && !addAll && !FILE_TOOLS.has(tool)) return null;
   const run = findActiveRun({
     sessionId: typeof payload.session_id === "string" ? payload.session_id : null,
     cwd: typeof payload.cwd === "string" ? payload.cwd : null,
@@ -162,6 +208,15 @@ export async function decide(payload, env = process.env) {
   // Only a run bound to this session: an old local-mode run matched by its
   // worktree (the project root) must not govern every later session there.
   if (!run || !SESSION_BOUND.has(run.matchedBy)) return null;
+  if (asking) return askDecision(run);
+  if (addAll) {
+    return LIVE.has(run.state.status)
+      ? deny(
+          `run ${run.state.taskId || run.statePath} stages the task's files by name: git add -A, --all and . also take agent artefacts and anything sensitive in the tree.`,
+        )
+      : null;
+  }
+  if (figmaHttp) return figmaDecision(payload, run, { record: false });
   return figma ? figmaDecision(payload, run) : boundaryDecision(payload, run, env);
 }
 

package/pipeline/scripts/run-scope-guard.sh

@@ -19,5 +19,17 @@ CORE="$HERE/run-scope-guard.mjs"
 [ -f "$CORE" ] || exit 0
 command -v node >/dev/null 2>&1 || exit 0
 
-node "$CORE" 2>/dev/null || true
+# Most Bash and WebFetch calls concern neither Figma nor run state; those end
+# here without starting node.
+INPUT="$(cat)"
+case "$INPUT" in
+  *'"tool_name":"Bash"'* | *'"tool_name": "Bash"'* | *'"tool_name":"WebFetch"'* | *'"tool_name": "WebFetch"'*)
+    case "$INPUT" in
+      *[Ff]igma* | *agent-state.json* | *tracker-state.json* | *" add "*) ;;
+      *) exit 0 ;;
+    esac
+    ;;
+esac
+
+printf '%s' "$INPUT" | node "$CORE" 2>/dev/null || true
 exit 0

package/pipeline/scripts/scope-check-gate.mjs

@@ -11,6 +11,7 @@
  *   git diff --name-only <base>...HEAD | node scope-check-gate.mjs --check .pipeline/scope-check.json --diff-files -
  *   node scope-check-gate.mjs --check scope-check.json --diff-files files.txt [--advisory]
  *       [--patch <unified diff> | --repo <dir> --patch-range <a>...<b>]
+ *       [--rejected <triage-output.json> --repo <dir> --rework-base <rev>]
  *
  * Output (stdout, JSON): {ok, justified, unjustified[], unlisted[], notDone, formatOnly[]}
  *   unjustified = in the diff, missing from files[] (or with an empty reason)
@@ -20,6 +21,11 @@
  *                 touch. Reported, never fatal. --patch-range reads that diff
  *                 with git itself, its output format pinned, so a caller needs
  *                 no file or process substitution for it.
+ *   rejectedTouched = with --rejected and --rework-base, findings triage
+ *                 rejected whose lines a rework hunk (rework base against the
+ *                 working tree) changed: Phase 2 acts on accepted findings
+ *                 only, so a rework that edits a rejected finding's lines is
+ *                 "fixing" a finding triage ruled out. Reported, never fatal.
  *
  * Exit codes: 0 every diff file justified (or --advisory), 1 otherwise or on
  * unreadable input, 64 usage.
@@ -32,7 +38,10 @@ import { normalizeFile } from "./_fingerprint.mjs";
 import { parseUnifiedDiff } from "./_unified-diff.mjs";
 
 const USAGE =
-  "usage: scope-check-gate.mjs --check <scope-check.json> --diff-files <path|-> [--advisory] [--patch <diff> | --repo <dir> --patch-range <a>...<b>]";
+  "usage: scope-check-gate.mjs --check <scope-check.json> --diff-files <path|-> [--advisory] [--patch <diff> | --repo <dir> --patch-range <a>...<b>] [--rejected <triage.json> --repo <dir> --rework-base <rev>]";
+
+const REV = /^[A-Za-z0-9_./~^@{}-]+$/;
+const NEAR = 2;
 
 function parseArgs(argv) {
   const opts = {};
@@ -44,16 +53,19 @@ function parseArgs(argv) {
     else if (a === "--patch") opts.patch = argv[++i];
     else if (a === "--patch-range") opts.patchRange = argv[++i];
     else if (a === "--repo") opts.repo = argv[++i];
+    else if (a === "--rejected") opts.rejected = argv[++i];
+    else if (a === "--rework-base") opts.reworkBase = argv[++i];
     else return null;
   }
-  if (opts.patchRange !== undefined && !/^[A-Za-z0-9_./~^@{}-]+$/.test(opts.patchRange))
-    return null;
-  if (opts.patchRange?.startsWith("-")) return null;
+  for (const rev of [opts.patchRange, opts.reworkBase]) {
+    if (rev !== undefined && (!REV.test(rev) || rev.startsWith("-"))) return null;
+  }
+  if (Boolean(opts.rejected) !== Boolean(opts.reworkBase)) return null;
   return opts.check && opts.diffFiles ? opts : null;
 }
 
-/** The diff of a revision range, in the one shape formatOnlyHunks reads. */
-function rangeDiff(repo, range) {
+/** The diff of a revision range (or a revision against the working tree), in the one shape the hunk readers take. */
+function rangeDiff(repo, range, unified = []) {
   return execFileSync(
     "git",
     [
@@ -67,6 +79,7 @@ function rangeDiff(repo, range) {
       "--no-textconv",
       "--src-prefix=a/",
       "--dst-prefix=b/",
+      ...unified,
       range,
       "--",
     ],
@@ -180,6 +193,45 @@ export function formatOnlyHunks(patch) {
   return found;
 }
 
+/**
+ * Rejected findings whose line a hunk of the rework diff changed. The diff
+ * runs from the reviewed tree, so a finding's line is read on the hunk's old
+ * side: a hunk that removes or rewrites lines within NEAR of it, or inserts
+ * next to it, touches it.
+ */
+export function rejectedTouched(triage, patch) {
+  const rejected = (Array.isArray(triage?.rejected) ? triage.rejected : [])
+    .map((r) => r?.finding)
+    .filter((f) => f && typeof f.file === "string" && Number.isInteger(f.line) && f.line > 0);
+  if (!rejected.length) return [];
+  const ranges = new Map();
+  for (const [file, diff] of parseUnifiedDiff(patch)) {
+    const list = [];
+    for (const h of diff.hunks) {
+      const m = /^@@ -(\d+)(?:,(\d+))?/.exec(h.header);
+      if (!m) continue;
+      const start = Number(m[1]);
+      const count = m[2] === undefined ? 1 : Number(m[2]);
+      list.push({ from: start - NEAR, to: start + Math.max(count, 1) - 1 + NEAR, hunk: h.header });
+    }
+    ranges.set(normalizeFile(file), list);
+  }
+  const out = [];
+  for (const f of rejected) {
+    const hit = (ranges.get(normalizeFile(f.file)) || []).find(
+      (r) => f.line >= r.from && f.line <= r.to,
+    );
+    if (hit)
+      out.push({
+        file: normalizeFile(f.file),
+        line: f.line,
+        issue: f.issue ?? null,
+        hunk: hit.hunk,
+      });
+  }
+  return out;
+}
+
 export function evaluate(check, diffFiles) {
   const files = Array.isArray(check?.files) ? check.files : [];
   const reasons = new Map();
@@ -228,6 +280,18 @@ function main() {
       result.patchError = err.message;
     }
   }
+  if (opts.rejected) {
+    try {
+      const triage = JSON.parse(readText(opts.rejected));
+      result.rejectedTouched = rejectedTouched(
+        triage,
+        rangeDiff(opts.repo, opts.reworkBase, ["-U0"]),
+      );
+    } catch (err) {
+      result.rejectedTouched = [];
+      result.rejectedError = err.message;
+    }
+  }
   process.stdout.write(JSON.stringify(result) + "\n");
   return result.ok ? 0 : fail;
 }

package/pipeline/scripts/task-mirror.mjs

@@ -21,12 +21,21 @@
  *     is left alone.
  * The task goes under the phase in progress when it was created.
  *
- * Exits 0 on every path and prints nothing: a mirror, not a gate. A failure is
- * written to the hook failure log.
+ * Phase tiles: a TaskCreate of "Phase N ..." records its id as the phase's
+ * `tasklist_id` (what :resume rebuilds the widget from), replacing the id a
+ * previous session left. The widget renders tiles in creation order, so a
+ * tile created after a higher-numbered one in the same session shows out of
+ * order (tracker-contract.md, "TaskCreate ordering"); the hook says so to the
+ * model as additionalContext. Which tiles this session created is kept in
+ * `tile-session.json` beside the tracker and starts over with a new session,
+ * so tiles a resume recreates are not compared with the old session's.
+ *
+ * Exits 0 on every path, blocks nothing, and prints only that ordering note. A
+ * failure is written to the hook failure log.
  */
 
 import { spawnSync } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -37,6 +46,7 @@ const HOOK = "task-mirror";
 const SESSION_BOUND = new Set(["session", "host-session"]);
 const STATUSES = new Set(["pending", "in_progress", "completed"]);
 const TILE = /^Phase \d+\b/;
+const TILE_NO = /^Phase (\d+)\b/;
 const MAX_INPUT = 256 * 1024;
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -102,6 +112,43 @@ export function mirrorArgs(payload, tracker) {
   return null;
 }
 
+/**
+ * For a phase tile's TaskCreate: the phase it is, the id it got, and the
+ * higher-numbered phases whose tiles already exist. Null for anything else.
+ */
+export function tileOf(payload, tracker) {
+  if (payload?.tool_name !== "TaskCreate") return null;
+  const m = TILE_NO.exec(String(payload.tool_input?.subject ?? "").trim());
+  if (!m) return null;
+  const n = Number(m[1]);
+  const phases = Array.isArray(tracker?.phases) ? tracker.phases : [];
+  const phase = phases.find((p) => Number(p.id) === n) ?? null;
+  return {
+    phase,
+    id: createdId(payload.tool_response),
+    recorded: phase ? String(phase.meta?.tasklist_id ?? "") : "",
+  };
+}
+
+/**
+ * This session's tile record after creating phase `n`, and the phases whose
+ * tiles this session created before it with a higher number.
+ */
+export function sessionTiles(previous, sessionId, n) {
+  if (!sessionId) return { record: previous, after: [] };
+  const same =
+    previous &&
+    previous.session === sessionId &&
+    previous.tiles &&
+    typeof previous.tiles === "object";
+  const tiles = same ? { ...previous.tiles } : {};
+  const after = Object.keys(tiles)
+    .filter((p) => Number(p) > n)
+    .sort((a, b) => Number(a) - Number(b));
+  tiles[String(n)] = true;
+  return { record: { session: sessionId, tiles }, after };
+}
+
 export function mirror(payload, env = process.env) {
   if (!payload || !["TaskCreate", "TaskUpdate"].includes(payload.tool_name)) return null;
   const run = findActiveRun({
@@ -119,26 +166,70 @@ export function mirror(payload, env = process.env) {
   } catch {
     return null;
   }
+  const tracked = (args) => {
+    const r = spawnSync("bash", [join(HERE, "phase-tracker.sh"), ...args], {
+      env: {
+        ...env,
+        MULTI_AGENT_TASK_ID: run.state.taskId,
+        TRACKER_FILE: trackerPath,
+        TRACKER_QUIET: "1",
+      },
+      encoding: "utf8",
+      timeout: 8000,
+    });
+    if (r.status !== 0) logHookFailure(HOOK, `phase-tracker ${args[0]} exited ${r.status}`, env);
+  };
+  const tile = tileOf(payload, tracker);
+  if (tile) {
+    if (!tile.phase) return null;
+    if (tile.id && tile.recorded !== tile.id)
+      tracked(["meta", String(tile.phase.id), "tasklist_id", tile.id]);
+    const sidecar = join(runDirOf(run.statePath), "tile-session.json");
+    let previous;
+    try {
+      previous = JSON.parse(readFileSync(sidecar, "utf8"));
+    } catch {
+      previous = null;
+    }
+    const { record, after } = sessionTiles(
+      previous,
+      String(payload.session_id ?? ""),
+      Number(tile.phase.id),
+    );
+    if (record)
+      try {
+        const tmp = `${sidecar}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(record));
+        renameSync(tmp, sidecar);
+      } catch (e) {
+        logHookFailure(HOOK, `tile record: ${String(e?.message || e).slice(0, 120)}`, env);
+      }
+    return after.length
+      ? {
+          note:
+            `Phase ${tile.phase.id}'s tile was created after the tiles of phase ${after.join(", ")}, ` +
+            "so the task widget shows it out of order. Tiles are created in phase-number order before any " +
+            'TaskUpdate (tracker-contract.md, "TaskCreate ordering").',
+        }
+      : null;
+  }
   const args = mirrorArgs(payload, tracker);
   if (!args) return null;
-  const r = spawnSync("bash", [join(HERE, "phase-tracker.sh"), ...args], {
-    env: {
-      ...env,
-      MULTI_AGENT_TASK_ID: run.state.taskId,
-      TRACKER_FILE: trackerPath,
-      TRACKER_QUIET: "1",
-    },
-    encoding: "utf8",
-    timeout: 8000,
-  });
-  if (r.status !== 0) logHookFailure(HOOK, `phase-tracker task exited ${r.status}`, env);
+  tracked(args);
   return args;
 }
 
 if (invokedDirectly(import.meta.url)) {
   try {
     const raw = readFileSync(0, "utf8").slice(0, MAX_INPUT);
-    mirror(JSON.parse(raw));
+    const out = mirror(JSON.parse(raw));
+    if (out?.note) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: out.note },
+        }) + "\n",
+      );
+    }
   } catch (e) {
     try {
       logHookFailure(HOOK, String(e?.message || e).slice(0, 200));

package/pipeline/scripts/task-mirror.sh

@@ -6,8 +6,9 @@
 # logic is in task-mirror.mjs; this wrapper exists because every hook the
 # pipeline registers is a `bash "$HOME/.<host>/scripts/<name>"` command.
 #
-# Exits 0 on every path and prints nothing: a missing node or any internal
-# error means no mirror, never a blocked tool call.
+# Exits 0 on every path; its only output is a tile-ordering note for the
+# model. A missing node or any internal error means no mirror, never a blocked
+# tool call.
 
 set -u