@worca/app 1.4.0-rc.1 → 1.5.0-rc.2

package/src/core/github-app.mjs

@@ -0,0 +1,107 @@
+// GitHub App mode: worca holds an App ID and private key and mints a short-lived
+// installation token for EACH git/gh operation (github-credentials.mjs#githubEnv).
+//
+//   WORCA_GH_APP_ID               the App's numeric id
+//   WORCA_GH_APP_KEY_FILE         path to the PEM private key (preferred), or
+//   WORCA_GH_APP_KEY_B64          base64 of the PEM, where only variables exist
+//   WORCA_GH_APP_INSTALLATION_ID  optional; else resolved from the repository, or
+//                                 the App's only installation
+//
+// The token lives for at most an hour and is never cached, written or logged:
+// minted, handed to one command's env, dropped. A run lasting days is fine, since
+// only its short fetch/push/PR calls need a credential. Each token is scoped down
+// to the role: read = contents/metadata/pull requests read; write adds contents
+// and pull requests write.
+import { createPrivateKey, createSign } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+
+const API = 'https://api.github.com';
+const HEADERS = { Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', 'User-Agent': 'worca' };
+const PERMISSIONS = {
+  read: { contents: 'read', metadata: 'read', pull_requests: 'read' },
+  write: { contents: 'write', metadata: 'read', pull_requests: 'write' },
+};
+
+const val = (v) => (typeof v === 'string' ? v.trim() : '');
+
+/** True when the App variables are present (the key itself is loaded lazily). Pure. */
+export function appConfigured(env = process.env) {
+  return /^\d+$/.test(val(env.WORCA_GH_APP_ID)) && !!(val(env.WORCA_GH_APP_KEY_FILE) || val(env.WORCA_GH_APP_KEY_B64));
+}
+
+/** { appId, key (KeyObject), installationId|null } or throws with a message that names no secret. */
+export function loadAppConfig(env = process.env, { readFile = readFileSync } = {}) {
+  const appId = val(env.WORCA_GH_APP_ID);
+  if (!/^\d+$/.test(appId)) throw new Error('WORCA_GH_APP_ID must be the App\'s numeric id');
+  let pem;
+  if (val(env.WORCA_GH_APP_KEY_FILE)) {
+    try { pem = readFile(val(env.WORCA_GH_APP_KEY_FILE), 'utf8'); } catch (e) { throw new Error(`cannot read WORCA_GH_APP_KEY_FILE (${e.code || 'error'})`); }
+  } else if (val(env.WORCA_GH_APP_KEY_B64)) {
+    pem = Buffer.from(val(env.WORCA_GH_APP_KEY_B64), 'base64').toString('utf8');
+  } else {
+    throw new Error('set WORCA_GH_APP_KEY_FILE or WORCA_GH_APP_KEY_B64');
+  }
+  let key;
+  try { key = createPrivateKey(pem); } catch { throw new Error('the App private key is not a valid PEM key'); }
+  if (key.asymmetricKeyType !== 'rsa') throw new Error('the App private key must be an RSA key');
+  const inst = val(env.WORCA_GH_APP_INSTALLATION_ID);
+  if (inst && !/^\d+$/.test(inst)) throw new Error('WORCA_GH_APP_INSTALLATION_ID must be numeric');
+  return { appId, key, installationId: inst || null };
+}
+
+const b64u = (x) => Buffer.from(typeof x === 'string' ? x : JSON.stringify(x)).toString('base64url');
+
+/** The App's own JWT (RS256): issued 60 s in the past for clock drift, valid 9 minutes. */
+export function appJwt({ appId, key }, nowMs = Date.now()) {
+  const now = Math.floor(nowMs / 1000);
+  const head = `${b64u({ alg: 'RS256', typ: 'JWT' })}.${b64u({ iat: now - 60, exp: now + 540, iss: appId })}`;
+  const sig = createSign('RSA-SHA256').update(head).sign(key).toString('base64url');
+  return `${head}.${sig}`;
+}
+
+async function api(fetchImpl, method, path, jwt, body) {
+  let res;
+  try {
+    res = await fetchImpl(`${API}${path}`, {
+      method, headers: { ...HEADERS, Authorization: `Bearer ${jwt}`, ...(body ? { 'Content-Type': 'application/json' } : {}) },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+      signal: AbortSignal.timeout(20_000),
+    });
+  } catch (e) {
+    throw new Error(`GitHub API unreachable (${e.name === 'TimeoutError' ? 'timeout' : e.code || e.name})`);
+  }
+  let data = null;
+  try { data = await res.json(); } catch { /* not JSON */ }
+  return { status: res.status, data };
+}
+
+const OWNER_REPO_RE = /^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/;
+
+/** Which installation: the configured id, else the repository's, else the App's only one. */
+export async function resolveInstallation(cfg, { repo = null, fetchImpl = fetch, now = Date.now() } = {}) {
+  if (cfg.installationId) return cfg.installationId;
+  const jwt = appJwt(cfg, now);
+  if (repo && OWNER_REPO_RE.test(repo)) {
+    const r = await api(fetchImpl, 'GET', `/repos/${repo}/installation`, jwt);
+    if (r.status === 200 && r.data?.id) return String(r.data.id);
+    if (r.status === 404) throw new Error(`the GitHub App is not installed on ${repo}`);
+    throw new Error(`cannot find the App installation for ${repo} (HTTP ${r.status})`);
+  }
+  const r = await api(fetchImpl, 'GET', '/app/installations', jwt);
+  if (r.status !== 200 || !Array.isArray(r.data)) throw new Error(`cannot list the App's installations (HTTP ${r.status})`);
+  if (r.data.length === 1) return String(r.data[0].id);
+  throw new Error(r.data.length ? 'the App has several installations: set WORCA_GH_APP_INSTALLATION_ID' : 'the GitHub App is not installed anywhere');
+}
+
+/** A fresh installation token for `role`, scoped down to it. Never cached. */
+export async function mintInstallationToken(cfg, { role = 'read', repo = null, fetchImpl = fetch, now = Date.now() } = {}) {
+  const installationId = await resolveInstallation(cfg, { repo, fetchImpl, now });
+  const r = await api(fetchImpl, 'POST', `/app/installations/${installationId}/access_tokens`, appJwt(cfg, now),
+    { permissions: PERMISSIONS[role === 'write' ? 'write' : 'read'] });
+  if (r.status === 201 && typeof r.data?.token === 'string') return { token: r.data.token, expiresAt: r.data.expires_at || null };
+  const why = r.status === 401 ? 'the App ID or private key was rejected'
+    : r.status === 404 ? `installation ${installationId} not found`
+      : r.status === 422 ? `the App lacks the ${role} permissions it asked for`
+        : `HTTP ${r.status}`;
+  throw new Error(`cannot mint a GitHub App token: ${why}`);
+}

package/src/core/github-credentials.mjs

@@ -0,0 +1,93 @@
+// GitHub credentials: which one worca holds, and the env for ONE git or gh call.
+//
+//   GH_TOKEN / GITHUB_TOKEN   single mode (today): one token for everything
+//   WORCA_GH_READ_TOKEN       split mode: clone and fetch
+//   WORCA_GH_WRITE_TOKEN      split mode: push and pull requests
+//   WORCA_GH_APP_*            App mode (github-app.mjs): a token minted per call
+//
+// Two rules (plans: "Worca hosting: projects, GitHub identity, Ask Worca"):
+//  - no agent ever gets a credential: stripGithubCredentials() runs on every
+//    claude and script spawn, in every guardrail tier and every mode;
+//  - worca's own git and gh calls get the credential for their role in THAT
+//    call's env only (credentialEnv), through a credential helper that reads a
+//    variable only worca sets. No global `gh auth setup-git` is needed.
+// credentialEnv is pure (token modes); githubEnv also mints in App mode.
+import { appConfigured, loadAppConfig, mintInstallationToken } from './github-app.mjs';
+
+/** Every variable that carries a GitHub credential. Never reaches an agent. */
+export const GITHUB_CREDENTIAL_KEYS = Object.freeze([
+  'GH_TOKEN', 'GITHUB_TOKEN', 'GH_ENTERPRISE_TOKEN', 'GITHUB_ENTERPRISE_TOKEN',
+  'WORCA_GH_READ_TOKEN', 'WORCA_GH_WRITE_TOKEN', 'WORCA_GIT_TOKEN',
+  'WORCA_GH_APP_ID', 'WORCA_GH_APP_KEY_FILE', 'WORCA_GH_APP_KEY_B64', 'WORCA_GH_APP_INSTALLATION_ID',
+]);
+
+const val = (v) => (typeof v === 'string' ? v.trim() : '');
+
+/** A copy of `env` without any GitHub credential. */
+export function stripGithubCredentials(env) {
+  const out = { ...env };
+  for (const k of GITHUB_CREDENTIAL_KEYS) delete out[k];
+  return out;
+}
+
+/** { mode: 'none'|'single'|'split'|'app', read, write }: tokens by role (null when none, and
+ *  always in App mode, where githubEnv mints one per call). Split mode falls back to the
+ *  single token for a role it leaves unset. App mode wins over both. */
+export function readGithubCredentials(env = process.env) {
+  if (appConfigured(env)) return { mode: 'app', read: null, write: null };
+  const single = val(env.GH_TOKEN) || val(env.GITHUB_TOKEN) || null;
+  const r = val(env.WORCA_GH_READ_TOKEN) || null;
+  const w = val(env.WORCA_GH_WRITE_TOKEN) || null;
+  const mode = r || w ? 'split' : single ? 'single' : 'none';
+  return { mode, read: r || single, write: w || single };
+}
+
+// The helper git runs for github.com: it answers `get` with the token worca put in
+// WORCA_GIT_TOKEN for this one call, and nothing for store/erase.
+export const GIT_CREDENTIAL_HELPER =
+  '!f() { test "$1" = get || exit 0; echo username=x-access-token; echo "password=$WORCA_GIT_TOKEN"; }; f';
+const HELPER_KEY = 'credential.https://github.com.helper';
+
+/**
+ * The env for one git or gh call that needs `role` ('read' | 'write'). Every
+ * credential is removed from `base`; the role's token (if any) is added back as
+ * GH_TOKEN for gh and, for git, as a github.com credential helper configured via
+ * GIT_CONFIG_* (appended after any the caller already set). The first helper
+ * entry is empty, which clears helpers from the user's and system config for
+ * github.com, so the token worca chose is the one used. With no token: the
+ * credential-free env, and git falls back to the user's own config, as before.
+ */
+export function credentialEnv(role, base = process.env) {
+  const creds = readGithubCredentials(base);
+  return withToken(base, role === 'write' ? creds.write : creds.read);
+}
+
+/**
+ * credentialEnv for any mode: in App mode a fresh installation token for `role` is minted
+ * for this one call (`repo` "owner/name" helps find the installation). Never throws:
+ * `{ env, error }`, where a failed mint leaves a credential-free env and says why.
+ */
+export async function githubEnv(role, { base = process.env, repo = null, fetchImpl = fetch, now = Date.now() } = {}) {
+  if (readGithubCredentials(base).mode !== 'app') return { env: credentialEnv(role, base), error: null };
+  try {
+    const { token } = await mintInstallationToken(loadAppConfig(base), { role, repo, fetchImpl, now });
+    return { env: withToken(base, token), error: null };
+  } catch (e) {
+    return { env: stripGithubCredentials(base), error: e.message };
+  }
+}
+
+function withToken(base, token) {
+  const env = stripGithubCredentials(base);
+  if (!token) return env;
+  const n = Number.parseInt(env.GIT_CONFIG_COUNT, 10);
+  const i = Number.isInteger(n) && n > 0 ? n : 0;
+  env[`GIT_CONFIG_KEY_${i}`] = HELPER_KEY;
+  env[`GIT_CONFIG_VALUE_${i}`] = '';
+  env[`GIT_CONFIG_KEY_${i + 1}`] = HELPER_KEY;
+  env[`GIT_CONFIG_VALUE_${i + 1}`] = GIT_CREDENTIAL_HELPER;
+  env.GIT_CONFIG_COUNT = String(i + 2);
+  env.WORCA_GIT_TOKEN = token;
+  env.GH_TOKEN = token;
+  return env;
+}

package/src/core/graph/executor.mjs

@@ -39,7 +39,8 @@ import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import {
   runClaude, MOCK_WRITER_ROLES, MOCK_ROLE_CLARIFY, MOCK_ROLE_DECOMPOSER,
 } from '../claude-runner.mjs';
-import { planPath, reviewPath, writeStepQuestions, writeClarify } from '../artifacts.mjs';
+import { planPath, reviewPath, writeStepQuestions, writeClarify, appendAuditById } from '../artifacts.mjs';
+import { byActor } from '../identity.mjs';
 import { readReview, classifyAskPayload } from '../protocol.mjs';
 import { prepareFormAsk, formAnswerValidator, downgradeQuestion } from '../ask-forms.mjs';
 import {
@@ -771,7 +772,9 @@ export async function runClarifierExecution(ctx) {
           agentKey: node?.key, nodeId: node?.id, questions: gate.ask,
         });
         await writeClarify(ctx.pipelineId, { questions: gate.ask });
-        const answerRow = { kind: 'form', form: gate.ask.form, version: gate.ask.version, values };
+        const formBy = clarifyAnswerer(ctx, `${CLARIFY_ASK_KIND}-${node.id}-${ordinal}`);
+        const answerRow = { kind: 'form', form: gate.ask.form, version: gate.ask.version, values, ...(formBy ? { answeredBy: formBy } : {}) };
+        auditClarify(ctx, meta, node, formBy);
         await writeStepQuestions(ctx.pipelineId, ctx.executionId, ordinal, {
           agentKey: node?.key, nodeId: node?.id, answers: answerRow,
         });
@@ -804,10 +807,13 @@ export async function runClarifierExecution(ctx) {
     });
     answers = normalizeAnswers(answerPayload, questions);
     if (ctx.pipelineId) {
+      const by = clarifyAnswerer(ctx, `${CLARIFY_ASK_KIND}-${node.id}-${ordinal}`);
+      const row = { answers, ...(by ? { answeredBy: by } : {}) };
       await writeStepQuestions(ctx.pipelineId, ctx.executionId, ordinal, {
-        agentKey: node?.key, nodeId: node?.id, answers: { answers },
+        agentKey: node?.key, nodeId: node?.id, answers: row,
       });
-      await writeClarify(ctx.pipelineId, { answers: { answers } });
+      await writeClarify(ctx.pipelineId, { answers: row });
+      auditClarify(ctx, meta, node, by);
     }
   }
 
