@mmerterden/multi-agent-pipeline 20.34.0 → 20.35.0

package/pipeline/lib/qr-code.mjs

@@ -0,0 +1,360 @@
+/**
+ * qr-code.mjs  -  a QR Code Model 2 encoder (ISO/IEC 18004), byte mode only.
+ *
+ * Used by office-pair to show the pairing link on the machine's own screen.
+ * Byte mode covers any UTF-8 text; the smallest version that fits the text at
+ * the requested error-correction level is chosen, and the mask with the lowest
+ * penalty score is applied.
+ *
+ * Zero runtime dependencies (ADR-0004).
+ *
+ * @module pipeline/lib/qr-code
+ */
+
+const ECC_FORMAT_BITS = { L: 1, M: 0, Q: 3, H: 2 };
+
+// Per version (index 1..40): error-correction codewords per block, and the
+// number of blocks, for each level (ISO/IEC 18004 table 9).
+const ECC_PER_BLOCK = {
+  L: [
+    -1, 7, 10, 15, 20, 26, 18, 20, 24, 30, 18, 20, 24, 26, 30, 22, 24, 28, 30, 28, 28, 28, 28, 30,
+    30, 26, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30,
+  ],
+  M: [
+    -1, 10, 16, 26, 18, 24, 16, 18, 22, 22, 26, 30, 22, 22, 24, 24, 28, 28, 26, 26, 26, 26, 28, 28,
+    28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28,
+  ],
+  Q: [
+    -1, 13, 22, 18, 26, 18, 24, 18, 22, 20, 24, 28, 26, 24, 20, 30, 24, 28, 28, 26, 30, 28, 30, 30,
+    30, 30, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30,
+  ],
+  H: [
+    -1, 17, 28, 22, 16, 22, 28, 26, 26, 24, 28, 24, 28, 22, 24, 24, 30, 28, 28, 26, 28, 30, 24, 30,
+    30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30,
+  ],
+};
+const BLOCKS = {
+  L: [
+    -1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 4, 4, 4, 4, 4, 6, 6, 6, 6, 7, 8, 8, 9, 9, 10, 12, 12, 12, 13, 14,
+    15, 16, 17, 18, 19, 19, 20, 21, 22, 24, 25,
+  ],
+  M: [
+    -1, 1, 1, 1, 2, 2, 4, 4, 4, 5, 5, 5, 8, 9, 9, 10, 10, 11, 13, 14, 16, 17, 17, 18, 20, 21, 23,
+    25, 26, 28, 29, 31, 33, 35, 37, 38, 40, 43, 45, 47, 49,
+  ],
+  Q: [
+    -1, 1, 1, 2, 2, 4, 4, 6, 6, 8, 8, 8, 10, 12, 16, 12, 17, 16, 18, 21, 20, 23, 23, 25, 27, 29, 34,
+    34, 35, 38, 40, 43, 45, 48, 51, 53, 56, 59, 62, 65, 68,
+  ],
+  H: [
+    -1, 1, 1, 2, 4, 4, 4, 5, 6, 8, 8, 11, 11, 16, 16, 18, 16, 19, 21, 25, 25, 25, 34, 30, 32, 35,
+    37, 40, 42, 45, 48, 51, 54, 57, 60, 63, 66, 70, 74, 77, 81,
+  ],
+};
+
+/** Modules available for data and error correction in a version. */
+export function rawDataModules(version) {
+  let n = (16 * version + 128) * version + 64;
+  if (version >= 2) {
+    const align = Math.floor(version / 7) + 2;
+    n -= (25 * align - 10) * align - 55;
+    if (version >= 7) n -= 36;
+  }
+  return n;
+}
+
+/** Data codewords of a version at a level. */
+export function dataCodewords(version, ecc) {
+  return (
+    Math.floor(rawDataModules(version) / 8) - ECC_PER_BLOCK[ecc][version] * BLOCKS[ecc][version]
+  );
+}
+
+// GF(256) with the QR polynomial x^8 + x^4 + x^3 + x^2 + 1.
+function gfMul(x, y) {
+  let z = 0;
+  for (let i = 7; i >= 0; i--) {
+    z = (z << 1) ^ ((z >>> 7) * 0x11d);
+    z ^= ((y >>> i) & 1) * x;
+  }
+  return z & 0xff;
+}
+
+function rsDivisor(degree) {
+  const result = new Array(degree).fill(0);
+  result[degree - 1] = 1;
+  let root = 1;
+  for (let i = 0; i < degree; i++) {
+    for (let j = 0; j < degree; j++) {
+      result[j] = gfMul(result[j], root);
+      if (j + 1 < degree) result[j] ^= result[j + 1];
+    }
+    root = gfMul(root, 0x02);
+  }
+  return result;
+}
+
+/** Reed-Solomon error-correction codewords for one block. */
+export function reedSolomon(data, degree) {
+  const divisor = rsDivisor(degree);
+  const result = new Array(degree).fill(0);
+  for (const b of data) {
+    const factor = b ^ result.shift();
+    result.push(0);
+    divisor.forEach((coef, i) => {
+      result[i] ^= gfMul(coef, factor);
+    });
+  }
+  return result;
+}
+
+function alignmentPositions(version) {
+  if (version === 1) return [];
+  const count = Math.floor(version / 7) + 2;
+  const size = version * 4 + 17;
+  const step = version === 32 ? 26 : Math.ceil((version * 4 + 4) / (count * 2 - 2)) * 2;
+  const out = [6];
+  for (let pos = size - 7; out.length < count; pos -= step) out.splice(1, 0, pos);
+  return out;
+}
+
+function bch(value, bits, poly, polyDegree) {
+  let rem = value << polyDegree;
+  for (let i = bits + polyDegree - 1; i >= polyDegree; i--) {
+    if ((rem >>> i) & 1) rem ^= poly << (i - polyDegree);
+  }
+  return (value << polyDegree) | rem;
+}
+
+/** The 15 format bits for a level and mask, already XORed with the fixed mask. */
+export function formatBits(ecc, mask) {
+  return bch((ECC_FORMAT_BITS[ecc] << 3) | mask, 5, 0x537, 10) ^ 0x5412;
+}
+
+function codewords(bytes, version, ecc) {
+  const capacityBits = dataCodewords(version, ecc) * 8;
+  const bits = [];
+  const put = (value, length) => {
+    for (let i = length - 1; i >= 0; i--) bits.push((value >>> i) & 1);
+  };
+  put(0b0100, 4);
+  put(bytes.length, version < 10 ? 8 : 16);
+  for (const b of bytes) put(b, 8);
+  put(0, Math.min(4, capacityBits - bits.length));
+  put(0, (8 - (bits.length % 8)) % 8);
+  for (let pad = 0xec; bits.length < capacityBits; pad ^= 0xec ^ 0x11) put(pad, 8);
+  const data = [];
+  for (let i = 0; i < bits.length; i += 8) {
+    data.push(bits.slice(i, i + 8).reduce((a, b) => (a << 1) | b, 0));
+  }
+
+  const blocks = BLOCKS[ecc][version];
+  const eccLen = ECC_PER_BLOCK[ecc][version];
+  const raw = Math.floor(rawDataModules(version) / 8);
+  const shortBlocks = blocks - (raw % blocks);
+  const shortLen = Math.floor(raw / blocks);
+  const groups = [];
+  for (let i = 0, k = 0; i < blocks; i++) {
+    const len = shortLen - eccLen + (i < shortBlocks ? 0 : 1);
+    const chunk = data.slice(k, k + len);
+    k += len;
+    groups.push({ data: chunk, ecc: reedSolomon(chunk, eccLen) });
+  }
+  const out = [];
+  for (let i = 0; i <= shortLen - eccLen; i++) {
+    for (const g of groups) if (i < g.data.length) out.push(g.data[i]);
+  }
+  for (let i = 0; i < eccLen; i++) for (const g of groups) out.push(g.ecc[i]);
+  return out;
+}
+
+const MASKS = [
+  (x, y) => (x + y) % 2 === 0,
+  (x, y) => y % 2 === 0,
+  (x) => x % 3 === 0,
+  (x, y) => (x + y) % 3 === 0,
+  (x, y) => (Math.floor(x / 3) + Math.floor(y / 2)) % 2 === 0,
+  (x, y) => ((x * y) % 2) + ((x * y) % 3) === 0,
+  (x, y) => (((x * y) % 2) + ((x * y) % 3)) % 2 === 0,
+  (x, y) => (((x + y) % 2) + ((x * y) % 3)) % 2 === 0,
+];
+
+function baseMatrix(version) {
+  const size = version * 4 + 17;
+  const dark = Array.from({ length: size }, () => new Array(size).fill(false));
+  const fixed = Array.from({ length: size }, () => new Array(size).fill(false));
+  const set = (x, y, v) => {
+    dark[y][x] = v;
+    fixed[y][x] = true;
+  };
+  for (let i = 0; i < size; i++) {
+    set(6, i, i % 2 === 0);
+    set(i, 6, i % 2 === 0);
+  }
+  const finder = (cx, cy) => {
+    for (let dy = -4; dy <= 4; dy++) {
+      for (let dx = -4; dx <= 4; dx++) {
+        const x = cx + dx;
+        const y = cy + dy;
+        if (x < 0 || y < 0 || x >= size || y >= size) continue;
+        const d = Math.max(Math.abs(dx), Math.abs(dy));
+        set(x, y, d !== 2 && d !== 4);
+      }
+    }
+  };
+  finder(3, 3);
+  finder(size - 4, 3);
+  finder(3, size - 4);
+  const align = alignmentPositions(version);
+  for (const ay of align) {
+    for (const ax of align) {
+      const corner =
+        (ax === 6 && ay === 6) || (ax === 6 && ay === size - 7) || (ax === size - 7 && ay === 6);
+      if (corner) continue;
+      for (let dy = -2; dy <= 2; dy++) {
+        for (let dx = -2; dx <= 2; dx++) {
+          set(ax + dx, ay + dy, Math.max(Math.abs(dx), Math.abs(dy)) !== 1);
+        }
+      }
+    }
+  }
+  for (let i = 0; i < 9; i++) {
+    fixed[8][i] = fixed[i][8] = true;
+    if (i < 8) fixed[8][size - 1 - i] = fixed[size - 1 - i][8] = true;
+  }
+  set(8, size - 8, true);
+  if (version >= 7) {
+    const v = bch(version, 6, 0x1f25, 12);
+    for (let i = 0; i < 18; i++) {
+      const bit = ((v >>> i) & 1) === 1;
+      const a = size - 11 + (i % 3);
+      const b = Math.floor(i / 3);
+      set(a, b, bit);
+      set(b, a, bit);
+    }
+  }
+  return { size, dark, fixed };
+}
+
+function drawFormat(dark, size, ecc, mask) {
+  const f = formatBits(ecc, mask);
+  const bit = (i) => ((f >>> i) & 1) === 1;
+  for (let i = 0; i <= 5; i++) dark[i][8] = bit(i);
+  dark[7][8] = bit(6);
+  dark[8][8] = bit(7);
+  dark[8][7] = bit(8);
+  for (let i = 9; i < 15; i++) dark[8][14 - i] = bit(i);
+  for (let i = 0; i < 8; i++) dark[8][size - 1 - i] = bit(i);
+  for (let i = 8; i < 15; i++) dark[size - 15 + i][8] = bit(i);
+  dark[size - 8][8] = true;
+}
+
+function placeData(dark, fixed, size, words) {
+  let i = 0;
+  const total = words.length * 8;
+  for (let right = size - 1; right >= 1; right -= 2) {
+    if (right === 6) right = 5;
+    for (let vert = 0; vert < size; vert++) {
+      for (let j = 0; j < 2; j++) {
+        const x = right - j;
+        const upward = ((right + 1) & 2) === 0;
+        const y = upward ? size - 1 - vert : vert;
+        if (fixed[y][x] || i >= total) continue;
+        dark[y][x] = ((words[i >>> 3] >>> (7 - (i & 7))) & 1) === 1;
+        i++;
+      }
+    }
+  }
+}
+
+/** The ISO penalty score of a finished matrix: runs, 2x2 blocks, finder-like patterns, balance. */
+export function penalty(dark) {
+  const size = dark.length;
+  let score = 0;
+  const lineScore = (get) => {
+    let s = 0;
+    for (let a = 0; a < size; a++) {
+      let run = 1;
+      for (let b = 1; b <= size; b++) {
+        if (b < size && get(a, b) === get(a, b - 1)) {
+          run++;
+        } else {
+          if (run >= 5) s += run - 2;
+          run = 1;
+        }
+      }
+      for (let b = 0; b + 10 < size; b++) {
+        const seq = Array.from({ length: 11 }, (_, k) => get(a, b + k));
+        const p1 = [1, 0, 1, 1, 1, 0, 1, 0, 0, 0, 0];
+        const p2 = [0, 0, 0, 0, 1, 0, 1, 1, 1, 0, 1];
+        if (seq.every((v, k) => v === Boolean(p1[k])) || seq.every((v, k) => v === Boolean(p2[k])))
+          s += 40;
+      }
+    }
+    return s;
+  };
+  score += lineScore((a, b) => dark[a][b]);
+  score += lineScore((a, b) => dark[b][a]);
+  let darkCount = 0;
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      if (dark[y][x]) darkCount++;
+      if (
+        y + 1 < size &&
+        x + 1 < size &&
+        dark[y][x] === dark[y][x + 1] &&
+        dark[y][x] === dark[y + 1][x] &&
+        dark[y][x] === dark[y + 1][x + 1]
+      )
+        score += 3;
+    }
+  }
+  const total = size * size;
+  score += (Math.ceil(Math.abs(darkCount * 20 - total * 10) / total) - 1) * 10;
+  return score;
+}
+
+/**
+ * Encode text as a QR code.
+ *
+ * @param {string} text
+ * @param {{ecc?: "L"|"M"|"Q"|"H", mask?: number}} [opts]  mask forces one of 0..7
+ * @returns {{version: number, size: number, ecc: string, mask: number, modules: boolean[][]}}
+ */
+export function encodeQr(text, { ecc = "M", mask } = {}) {
+  if (!ECC_PER_BLOCK[ecc]) throw new Error(`unknown error-correction level ${ecc}`);
+  const bytes = [...Buffer.from(String(text), "utf8")];
+  let version = 1;
+  const fits = (v) => 4 + (v < 10 ? 8 : 16) + bytes.length * 8 <= dataCodewords(v, ecc) * 8;
+  while (version <= 40 && !fits(version)) version++;
+  if (version > 40) throw new Error("text is too long for a QR code");
+  const words = codewords(bytes, version, ecc);
+  const { size, dark, fixed } = baseMatrix(version);
+  placeData(dark, fixed, size, words);
+  const candidates = Number.isInteger(mask) ? [mask] : [0, 1, 2, 3, 4, 5, 6, 7];
+  let best = null;
+  for (const m of candidates) {
+    const grid = dark.map((row, y) => row.map((v, x) => (fixed[y][x] ? v : v !== MASKS[m](x, y))));
+    drawFormat(grid, size, ecc, m);
+    const score = penalty(grid);
+    if (!best || score < best.score) best = { score, grid, mask: m };
+  }
+  return { version, size, ecc, mask: best.mask, modules: best.grid };
+}
+
+/** The code as one SVG path (one unit per module, a four-module quiet zone). */
+export function qrSvg(qr, { scale = 6 } = {}) {
+  const q = 4;
+  const n = qr.size + q * 2;
+  let d = "";
+  qr.modules.forEach((row, y) =>
+    row.forEach((on, x) => {
+      if (on) d += `M${x + q} ${y + q}h1v1h-1z`;
+    }),
+  );
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${n} ${n}" width="${n * scale}" ` +
+    `height="${n * scale}" shape-rendering="crispEdges"><rect width="${n}" height="${n}" ` +
+    `fill="#fff"/><path d="${d}" fill="#000"/></svg>`
+  );
+}

