@mmerterden/multi-agent-pipeline 20.33.0 → 20.35.0

package/pipeline/contract/types/index.d.ts

@@ -1,8 +1,8 @@
 // Generated by pipeline/contract/build.mjs from pipeline/schemas/*.schema.json.
 // Do not edit: change the schema and run `node pipeline/contract/build.mjs --write`.
 
-export type ContractVersion = "1.6.0";
-export type SurfaceId = "runs" | "run" | "commands" | "questions" | "issues" | "worktrees" | "launch-spec" | "repos" | "repo-add" | "repo-remove" | "launch" | "answer" | "run-log" | "resume" | "kill" | "gc" | "autopilot" | "autopilot-off" | "phone-runs" | "phone-run" | "phone-answer" | "phone-launch" | "autopilot-on" | "steer" | "activity" | "activity-stream" | "agent-chat" | "routines" | "routine-delete" | "jobs" | "job-start" | "stack" | "stack-set" | "ledger" | "system" | "prune-logs" | "settings" | "settings-set" | "credentials" | "memory" | "run-results" | "run-evidence" | "review-verdict" | "issue-maturity" | "prs" | "tools" | "tool-call" | "service-confluence" | "service-crashlytics" | "service-figma" | "permissions";
+export type ContractVersion = "1.7.0";
+export type SurfaceId = "runs" | "run" | "commands" | "questions" | "issues" | "worktrees" | "launch-spec" | "repos" | "repo-add" | "repo-remove" | "launch" | "answer" | "run-log" | "resume" | "kill" | "gc" | "autopilot" | "autopilot-off" | "phone-runs" | "phone-run" | "phone-answer" | "phone-launch" | "autopilot-on" | "steer" | "activity" | "activity-stream" | "agent-chat" | "routines" | "routine-delete" | "jobs" | "job-start" | "stack" | "stack-set" | "ledger" | "system" | "prune-logs" | "settings" | "settings-set" | "credentials" | "memory" | "run-results" | "run-evidence" | "review-verdict" | "issue-maturity" | "prs" | "prs-reach" | "tools" | "tool-call" | "service-confluence" | "service-crashlytics" | "service-figma" | "permissions";
 
 /** What `runs-index.mjs --json` prints: every run under the log root and the unattended log root (one record per task id), grouped per status/SKILL.md 3b. Fields are only ever added - a decoder ignores keys it does not know. `--redact` drops every x-sensitivity local field (and `logsRoot`) and scrubs the free text in the title, `now`, sub-step names, task subjects and the pending question. */
 export interface RunsIndex {
@@ -1202,6 +1202,28 @@ export interface Prs {
   }>;
 }
 