@@ -816,6 +822,18 @@ export async function runClarifierExecution(ctx) {
   return { outputs: publishable(ports, outputs), questions, answers, sessionId, prompt, warnings };
 }
 
+/** Who answered a clarifier question (the orchestrator's answeredBy seam), or null. */
+function clarifyAnswerer(ctx, id) {
+  try { const by = typeof ctx.answeredBy === 'function' ? ctx.answeredBy(id) : null; return typeof by === 'string' && by ? by : null; }
+  catch { return null; }
+}
+
+/** The audit line for a human clarifier answer (actor stored always; named unless 'local'). */
+function auditClarify(ctx, meta, node, by) {
+  if (!by || !ctx.pipelineId) return;
+  appendAuditById(ctx.pipelineId, `${meta?.displayName || node?.key || 'Clarify'}: questions answered${byActor(by)}.`, { actor: by });
+}
+
 // ── flow executors (pure engine: instant, $0, no process spawn) ───────────────
 
 /** Write a file, creating its directory. Synchronous on purpose: the flow cards run

package/src/core/graph/script-runner.mjs

@@ -19,6 +19,8 @@ import { readVerdict, missingVerdictWarning } from './exec-io.mjs';
 import { AWAIT_PORT, PARAMS_PORT } from '../../shared/graph/constants.mjs';
 import { DEFAULT_EXIT_CODES, DEFAULT_TIMEOUT_MS, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS, SCRIPT_RUNTIMES, pythonMissingSentence, overlayWiredParams } from '../../shared/graph/script-meta.mjs';
 import { probePython } from './python-probe.mjs';
+import { stripGithubCredentials } from '../github-credentials.mjs';
+import { agentIdentity, agentSpawn, killAgentGroupSync } from '../agent-user.mjs';
 
 const CHILD_PATH = fileURLToPath(new URL('./script-child.mjs', import.meta.url));
 /** The `python` harness (workbench spec §7), spawned as `<python> -u worca_script.py <program.py>`. */