package/pipeline/lib/repo-hygiene.sh

@@ -41,6 +41,7 @@ MA_HYGIENE_END='# <<< multi-agent pipeline (managed) <<<'
 ma_hygiene_patterns() {
   cat <<'PATTERNS'
 .worktrees/
+.DerivedData/
 .pipeline/
 .multi-agent/
 triage-output.json

package/pipeline/lib/run-completion.mjs

@@ -11,6 +11,8 @@
  *      `commit.sha`, a `pr`, a runner `publish` record, a `projects[].commit`
  *      or `projects[].pr`, or an explicit no-commit decision
  *      (`phases["4"].status: "skipped"` with a `notes` reason).
+ *      A repo commit counts as delivered once its push outcome is recorded
+ *      (`projects[].pushStatus`) or it has a pull request.
  *   3. The plan's coverage was judged, unless the mode declares
  *      `commits: false`: a `plan-coverage` entry in `gates[]` with a passing
  *      verdict. plan-coverage-gate.mjs records it attended and unattended.
@@ -101,6 +103,16 @@ export function phase4Evidence(state) {
   return Boolean(p4 && p4.status === "skipped" && typeof p4.notes === "string" && p4.notes.trim());
 }
 
+const PUSH_RECORDED = new Set(["pushed", "rebase-pushed", "skipped"]);
+
+/** Repos whose commit has neither a recorded push outcome nor a pull request. */
+export function unpushedRepos(state) {
+  const projects = Array.isArray(state.projects) ? state.projects : [];
+  return projects
+    .filter((p) => p && hasSha(p.commit) && !hasPr(p.pr) && !PUSH_RECORDED.has(p.pushStatus))
+    .map((p, i) => p.project || p.name || `#${i + 1}`);
+}
+
 /** True when a passing plan-coverage verdict is in the gate ledger. */
 export function planCoverageRecorded(state) {
   const gates = Array.isArray(state.gates) ? state.gates : [];
@@ -138,6 +150,11 @@ export function completionGaps(state) {
         'no Phase 4 evidence: record commit.sha (or pr), or the no-commit decision as phases["4"] = {status: "skipped", notes: "<why>"}',
       );
     }
+    for (const name of unpushedRepos(state)) {
+      gaps.push(
+        `repo ${name} has a commit with no recorded push: set projects[].pushStatus to "pushed" or "rebase-pushed", or "skipped" when the push is left to the user (Phase 4 push policy)`,
+      );
+    }
     if (!planCoverageRecorded(state)) {
       gaps.push(
         "no passing plan-coverage verdict in gates[]: run plan-coverage-gate.mjs --state <agent-state.json> (Phase 4 Step 0a)",

package/pipeline/multi-agent-refs/channels/issue-comment.md

@@ -132,7 +132,7 @@ gh issue comment "$ISSUE_NUMBER" --repo "$ORG/$REPO" --body-file /tmp/channels-$
 bash $HOME/.claude/scripts/update-issue-progress.sh "$TASK_ID"
 ```
 
-If either call fails, the channel adapter MUST NOT mark the issue channel as completed in `agent-state.json`. The user sees a clear error and can retry.
+If either call fails, the channel adapter MUST NOT mark the issue channel as completed in `agent-state.json`. The user sees a clear error and can retry. The order is enforced: `update-issue-progress.sh` exits 5 and leaves the body unchanged unless the authenticated account has a comment on the issue since `state.startedAt` that carries the `Ref: #N` footer.
 
 ## Drift detection
 

package/pipeline/multi-agent-refs/features/office-remote-protocol.md

@@ -0,0 +1,166 @@
+# Office remote protocol
+
+<!-- toc -->
+- [Parts and trust](#parts-and-trust)
+- [Account](#account)
+- [Pairing](#pairing)
+- [Transport](#transport)
+- [Passkey tiers](#passkey-tiers)
+- [Audit](#audit)
+- [Decisions](#decisions)
+- [To verify on a real phone](#to-verify-on-a-real-phone)
+<!-- /toc -->
+
+How a phone reaches the phone routes of the local contract server through a
+relay on the user's site, without the machine opening a port and without the
+relay or the site being able to read a payload or act on their own.
+
+The request layer exists and is not changed here: every phone request is signed
+with the device's Ed25519 key (`MA-PHONE-SIG-1`), and `_phone-auth.mjs` checks
+the device, the window, the nonce, the scopes and writes the audit line
+(`phone-api.md`). This document adds what leaving the machine requires: an
+end-to-end layer around those requests, the relay that carries it, pairing that
+enrols the device through the existing registry, and a passkey on top of the
+device signature for the routes that change something.
+
+## Parts and trust
+
+| Part | Runs | Holds | Trusted for |
+|---|---|---|---|
+| Phone page | the phone browser, on the site origin (behind the owner session) | the device signing key and the session key pair (non-extractable WebCrypto), a passkey | showing data, asking the user, signing |
+| Site + relay | the user's site (serverless functions + database) | the owner's account, pairing records, ciphertext queues | delivering ciphertext, nothing else |
+| Machine client | the user's machine, started with the office | the machine key pair, the audit of remote frames | decrypting, checking the passkey tier, forwarding to the local server |
+| Local server | the user's machine, 127.0.0.1 only | the device registry, nonces, audit | verifying the device signature and executing phone routes, as today |
+
+The relay and its database are treated as compromised: they can drop, delay,
+replay and reorder frames. None of that lets them read a frame, forge a device
+signature or pass the passkey check. The phone page itself is the trust anchor
+on the phone side, as for any web app holding keys: a site that serves a
+modified page can act as the phone. The page therefore loads no third-party
+script, runs under a strict CSP and keeps its keys non-extractable, and the
+machine still applies every check of its own (tiers, routes, counters).
+
+## Account
+
+The first release serves the owner's account only and reuses the site's
+existing owner session rather than adding a second login: the phone page and
+every phone relay route require it, and state-changing routes also require a
+same-origin request. The session only lets the phone use the relay for its
+own pairings; it never authorizes an action on the machine, which still
+checks the device signature, the passkey tier and the route itself. Invited
+accounts are a later step.
+
+## Pairing
+
+`office-pair.mjs` runs the machine side; every subcommand refuses an
+unattended run. The user runs it in their own terminal (`! node
+~/.claude/scripts/office-pair.mjs start`), so nothing it shows lands in a
+transcript.
+
+1. `start [--relay <origin>]` creates the machine key pair (P-256) on first
+   use and a relay token (256 bits) kept in `<phone dir>/remote.json` (0600),
+   a pairing id and a one-time secret (128 bits, valid 10 minutes). The relay
+   origin comes from `prefs.global.office.remote.relayUrl` or the flag, never
+   from the code; it is https, or http on the loopback. The relay receives the
+   pairing id, the machine public key, the expiry and the SHA-256 of the relay
+   token, never the token itself.
+2. The QR code is drawn by the dependency-free encoder in `lib/qr-code.mjs`
+   into a 0600 page (`default-src 'none'`) in a 0700 directory and opened in
+   the local browser; the secret is never printed. It holds
+   `<origin>/office/pair#p=<pairing id>&s=<secret>&k=<machine public key>`.
+   A browser never sends the fragment to a server, so the relay neither sees
+   the secret nor can swap the machine key.
+3. The phone, signed in, scans it, creates its Ed25519 device key and its P-256
+   session key, registers a passkey (WebAuthn `create`, user verification
+   required) and sends, sealed with a key that mixes the ECDH secret with the
+   pairing secret: the device name and public key, and the passkey credential
+   id, public key (`getPublicKey()`, SPKI), rp id and origin.
+4. `wait` polls the relay with the token, opens the message, refuses a passkey
+   whose origin is not the relay origin or whose rp id is not its host, and
+   prints the six-digit code derived from both public keys and a fingerprint
+   of the machine key. The phone shows the same code and fingerprint, and
+   accepts the pairing only after its user confirms on the phone that both
+   match, so a link someone else registered cannot pair the phone with their
+   machine.
+5. `confirm <code>` takes the code as the phone shows it. A mismatch drops the
+   pairing (one attempt). A match enrols the device with
+   `phone-devices.mjs add` (scopes `read,answer`; `launch` stays a separate
+   local switch), stores the session key and passkey beside it, and tells the
+   relay to start delivering for the pairing. That call carries the first
+   machine-to-phone frame (counter 1), sealed with the pairing's keys, holding
+   the device id the phone signs its requests with; the relay cannot alter it.
+6. Revoke: `phone-devices.mjs revoke <id>` on the machine also drops the
+   device's remote keys; the site can stop delivering for a pairing. Either
+   alone ends control.
+
+## Transport
+
+- The machine client polls the relay over HTTPS (long poll, 25 s) and posts
+  responses. No inbound port, no tunnel, no funnel.
+- A frame is `{method, target, headers, body}` (request) or
+  `{status, headers, body}` (response), as `phone-api.md` specifies, sealed
+  with AES-256-GCM. The keys come from ECDH between the phone session key and
+  the machine key, through HKDF-SHA-256 with the pairing id as salt, one key
+  per direction; the nonce is a per-direction counter, and a frame whose
+  counter does not exceed the last one accepted is dropped.
+- The relay stores `{pairingId, direction, counter, ciphertext, expiresAt}` in
+  a table only the service role reaches, and deletes a row on delivery or
+  after 10 minutes.
+- The machine client takes a target only in the canonical form the local
+  server routes on (no encoded dot segment, backslash or fragment), so the
+  tier and the route prefix are judged on the path the server executes. Only
+  one client runs at a time (a lock file), and each poll writes its counters
+  onto the config as it is on disk, so a revoke made meanwhile is kept.
+- The machine client forwards only targets under `/v1/phone/`, never adds an
+  `Authorization` header, and rewrites `Host` to the loopback address; the
+  local server's own checks then apply unchanged.
+- Remote is off by default: the client runs only while the office is on and
+  a device is paired; `office-off` stops it.
+
+## Passkey tiers
+
+The device signature proves which phone sent a request; the passkey proves the
+user was holding it. Each phone route carries a tier from the route table:
+
+| Tier | Phone routes | Passkey |
+|---|---|---|
+| read | `GET /v1/phone/runs`, `GET /v1/phone/runs/{id}` | one at session open; the session locks after 5 minutes idle |
+| low | `POST /v1/phone/runs/{id}/answer`, a canned steer | within 2 minutes of the last passkey (configurable down to every time) |
+| high | `POST /v1/phone/launch` and any later route that changes code or writes to a host | every time, bound to the request |
+
+For a passkey-bound request the phone sends `X-MA-Passkey` with a WebAuthn
+assertion whose challenge is SHA-256 of the request's canonical signed text.
+The machine verifies, before the request reaches the local server: the rp id
+hash and origin match the paired ones, the user verified flag is set, the
+signature verifies with the paired credential key, and the sign count (when the
+authenticator keeps one) has grown. Steering from the phone is a canned
+template chosen by id and expanded on the machine; free-text steering, widening
+actions (autopilot on, stack, routine delete, host permissions) and merges stay
+desktop routes.
+
+## Audit
+
+The local server keeps its per-request audit as today. The machine client adds
+`<phone dir>/remote-frames.jsonl` (0600): time, device, counter,
+target path without query, tier, passkey verdict and the reason of a drop.
+Never a body, a header value or a signature.
+
+## Decisions
+
+1. **The machine client ships in the public pipeline**, inert until
+   `office-pair` pairs a device. The relay URL comes from prefs or the pairing
+   QR, never from the code.
+2. **Steering from the phone takes canned templates only**, chosen by id and
+   expanded on the machine.
+3. **The first release serves the owner's account only**; invites follow as a
+   separate step.
+4. **The relay queue is a short-lived table in the site's database**: ciphertext
+   only, deleted on delivery or after 10 minutes, service role only.
+
+## To verify on a real phone
+
+WebCrypto Ed25519 and non-extractable P-256 keys in the phone's browser,
+`getPublicKey()` on the passkey registration response, and the long-poll
+interval against the site's function time limit. The design falls back to
+P-256 ECDSA for the device key if Ed25519 is missing, which `_phone-auth.mjs`
+would then accept as a second key type.

package/pipeline/multi-agent-refs/features/office-threat-model.md

@@ -66,7 +66,7 @@ not mitigated here.
 | T20 | A learned statement carrying a secret or a machine path to the page | `GET /v1/memory` returns counts, the code graph's age and size, and the five newest learning statements per repository, each passed through the transcript redactor (provider credential rules, paths and addresses) and cut to 120 characters. Repository names are matched against a safe character set before any file is opened. Read only; `local-only` | `office-routes.test.mjs` "GET /v1/memory reports every shelf, redacted" |
 | T21 | Machine details through the resource panel | `GET /v1/system` returns numbers only (cores, load, memory, free disk, process counts, log folder size) and two fixed warnings; no path, process argument, user or host name. The schema allows nothing else. The measurement runs as child processes off the event loop, concurrent requests share one measurement, and the log folder size is reused for a minute. Readable from a phone, since it names nothing | `office-routes.test.mjs` "GET /v1/system returns numbers only: no path, user or host name" |
 | T22 | Old run logs deleted wider than asked, or a live run's log removed | `POST /v1/prune-logs` takes only an age from a fixed set (7, 30 or 90 days) and runs `prune-logs.sh`, the script `/multi-agent:prune-logs` runs: the dry run is the preview; the confirmed step lists the folders again, refuses with `changed` when they differ, and then prunes only the previewed list through `--only-from`, under a token bound to that age and list. The script never touches the audit trail, the metrics corpus or the task counters, refuses a log root that is `/`, the home folder or a git checkout, and spares a folder written in the last minutes and a run that can still be resumed. Tagged `local-only`/`high` | `office-routes.test.mjs` "POST /v1/prune-logs previews, then prunes only on the token" |
-| T23 | Pull request listing exposing a token, or the native task mirror writing into another run | Each GitHub account gh is logged in to is asked with `gh auth token` for that host and login; the token travels in `GH_TOKEN` (and `GH_ENTERPRISE_TOKEN` for an Enterprise Server host) for the child process only, never on a command line, in a response or a log. Bitbucket Server is read over https only (a plain-http host is refused unless it is the loopback), redirects are not followed, and the token, read from the credential store with a deadline, travels in the `Authorization` header only; an unreachable host is a reason on that source, not a failure of the list. A redacted answer drops URLs and logins, numbering the accounts instead. The task-mirror hook (PostToolUse on TaskCreate and TaskUpdate) writes only into the run whose recorded session is the calling session, skips phase tiles, never prints, and exits 0 on any input it cannot read | `work-items-prs.test.mjs`, `task-mirror.test.mjs` |
+| T23 | Pull request listing exposing a token, or the native task mirror writing into another run | Each GitHub account gh is logged in to is asked with `gh auth token` for that host and login; the token travels in `GH_TOKEN` (and `GH_ENTERPRISE_TOKEN` for an Enterprise Server host) for the child process only, never on a command line, in a response or a log. Bitbucket Server is read over https only (a plain-http host is refused unless it is the loopback), redirects are not followed, and the token, read from the credential store with a deadline, travels in the `Authorization` header only; an unreachable host is a reason on that source, not a failure of the list. `GET /v1/prs/reach` (local-only) asks gh for the changed file paths of at most 20 GitHub pull requests, three at a time, each with its account's token in the environment; it asks nothing for a repository whose name is not `owner/repo` or that has no graph under `~/.claude/knowledge/<repo name>/`. The paths serve only as keys into the local graph: nothing is read from disk by them and none is returned, only counts. The graph is parsed in a child process, so no other route waits behind it. A redacted answer drops URLs and logins, numbering the accounts instead. The task-mirror hook (PostToolUse on TaskCreate and TaskUpdate) writes only into the run whose recorded session is the calling session, skips phase tiles, never prints, and exits 0 on any input it cannot read | `work-items-prs.test.mjs`, `task-mirror.test.mjs`, `pr-reach.test.mjs`, `office-work.test.mjs` "GET /v1/prs/reach says which pull requests have no graph to measure against" |
 | T24 | The panel changing a preference wider than the terminal would, or posting addresses to a phone | `POST /v1/settings` takes one of three settings and one of its two values, previews the change and runs, under a token bound to that setting and value, what `/multi-agent:language`, `/multi-agent:model` or `/multi-agent:route-on`/`route-off` runs; route on passes the saved strategy back so only the switch changes, nothing the panel sends can add rules or a free provider, and two changes never run at once. Tagged `local-only`/`high`. Report links: `channelResults` URLs must be https, travel only in the run record's `channelUrls` (local, dropped from a redacted answer) and are shown as text, never followed | `office-routes.test.mjs` "POST /v1/settings changes a switch only on the token, through its script", `runs-index.test.mjs` |
 
 ## Residual risks

package/pipeline/multi-agent-refs/features/scope-check.md

@@ -29,7 +29,22 @@ git -C "$WORKTREE" diff --name-only "origin/$BASE_BRANCH"...HEAD \
   | node $HOME/.claude/scripts/scope-check-gate.mjs --check "$WORKTREE/.pipeline/scope-check.json" --diff-files -
 ```
 
-Output `{ok, justified, unjustified[], unlisted[], notDone}`, plus `formatOnly[]` with `--patch` / `--patch-range` (`patchError` when the diff could not be read). With `--patch <unified diff>` (or `--repo <dir> --patch-range <a>...<b>`, which reads that diff itself), `formatOnly[]` lists hunks whose removed and added lines differ only in whitespace: a reformat of lines the task did not need to touch. It is reported, never fatal, and reviewers see it in `<scope-self-check>`. Exit 1 lists `unjustified[]` (in the diff, no reason or an empty one); `unlisted[]` (in the record, not in the diff) is reported and never fatal. Complete the record once and re-run. A second exit 1 does not block: log `dev.scope_check=incomplete unjustified=<n>` and hand off; Phase 4 receives the gate output inside `<scope-self-check>`, so reviewers see which files arrived without a stated reason. `--advisory` (used by Phase 4) always exits 0. Progress line: `    → checking scope self-check ({n} files, {m} not done)`.
+Output `{ok, justified, unjustified[], unlisted[], notDone}`, plus `formatOnly[]` with `--patch` / `--patch-range` (`patchError` when the diff could not be read). With `--patch <unified diff>` (or `--repo <dir> --patch-range <a>...<b>`, which reads that diff itself), `formatOnly[]` lists hunks whose removed and added lines differ only in whitespace: a reformat of lines the task did not need to touch. It is reported, never fatal, and reviewers see it in `<scope-self-check>`. On a rework pass, `--rejected <triage-output.json> --repo <dir> --rework-base <rev>` (the two come together) adds `rejectedTouched[]` (`rejectedError` when unreadable): each finding triage rejected whose line a hunk of `git diff <rework base>` against the working tree changed, read on the hunk's old side within two lines. Phase 2 acts on accepted findings only, so such a hunk is a fix triage ruled out; it is reported, never fatal. Exit 1 lists `unjustified[]` (in the diff, no reason or an empty one); `unlisted[]` (in the record, not in the diff) is reported and never fatal. Complete the record once and re-run. A second exit 1 does not block: log `dev.scope_check=incomplete unjustified=<n>` and hand off; Phase 4 receives the gate output inside `<scope-self-check>`, so reviewers see which files arrived without a stated reason. `--advisory` (used by Phase 4) always exits 0. Progress line: `    → checking scope self-check ({n} files, {m} not done)`.
+
+## Rework pass
+
+Rejected findings carry the line numbers of the tree the review read, and every round rewrites `triage-output.json`, so a rework is compared against that round's own base.
+
+1. Before the first rework edit, record the base: `node $HOME/.claude/scripts/rework-base.mjs record --worktree "$WORKTREE" --iteration "$(jq '.reviewIterations | length' "$STATE_FILE")"`. One file per round, `.pipeline/rework-base-<N>`; a resumed re-entry of the same round keeps the base it started from.
+2. In Step 3.7, after the normal gate:
+
+```bash
+REWORK_BASE=$(node $HOME/.claude/scripts/rework-base.mjs get --worktree "$WORKTREE" --iteration "$(jq '.reviewIterations | length' "$STATE_FILE")")
+node $HOME/.claude/scripts/scope-check-gate.mjs --check "$WORKTREE/.pipeline/scope-check.json" --diff-files /dev/null --advisory \
+  --rejected "$WORKTREE/triage-output.json" --repo "$WORKTREE" --rework-base "$REWORK_BASE"
+```
+
+Each `rejectedTouched[]` entry is an edit to lines triage ruled out: revert that hunk unless an accepted finding needs it, and say which in the record's reason. Log `dev.rework_rejected_touch=<n>`.
 
 ## Known limits in the code
 

package/pipeline/multi-agent-refs/features/verify-by-test.md

@@ -21,6 +21,16 @@
 
 Downgrades go to `deferred`, never `rejected`: triage judged the issue real, and deferred items surface in the Phase 5 report for a human eye.
 
+## Repeat runs
+
+Phase 2's stability rule keeps each run of the new and changed tests as `.pipeline/repeat-<k>.junit.xml` (k = 1..N) and judges them together:
+
+```bash
+node $HOME/.claude/scripts/test-stability-gate.mjs --dir "$WORKTREE/.pipeline" --expect N
+```
+
+Exit 1 means a missing run, a flake (`flaky[]`: outcomes that differ across runs) or a test that failed every time; the step is not GREEN. A runner that writes no JUnit XML (xcodebuild) has each run exported with `xcrun xcresulttool` first, or logs `test.stability=unverifiable` and says so in the Phase 5 report.
+
 ## Red-test handoff to Phase 3
 
 `state.reviewIterations[-1].verifyByTest = { attempted, confirmed, downgraded, inconclusive, redTests: [{file, testRef, issue}] }`. On the Phase 3 re-entry, each `redTests[]` entry IS the RED step of the rework TDD cycle for its finding: the reflection prompt instructs "a failing repro test already exists at <testRef>; make it green; do not delete or weaken it." The dev agent must not write a duplicate failing test for those findings.

package/pipeline/multi-agent-refs/keychain.md

@@ -1,5 +1,12 @@
 ## Keychain Token Registry
 
+<!-- toc -->
+- [Keychain Token Registry](#keychain-token-registry)
+- [Rule 1  -  Never prompt for a token *value* mid-run](#rule-1---never-prompt-for-a-token-value-mid-run)
+- [Rule 2  -  MUST: never ask the user for what a mapped credential can fetch (BLOCKING)](#rule-2---must-never-ask-the-user-for-what-a-mapped-credential-can-fetch-blocking)
+- [Credential store mechanics](#credential-store-mechanics)
+<!-- /toc -->
+
 > **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
 
 Tokens live in the macOS Keychain. Key names are resolved via **preferences mapping**  -  never hardcoded.