+/** What GET /v1/prs/reach returns (`work-items.mjs reach`): for each open GitHub pull request (at most 20), how many files in the repository's own code graph depend on what it changes, widest first. Changed paths serve only as keys into the local graph and are never returned. A pull request that cannot be measured carries reach null and its reason. */
+export interface PrReach {
+  contractVersion: string;
+  /** Reverse-dependency depth the count was taken at. */
+  depth: number;
+  items: Array<{
+    source: "github" | "bitbucket";
+    repo: string;
+    number: number;
+    /** The knowledge-folder project whose graph answered, or null. */
+    project: string | null;
+    /** Files the pull request changes. */
+    changed?: number;
+    /** Of those, files the graph knows. */
+    inGraph?: number;
+    /** Files that depend on the changed ones, within depth. Null when not measured. */
+    reach: number | null;
+    /** Why reach is null. */
+    reason?: string;
+  }>;
+}
+
 /** The body of POST /v1/runs/{id}/review-verdict: empty for the preview, confirmToken to post. The verdict is never chosen by the request; it follows from the review's recorded findings. */
 export interface ReviewVerdictRequest {
   contractVersion: string;

package/pipeline/lib/json-file-lock.mjs

@@ -18,9 +18,12 @@
 
 import {
   chmodSync,
+  closeSync,
+  fstatSync,
   linkSync,
   lstatSync,
   mkdirSync,
+  openSync,
   readFileSync,
   readlinkSync,
   realpathSync,
@@ -47,22 +50,70 @@ export class FileLockTimeout extends Error {
 
 const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 
-function staleIdentity(lockPath, staleMs) {
-  let pid;
-  let st;
+/**
+ * The PID inside a lock file and that file's identity, read through one
+ * descriptor. Read by path twice, the PID can come from a lock that was
+ * released in between and the identity from the one acquired after it, which
+ * makes a live lock look like a dead holder's.
+ *
+ * @param {string} lockPath
+ * @returns {{pid: number, ino: number, mtimeMs: number} | null}
+ */
+export function readLockOwner(lockPath) {
+  let fd;
   try {
-    pid = parseInt(readFileSync(lockPath, "utf8").trim(), 10);
-    st = statSync(lockPath);
+    fd = openSync(lockPath, "r");
+    const st = fstatSync(fd);
+    const pid = parseInt(readFileSync(fd, "utf8").trim(), 10);
+    return { pid, ino: st.ino, mtimeMs: st.mtimeMs };
   } catch {
     return null;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
   }
-  const age = Date.now() - st.mtimeMs;
-  if (!Number.isInteger(pid) || pid <= 0) return age > staleMs ? st : null;
+}
+
+/**
+ * Remove the lock judged stale, and only that one. The lock is first moved to
+ * a name private to this process, so the file examined is the file removed; a
+ * live lock that took its place in the meantime is linked back as the same
+ * file, which its holder's release recognises by inode.
+ *
+ * @param {string} lockPath
+ * @param {{ino: number, mtimeMs: number}} judged
+ * @returns {boolean} true when the stale lock was removed
+ */
+export function reapLock(lockPath, judged) {
+  const reap = `${lockPath}.${process.pid}.reap`;
   try {
-    process.kill(pid, 0);
+    renameSync(lockPath, reap);
+  } catch {
+    return false;
+  }
+  const st = statSync(reap);
+  if (st.ino === judged.ino && st.mtimeMs === judged.mtimeMs) {
+    unlinkSync(reap);
+    return true;
+  }
+  try {
+    linkSync(reap, lockPath);
+  } catch {
+    /* a new holder already has the path; the displaced one keeps its inode */
+  }
+  unlinkSync(reap);
+  return false;
+}
+
+function staleIdentity(lockPath, staleMs) {
+  const owner = readLockOwner(lockPath);
+  if (!owner) return null;
+  const age = Date.now() - owner.mtimeMs;
+  if (!Number.isInteger(owner.pid) || owner.pid <= 0) return age > staleMs ? owner : null;
+  try {
+    process.kill(owner.pid, 0);
     return null;
   } catch (err) {
-    return err.code === "ESRCH" ? st : null;
+    return err.code === "ESRCH" ? owner : null;
   }
 }
 
@@ -82,12 +133,7 @@ function acquire(lockPath, timeoutMs, staleMs) {
     }
     const stale = staleIdentity(lockPath, staleMs);
     if (stale) {
-      try {
-        const now = statSync(lockPath);
-        if (now.ino === stale.ino && now.mtimeMs === stale.mtimeMs) unlinkSync(lockPath);
-      } catch {
-        /* gone already */
-      }
+      reapLock(lockPath, stale);
       continue;
     }
     if (Date.now() >= deadline) throw new FileLockTimeout(lockPath, timeoutMs);

package/pipeline/lib/office-remote.mjs

@@ -0,0 +1,228 @@
+/**
+ * office-remote.mjs  -  the machine side of the office remote layer
+ * (features/office-remote-protocol.md).
+ *
+ * - Keys: P-256 ECDH between the machine key and the phone's session key,
+ *   through HKDF-SHA-256 with the pairing id as salt, into one AES-256 key per
+ *   direction.
+ * - Frames: AES-256-GCM; the 12-byte nonce is a 4-byte direction tag and an
+ *   8-byte counter, so a frame opens only in its own direction and a counter
+ *   that does not exceed the last accepted one is refused as a replay.
+ * - Pairing: the phone's first message is sealed with a key that also mixes in
+ *   the one-time pairing secret from the QR code, so the relay cannot open it
+ *   even holding both public keys.
+ * - Comparison code: six digits from both public keys, the same on either end.
+ * - Passkey: a WebAuthn assertion checked against the paired credential key,
+ *   rp id, origin, the request-bound challenge, user verification and the sign
+ *   count.
+ *
+ * Zero runtime dependencies (ADR-0004): node:crypto only.
+ *
+ * @module pipeline/lib/office-remote
+ */
+
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  diffieHellman,
+  generateKeyPairSync,
+  hkdfSync,
+  timingSafeEqual,
+  verify,
+} from "node:crypto";
+
+const DIRECTIONS = { "phone-to-machine": 1, "machine-to-phone": 2 };
+const INFO = "ma-office v1 ";
+const MAX_COUNTER = 2 ** 48;
+
+const b64u = (b) => Buffer.from(b).toString("base64url");
+const fromB64u = (s) => Buffer.from(String(s || ""), "base64url");
+const sha256 = (b) => createHash("sha256").update(b).digest();
+
+/** A new machine key pair: PKCS#8 PEM private key, base64url SPKI public key. */
+export function createMachineKeys() {
+  const { privateKey, publicKey } = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+  return {
+    privatePem: privateKey.export({ type: "pkcs8", format: "pem" }),
+    publicKey: b64u(publicKey.export({ type: "spki", format: "der" })),
+  };
+}
+
+function shared(privatePem, peerPublic) {
+  return diffieHellman({
+    privateKey: createPrivateKey(privatePem),
+    publicKey: createPublicKey({ key: fromB64u(peerPublic), format: "der", type: "spki" }),
+  });
+}
+
+const derive = (ikm, pairingId, label) =>
+  Buffer.from(
+    hkdfSync("sha256", ikm, Buffer.from(String(pairingId)), Buffer.from(INFO + label), 32),
+  );
+
+/**
+ * The two AES keys of a pairing, from this end's point of view.
+ *
+ * @param {{privatePem: string, peerPublic: string, pairingId: string, role: "machine"|"phone"}} p
+ * @returns {{send: Buffer, recv: Buffer}}
+ */
+export function directionKeys({ privatePem, peerPublic, pairingId, role }) {
+  const ikm = shared(privatePem, peerPublic);
+  const p2m = derive(ikm, pairingId, "phone-to-machine");
+  const m2p = derive(ikm, pairingId, "machine-to-phone");
+  return role === "machine" ? { send: m2p, recv: p2m } : { send: p2m, recv: m2p };
+}
+
+function nonceFor(direction, counter) {
+  const tag = DIRECTIONS[direction];
+  if (!tag) throw new Error(`unknown direction ${direction}`);
+  if (!Number.isSafeInteger(counter) || counter < 1 || counter >= MAX_COUNTER) {
+    throw new Error("counter out of range");
+  }
+  const iv = Buffer.alloc(12);
+  iv.writeUInt32BE(tag, 0);
+  iv.writeUIntBE(counter, 6, 6);
+  return iv;
+}
+
+/** Seal a JSON value as one frame. */
+export function sealFrame(key, counter, direction, value) {
+  const iv = nonceFor(direction, counter);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  cipher.setAAD(Buffer.from(direction));
+  const body = Buffer.concat([cipher.update(JSON.stringify(value), "utf8"), cipher.final()]);
+  return { counter, ct: b64u(Buffer.concat([body, cipher.getAuthTag()])) };
+}
+
+/**
+ * Open one frame. Refuses a counter that does not exceed `lastCounter`, a
+ * frame for the other direction and any altered byte.
+ *
+ * @returns {{ok: true, value: unknown, counter: number} | {ok: false, reason: string}}
+ */
+export function openFrame(key, frame, direction, lastCounter) {
+  const counter = Number(frame?.counter);
+  if (!Number.isSafeInteger(counter) || counter <= Number(lastCounter || 0)) {
+    return { ok: false, reason: "counter did not grow (replay or reorder)" };
+  }
+  let iv;
+  try {
+    iv = nonceFor(direction, counter);
+  } catch (err) {
+    return { ok: false, reason: err.message };
+  }
+  const raw = fromB64u(frame?.ct);
+  if (raw.length < 17) return { ok: false, reason: "frame too short" };
+  try {
+    const decipher = createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAAD(Buffer.from(direction));
+    decipher.setAuthTag(raw.subarray(raw.length - 16));
+    const text = Buffer.concat([
+      decipher.update(raw.subarray(0, raw.length - 16)),
+      decipher.final(),
+    ]);
+    return { ok: true, value: JSON.parse(text.toString("utf8")), counter };
+  } catch {
+    return { ok: false, reason: "frame did not authenticate" };
+  }
+}
+
+function pairingKey({ privatePem, peerPublic, secret, pairingId }) {
+  const ikm = Buffer.concat([shared(privatePem, peerPublic), fromB64u(secret)]);
+  return derive(ikm, pairingId, "pairing");
+}
+
+/** Seal the phone's pairing message (counter 1, phone to machine). */
+export function sealPairing({ privatePem, peerPublic, secret, pairingId, value }) {
+  return sealFrame(
+    pairingKey({ privatePem, peerPublic, secret, pairingId }),
+    1,
+    "phone-to-machine",
+    value,
+  );
+}
+
+/** Open the phone's pairing message with the machine key and the pairing secret. */
+export function openPairing({ privatePem, peerPublic, secret, pairingId, sealed }) {
+  try {
+    const key = pairingKey({ privatePem, peerPublic, secret, pairingId });
+    const r = openFrame(key, sealed, "phone-to-machine", 0);
+    return r.ok ? { ok: true, value: r.value } : r;
+  } catch {
+    return { ok: false, reason: "pairing message could not be opened" };
+  }
+}
+
+/** Six digits from two public keys, independent of their order. */
+export function comparisonCode(a, b) {
+  const [x, y] = [String(a), String(b)].sort();
+  const n = sha256(Buffer.from(`${INFO}compare\n${x}\n${y}`)).readUInt32BE(0) % 1_000_000;
+  return String(n).padStart(6, "0");
+}
+
+const sameBytes = (a, b) => a.length === b.length && timingSafeEqual(a, b);
+
+/**
+ * Check a WebAuthn assertion against the paired passkey.
+ *
+ * @param {object} p
+ * @param {{authenticatorData: string, clientDataJSON: string, signature: string}} p.assertion  base64url fields
+ * @param {string} p.credential   base64url SPKI of the passkey public key
+ * @param {string} p.rpId
+ * @param {string} p.origin
+ * @param {Buffer} p.challenge    the bytes this request binds (SHA-256 of its canonical signed text)
+ * @param {number} [p.prevSignCount]
+ * @returns {{ok: true, signCount: number} | {ok: false, reason: string}}
+ */
+export function verifyPasskey({
+  assertion,
+  credential,
+  rpId,
+  origin,
+  challenge,
+  prevSignCount = 0,
+}) {
+  const authData = fromB64u(assertion?.authenticatorData);
+  const clientRaw = fromB64u(assertion?.clientDataJSON);
+  if (authData.length < 37) return { ok: false, reason: "authenticator data too short" };
+  let client;
+  try {
+    client = JSON.parse(clientRaw.toString("utf8"));
+  } catch {
+    return { ok: false, reason: "client data is not JSON" };
+  }
+  if (client?.type !== "webauthn.get")
+    return { ok: false, reason: "client data type is not webauthn.get" };
+  if (!sameBytes(fromB64u(client.challenge), Buffer.from(challenge))) {
+    return { ok: false, reason: "challenge is not this request" };
+  }
+  if (client.origin !== origin) return { ok: false, reason: "origin is not the paired one" };
+  if (!sameBytes(authData.subarray(0, 32), sha256(Buffer.from(rpId)))) {
+    return { ok: false, reason: "rp id is not the paired one" };
+  }
+  const flags = authData[32];
+  if (!(flags & 0x01) || !(flags & 0x04))
+    return { ok: false, reason: "the user was not present and verified" };
+  const signCount = authData.readUInt32BE(33);
+  if ((signCount !== 0 || prevSignCount !== 0) && signCount <= prevSignCount) {
+    return { ok: false, reason: "sign count did not grow (a cloned authenticator or a replay)" };
+  }
+  let good;
+  try {
+    const key = createPublicKey({ key: fromB64u(credential), format: "der", type: "spki" });
+    good = verify(
+      "sha256",
+      Buffer.concat([authData, sha256(clientRaw)]),
+      key,
+      fromB64u(assertion.signature),
+    );
+  } catch {
+    good = false;
+  }
+  return good
+    ? { ok: true, signCount }
+    : { ok: false, reason: "signature does not verify with the paired passkey" };
+}