@@ -152,7 +154,8 @@ export function envForShell(envelope, baseEnv = process.env) {
  *  environment than the agents beside it. Scrub off: the server's env (D11). */
 export function scriptBaseEnv(claudeOpts, platform = process.platform) {
   const scrubbed = buildSpawnEnv(claudeOpts?.envScrub, claudeOpts?.envAllowlist);
-  return scrubbed ? { ...scrubbedEnv(platform), ...scrubbed } : process.env;
+  // Never a GitHub credential, like the agents (src/core/github-credentials.mjs).
+  return stripGithubCredentials(scrubbed ? { ...scrubbedEnv(platform), ...scrubbed } : process.env);
 }
 
 export function parseFrame(text) {
@@ -247,9 +250,17 @@ export function killTree(child, platform = process.platform) {
     }
     return;
   }
+  // A script under the agent's uid (agent-user.mjs): the server can signal sudo but not the script, so the
+  // group goes down through sudo too. Only while sudo still runs: after it exits the pid may be reused.
+  const agent = agentOf.get(child);
+  const alive = child.exitCode === null && child.signalCode === null;
   try { process.kill(-child.pid, 'SIGKILL'); } catch { try { child.kill('SIGKILL'); } catch { /* gone */ } }
+  if (agent && alive) killAgentGroupSync(child.pid, agent);
 }
 
+/** Children spawned under the agent's uid -> that identity (for killTree). */
+const agentOf = new WeakMap();
+
 /** How long a killed spawn may keep its pipes before we stop waiting for `'close'`. */
 const KILL_GRACE_MS = 2000;
 
@@ -271,15 +282,25 @@ process.on('exit', () => { for (const [child, platform] of live) killTree(child,
 export function spawnScript({ file, args, cwd, env, stdin = null, timeoutMs, signal, onLine, stdoutMode, platform = process.platform }) {
   return new Promise((resolve, reject) => {
     const started = Date.now();
-    const child = spawn(file, args, {
+    // Scripts run the agents' code (tests, builds): under the agent's uid when the container has one.
+    const agent = platform !== 'win32' ? agentIdentity() : null;
+    let spawnFile = file;
+    let spawnArgs = args;
+    let spawnEnv = env;
+    if (agent) {
+      try { ({ file: spawnFile, args: spawnArgs, env: spawnEnv } = agentSpawn(file, args, env || process.env, agent)); }
+      catch (err) { reject(err); return; }
+    }
+    const child = spawn(spawnFile, spawnArgs, {
       cwd,
-      env,
+      env: spawnEnv,
       detached: platform !== 'win32',
       windowsHide: true,
       windowsVerbatimArguments: platform === 'win32' && stdoutMode === 'capture',
       stdio: [stdin == null ? 'ignore' : 'pipe', 'pipe', 'pipe'],
     });
     live.set(child, platform);
+    if (agent) agentOf.set(child, agent);
     const capture = createCapture();
     const partial = { out: '', err: '' };
     let frameOut = '';

package/src/core/guardrails.mjs

@@ -40,6 +40,7 @@ const NORMAL_PROTECTED = [
   '*.pem', '*.key',        // TLS / private key material
   'id_rsa', 'id_ed25519',  // bare SSH keys checked into odd places
   '*.p12', '*.pfx',        // bundled cert+key stores
+  '//run/secrets/**',      // container secrets (docker/compose `secrets:`); `//` = absolute
 ];
 
 // Irreversible-publication commands no pipeline role ever needs.

package/src/core/identity.mjs

@@ -0,0 +1,83 @@
+// Who started this: attribution, not authorisation (everyone signed in keeps the
+// same rights). The first source that applies wins, and nothing is ever guessed:
+//
+//   1. the identity the server VERIFIED for this request (a Cloudflare Access
+//      token, remote-access.mjs -> req.worcaUser)
+//   2. WORCA_IDENTITY_HEADER: a header an identity proxy in front sets (oauth2-proxy,
+//      Tailscale, an IAP). Read only when named: a header means nothing unless the
+//      proxy verifies it and strips any incoming copy, so unset = ignored even if sent
+//   3. WORCA_IDENTITY_NAME: a name the operator declares (a self-hoster with no proxy)
+//   4. 'local': the CLI, in-container callers, a local install
+//
+// Pure: reads only the request and `env`.
+
+const HEADER_NAME_RE = /^[A-Za-z0-9-]{1,64}$/;
+// A display name or email: printable, one line, bounded. It lands in PR bodies and the UI.
+const VALUE_RE = /^[^\u0000-\u001f\u007f-\u009f\u2028\u2029<>]{1,200}$/;
+
+const clean = (v) => {
+  const s = typeof v === 'string' ? v.trim() : '';
+  return VALUE_RE.test(s) ? s : null;
+};
+
+/** { name, source: 'access'|'header'|'operator'|'local' } for this request. */
+export function resolveIdentity(req, env = process.env) {
+  const verified = clean(req?.worcaUser?.email);
+  if (verified) return { name: verified, source: 'access' };
+  const header = String(env.WORCA_IDENTITY_HEADER || '').trim();
+  if (HEADER_NAME_RE.test(header)) {
+    const v = req?.headers?.[header.toLowerCase()];
+    const name = clean(Array.isArray(v) ? v[0] : v);
+    if (name) return { name, source: 'header' };
+  }
+  const operator = clean(env.WORCA_IDENTITY_NAME);
+  if (operator) return { name: operator, source: 'operator' };
+  return { name: 'local', source: 'local' };
+}
+
+/** The startedBy a run records: the resolved name ('local' when nothing else applies). */
+export function startedByOf(req, env = process.env) {
+  return resolveIdentity(req, env).name;
+}
+
+/** The PR body footer naming who started the run, or '' when nobody in particular did. */
+export function prAttributionFooter(startedBy) {
+  const who = clean(startedBy);
+  return who && who !== 'local' ? `\n\n---\nStarted by ${who} via worca` : '';
+}
+
+/** Who did this: the actor string an action records ('local' when nothing applies). */
+export function actorOf(req, env = process.env) {
+  return resolveIdentity(req, env).name;
+}
+
+/** The name an action's actor shows as in text (audit lines, exports), or '' for 'local' /
+ *  unknown / invalid values — the caller then says nothing about who. */
+export function actorLabel(actor) {
+  const who = clean(actor);
+  return who && who !== 'local' ? who : '';
+}
+
+/** " by <name>" for an audit line, or '' when nobody in particular did it. */
+export function byActor(actor) {
+  const who = actorLabel(actor);
+  return who ? ` by ${who}` : '';
+}
+
+/** True for a real per-person sign-in (a verified token or a named trusted header): the
+ *  deployments where "who" can have more than one answer, so ownership and per-person
+ *  state apply. 'operator' and 'local' are one person by definition. */
+export function isSharedIdentity(source) {
+  return source === 'access' || source === 'header';
+}
+
+const PLATFORM_NAMES = { slack: 'Slack', telegram: 'Telegram', discord: 'Discord', teams: 'Teams', msteams: 'Teams' };
+
+/** The actor for a chat command: "ada via Slack" (sanitised like every other value), or
+ *  "someone via Slack" when the platform gave no usable name. */
+export function chatActor({ platform, userName, userId } = {}) {
+  const p = String(platform || '').trim().toLowerCase();
+  const via = PLATFORM_NAMES[p] || clean(platform) || 'chat';
+  const who = clean(userName) || clean(userId != null ? String(userId) : '') || 'someone';
+  return clean(`${who} via ${via}`) || `someone via ${via}`;
+}

package/src/core/metrics/pr-events-workflow.yml

@@ -0,0 +1,127 @@
+# Worca team metrics: pull-request events for the delivery timeline.
+#
+# Writes one small file per pull request, .worca-metrics/prs/<number>.json, to the
+# worca-metrics branch whenever a PR is opened, reopened or closed, so the Team metrics
+# Timeline knows when work merged without anyone needing the GitHub CLI. Run it by hand
+# ("Run workflow") to backfill the PRs updated in the last N days.
+#
+# Installed by `worca metrics pr-workflow`; see docs/team-metrics.md ("Merge tracking").
+# Safe on pull_request_target: it never checks out or runs code from the pull request,
+# it only reads the event's metadata. It does nothing when the repository has no
+# worca-metrics branch. Like Worca itself, it needs worca-metrics to be exempt from
+# branch protection.
+name: Worca metrics · PR events
+
+on:
+  pull_request_target:
+    types: [opened, reopened, closed]
+  workflow_dispatch:
+    inputs:
+      days:
+        description: Backfill the pull requests updated in the last N days
+        default: '90'
+
+permissions:
+  contents: write
+  pull-requests: read
+
+concurrency:
+  group: worca-metrics-pr-events
+  cancel-in-progress: false
+
+jobs:
+  record:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/github-script@v8
+        with:
+          script: |
+            const BRANCH = 'worca-metrics';
+            const DIR = '.worca-metrics/prs';
+            const { owner, repo } = context.repo;
+            const headRef = async () => (await github.rest.git.getRef({ owner, repo, ref: `heads/${BRANCH}` })).data.object.sha;
+            try { await headRef(); } catch (e) {
+              if (e.status === 404) { core.notice(`No ${BRANCH} branch here: team metrics are not enabled, nothing to record.`); return; }
+              throw e;
+            }
+            // The team's attribution choice (set when team metrics was enabled): with "none", no
+            // author is recorded, as for the run records.
+            let attribution = 'git-user';
+            try {
+              const cfg = await github.rest.repos.getContent({ owner, repo, path: '.worca-metrics/config.json', ref: BRANCH });
+              attribution = JSON.parse(Buffer.from(cfg.data.content, 'base64').toString('utf8')).attribution || attribution;
+            } catch (e) { core.info(`No readable .worca-metrics/config.json (${e.status || e.message}); recording authors.`); }
+            const clean = (s) => String(s || '').replace(/[\u0000-\u001F\u007F-\u009F\u2028\u2029]+/g, ' ').trim().slice(0, 200);
+            // Who made the PR, the way Worca names the author of a run: the git author of most of its
+            // commits (name, plus a key = sha256("worca:" + email), never the address itself). Git
+            // identities are the same on every host; the GitHub login is kept only as a fallback.
+            // Machine identities (Worca's own run commits, orchestrator@local) are skipped.
+            const who = new Map();   // PR number → { name, key }
+            const personKey = (email) => {
+              const e = String(email || '').trim().toLowerCase();
+              if (!e.includes('@') || /@local$/.test(e)) return null;
+              return require('crypto').createHash('sha256').update(`worca:${e}`).digest('hex').slice(0, 16);
+            };
+            const loadAuthors = async (numbers) => {
+              for (let i = 0; i < numbers.length; i += 50) {
+                const batch = numbers.slice(i, i + 50);
+                const q = `query($owner: String!, $repo: String!) { repository(owner: $owner, name: $repo) { ${batch.map((n, j) => `p${j}: pullRequest(number: ${Number(n)}) { commits(first: 100) { nodes { commit { author { name email } } } } }`).join(' ')} } }`;
+                let data;
+                try { data = await github.graphql(q, { owner, repo }); } catch (e) { data = e.data; core.info(`Some commit authors could not be read: ${e.message}`); }
+                batch.forEach((n, j) => {
+                  const nodes = data?.repository?.[`p${j}`]?.commits?.nodes || [];
+                  const tally = new Map();   // key → { n, names: Map(name → n) }
+                  for (const c of nodes) {
+                    const a = c?.commit?.author;
+                    const key = personKey(a?.email);
+                    if (!key) continue;
+                    const t = tally.get(key) || { n: 0, names: new Map() };
+                    t.n += 1;
+                    if (a.name) t.names.set(a.name, (t.names.get(a.name) || 0) + 1);
+                    tally.set(key, t);
+                  }
+                  const top = [...tally.entries()].sort((x, y) => y[1].n - x[1].n)[0];
+                  if (top) who.set(n, { key: top[0], name: [...top[1].names.entries()].sort((x, y) => y[1] - x[1])[0]?.[0] || null });
+                });
+              }
+            };
+            const toEvent = (pr) => ({
+              v: 1, kind: 'pr', repo: `${owner}/${repo}`, number: pr.number, url: pr.html_url, title: clean(pr.title),
+              head: pr.head.ref, base: pr.base.ref, author: attribution === 'none' ? null : (pr.user && pr.user.login) || null,
+              authorName: attribution === 'none' ? null : clean(who.get(pr.number)?.name) || null,
+              authorKey: attribution === 'none' ? null : who.get(pr.number)?.key || null,
+              state: pr.merged_at ? 'MERGED' : pr.state === 'closed' ? 'CLOSED' : 'OPEN',
+              createdAt: pr.created_at, mergedAt: pr.merged_at || null, closedAt: pr.closed_at || null, updatedAt: pr.updated_at,
+            });
+            let prs = [];
+            if (context.eventName === 'workflow_dispatch') {
+              const days = Math.max(1, Math.min(3650, Number(context.payload.inputs?.days) || 90));
+              const since = Date.now() - days * 86400000;
+              outer: for await (const page of github.paginate.iterator(github.rest.pulls.list, { owner, repo, state: 'all', sort: 'updated', direction: 'desc', per_page: 100 })) {
+                for (const pr of page.data) { if (Date.parse(pr.updated_at) < since) break outer; prs.push(pr); }
+              }
+            } else prs = [context.payload.pull_request];
+            prs = prs.filter((pr) => pr && pr.head && pr.head.ref);
+            if (attribution !== 'none') await loadAuthors(prs.map((pr) => pr.number));
+            for (let i = 0; i < prs.length; i += 200) {
+              const chunk = prs.slice(i, i + 200);
+              const tree = chunk.map((pr) => ({ path: `${DIR}/${pr.number}.json`, mode: '100644', type: 'blob', content: `${JSON.stringify(toEvent(pr))}\n` }));
+              const message = chunk.length === 1 ? `worca-metrics: PR #${chunk[0].number} ${toEvent(chunk[0]).state.toLowerCase()}` : `worca-metrics: ${chunk.length} PR events`;
+              for (let attempt = 1; ; attempt++) {
+                const parent = await headRef();
+                const base = (await github.rest.git.getCommit({ owner, repo, commit_sha: parent })).data.tree.sha;
+                const next = (await github.rest.git.createTree({ owner, repo, base_tree: base, tree })).data.sha;
+                if (next === base) { core.info('Already up to date.'); break; }
+                const commit = (await github.rest.git.createCommit({ owner, repo, message, tree: next, parents: [parent] })).data.sha;
+                try {
+                  await github.rest.git.updateRef({ owner, repo, ref: `heads/${BRANCH}`, sha: commit, force: false });
+                  core.info(`${message} (${chunk.length} file${chunk.length === 1 ? '' : 's'})`);
+                  break;
+                } catch (e) {
+                  // 422: someone (a teammate's Worca) pushed in between. Rebuild on the new tip.
+                  if (e.status !== 422 || attempt >= 5) throw e;
+                  await new Promise((r) => setTimeout(r, 1000 * attempt));
+                }
+              }
+            }