forgedock 1.16.2 → 1.18.0

package/bin/engine/projector.mjs

@@ -3,6 +3,16 @@
  * `io.gh(args)` is injected (async, returns stdout) so this is testable offline.
  */
 import { parseState, upsertStateBlock } from "./state.mjs";
+import { isTrustedActor } from "./phases.mjs";
+
+// Defence in depth: a lease further out than 3x the engine's 10 min TTL (same
+// bound as scripts/remediate-liveness.sh MAX_LEASE_TTL_MS) is never honoured.
+export const MAX_LEASE_TTL_MS = 3 * 600_000;
+
+// Body + provenance in ONE call. `gh issue view --json` cannot return the last
+// editor or authorAssociation, so GraphQL is used. -F variables, never interpolation.
+const PROVENANCE_QUERY = "query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){"
+  + "issue(number:$number){body authorAssociation author{login __typename} editor{login __typename}}}}";
 
 export function makeProjector(io) {
   const gh = io.gh;
@@ -12,9 +22,46 @@ export function makeProjector(io) {
     try { return JSON.parse(out).body ?? ""; } catch { return ""; }
   }
 
+  /**
+   * Body of the issue iff its LAST EDITOR (`editor ?? author`) is trusted, else
+   * null. The reporter can edit their own body, so creator-only trust is wrong
+   * and engine writes (bot editor) must stay readable. Any error, malformed
+   * JSON or missing provenance fails closed (null).
+   */
+  async function getTrustedBody(issue) {
+    try {
+      const out = await gh(["api", "graphql", "-f", `query=${PROVENANCE_QUERY}`,
+        "-F", "owner={owner}", "-F", "name={repo}", "-F", `number=${Number(issue)}`]);
+      const i = JSON.parse(out)?.data?.repository?.issue;
+      if (!i || typeof i.body !== "string") return null;
+      const actor = i.editor ?? i.author;
+      if (!actor || typeof actor !== "object") return null;
+      // authorAssociation describes the CREATOR: valid for the actor only when
+      // the actor IS the creator. A distinct human editor's standing comes from
+      // the collaborator permission endpoint (fail closed to NONE).
+      let association = "NONE";
+      if (!i.editor || i.editor.login === i.author?.login) association = i.authorAssociation;
+      else if (actor.__typename !== "Bot" && typeof actor.login === "string" && /^[A-Za-z0-9-]+(\[bot\])?$/.test(actor.login)) {
+        try {
+          const perm = JSON.parse(await gh(["api", `repos/{owner}/{repo}/collaborators/${actor.login}/permission`, "--jq", "{permission}"])).permission;
+          association = perm === "admin" ? "OWNER" : (perm === "maintain" || perm === "write") ? "COLLABORATOR" : "NONE";
+        } catch { /* fail closed */ }
+      }
+      return isTrustedActor({ association, type: actor.__typename, login: actor.login }) ? i.body : null;
+    } catch { return null; }
+  }
+
   return {
     /** @returns {Promise<import("./phases.mjs").RunState|null>} */
-    async readState(issue) { return parseState(await getBody(issue)); },
+    async readState(issue) {
+      const body = await getTrustedBody(issue);
+      if (body === null) return null;
+      const st = parseState(body);
+      if (st?.lease && !(Number.isFinite(st.lease.until) && st.lease.until <= Date.now() + MAX_LEASE_TTL_MS)) {
+        return { ...st, lease: null };
+      }
+      return st;
+    },
 
     async writeState(issue, index) {
       const body = upsertStateBlock(await getBody(issue), index);

package/bin/engine/runlog.mjs

@@ -12,7 +12,10 @@ export function appendEvent(dir, issue, event) {
   mkdirSync(dir, { recursive: true });
   const path = logPath(dir, issue);
   const seq = readLog(dir, issue).length + 1;
-  appendFileSync(path, JSON.stringify({ seq, ...event }) + "\n");
+  // forge#3696: wall-clock ISO-8601 `ts` on every appended event. Placed before the
+  // spread so a caller-supplied `ts` wins. rewriteLog() deliberately does not stamp:
+  // a hydrated rewrite time would be a false timestamp. Old logs lack `ts` and still parse.
+  appendFileSync(path, JSON.stringify({ seq, ts: new Date().toISOString(), ...event }) + "\n");
 }
 
 /**
@@ -58,7 +61,9 @@ export function deriveState(events) {
   const s = { v: 0, run: null, issue: null, lane: "staging", committed: [],
               phase: null, branch: null, pr: null, terminal: false,
               terminalReason: null, lease: null, lastRateLimit: null,
-              remediationKind: null };
+              remediationKind: null, outcomeCode: null };
+  // forge#3833: outcome code of the LAST PHASE_COMMIT only (replaced, like lastCommitReason).
+  let lastCommitCode = null;
   // forge#3528: handoff reason of the LAST PHASE_COMMIT only (replaced, not sticky).
   let lastCommitReason = null;
   // forge#3754: phase of the LAST PHASE_COMMIT, so a reopen can tell a remediate-terminal run.
@@ -80,6 +85,8 @@ export function deriveState(events) {
         // remediate instead of defaulting to a "merged" close.
         if (e.terminalReason) s.terminalReason = e.terminalReason;
         lastCommitReason = e.terminalReason ?? null;
+        lastCommitCode = e.code ?? null;
+        if (e.code) s.outcomeCode = e.code;
         lastCommitPhase = e.phase ?? null;
         // forge#3530: the review's remediation kind must survive resume. A later review
         // commit replaces it; a committed remediate consumes it, so it is never reused.
@@ -89,6 +96,7 @@ export function deriveState(events) {
       case "RUN_TERMINAL":
         s.terminal = true; s.terminalReason = e.reason ?? "done"; s.v = e.seq;
         lastTerminalReason = s.terminalReason;
+        if (e.code) s.outcomeCode = e.code;
         break;
       // forge#3511: an explicit `run-issue --retry` reopens an engine-error
       // terminal. Bumping `v` makes the local state newer than the stale
@@ -97,7 +105,14 @@ export function deriveState(events) {
       // (needs-human / decomposed); restore the last commit's reason so the
       // retry re-enters remediate/decompose instead of close/build.
       case "RUN_REOPEN":
-        s.terminal = false; s.terminalReason = lastCommitReason; s.v = e.seq;
+        s.terminal = false; s.terminalReason = lastCommitReason; s.outcomeCode = lastCommitCode; s.v = e.seq;
+        // forge#3862: a `decomposed` terminal whose decomposition was revoked (trusted GitHub state,
+        // checked by the engine before it appends this event) reopens at build: un-commit the
+        // phases named in `uncommit` and drop the stale handoff reason so pickPhase re-selects build.
+        if (Array.isArray(e.uncommit) && e.uncommit.length) {
+          s.committed = s.committed.filter((p) => !e.uncommit.includes(p));
+          s.terminalReason = null; s.outcomeCode = null;
+        }
         // forge#3754: a remediate that ended needs-human is re-run after a human clears the
         // label. Un-commit it (new array, no in-place mutation) so the forge#3506 resume guard
         // does not re-terminate and remediate's entryCondition re-selects it.
@@ -119,9 +134,9 @@ export function deriveState(events) {
       // lastCommitReason is reset so a stale handoff reason cannot leak into
       // the new cycle through a later RUN_REOPEN.
       case "RUN_NEXT_CYCLE":
-        s.terminal = false; s.terminalReason = null; s.committed = [];
+        s.terminal = false; s.terminalReason = null; s.committed = []; s.outcomeCode = null;
         s.branch = null; s.pr = null; s.remediationKind = null;
-        lastCommitReason = null; lastCommitPhase = null; lastTerminalReason = null; s.v = e.seq;
+        lastCommitReason = null; lastCommitPhase = null; lastCommitCode = null; lastTerminalReason = null; s.v = e.seq;
         s.lastRateLimit = null; // forge#3791
         break;
       // forge#2524: a session-limit pause is purely informational — it does

package/bin/engine/telemetry-seam.mjs

@@ -0,0 +1,62 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * forge#3835: the engine's `emitTelemetry` seam writer. Maps the run-log shaped records the engine hands to the
+ * seam onto FORGE:TELEMETRY events so `forgedock stats` can rebuild Cost, Time and outcome codes from GitHub alone:
+ *   PHASE_ATTEMPT_USAGE -> `phase_attempt` (attempt, model, turns, duration_ms, cost_usd, *_tokens)
+ *   RUN_TERMINAL        -> `run_terminal`  (reason, code, wall_ms)
+ * Other records are ignored. The returned function NEVER throws and honours FORGE_TELEMETRY=off. Telemetry values
+ * are scalars (the emitter stringifies objects), so the `usage` object is flattened here; absent values are omitted.
+ */
+import { execFileSync } from "node:child_process";
+import { emit } from "./telemetry.mjs";
+
+export function defaultResolveRepo() {
+  try {
+    const r = execFileSync("gh", ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 15000 }).trim();
+    return /^[\w.-]+\/[\w.-]+$/.test(r) ? r : null;
+  } catch { return null; }
+}
+
+const scalar = (v) => (typeof v === "number" ? Number.isFinite(v) : typeof v === "string" && v !== "");
+const compact = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => scalar(v)));
+const tok = (u, k) => (u && typeof u === "object" && Number.isFinite(u[k]) ? u[k] : undefined);
+
+/** Pure mapping, exported for tests: returns { event, payload, phase } or null when the record is not mapped. */
+export function mapRecord(rec, wallMs) {
+  if (!rec || typeof rec !== "object") return null;
+  if (rec.event === "PHASE_ATTEMPT_USAGE") {
+    return { event: "phase_attempt", phase: rec.phase, payload: compact({
+      attempt: rec.attempt, model: rec.model, turns: rec.turns, duration_ms: rec.duration_ms,
+      cost_usd: Number.isFinite(rec.cost_usd) ? Math.round(rec.cost_usd * 1e6) / 1e6 : undefined,
+      input_tokens: tok(rec.usage, "input_tokens"), output_tokens: tok(rec.usage, "output_tokens"),
+      cache_read_tokens: tok(rec.usage, "cache_read_input_tokens"), cache_creation_tokens: tok(rec.usage, "cache_creation_input_tokens"),
+    }) };
+  }
+  if (rec.event === "RUN_TERMINAL") {
+    return { event: "run_terminal", phase: null, payload: compact({ reason: rec.reason, code: rec.code, wall_ms: wallMs }) };
+  }
+  return null;
+}
+
+/**
+ * @param {{repo?: string|null, emitFn?: Function, now?: () => number, resolveRepo?: () => string|null, env?: object}} o
+ * @returns {(rec: object) => Promise<void>}
+ */
+export function makeEmitTelemetry({ repo = null, emitFn = emit, now = Date.now, resolveRepo = defaultResolveRepo, env = process.env } = {}) {
+  const startedAt = now();
+  let resolved = repo || env.FORGE_REPO || null;
+  let tried = Boolean(resolved);
+  return async (rec) => {
+    try {
+      if ((env.FORGE_TELEMETRY || "on") === "off") return;
+      const mapped = mapRecord(rec, now() - startedAt);
+      if (!mapped || rec.issue == null) return;
+      if (!tried) { tried = true; resolved = resolveRepo() || null; }
+      if (!resolved) return; // no destination: the Node emitter would drop it anyway
+      // ctx carries repo/issue/run/phase: emit() drops those reserved keys from the payload.
+      emitFn(mapped.event, mapped.payload, { repo: resolved, issue: rec.issue, run: `r_${rec.issue}_${Math.floor(startedAt / 1000)}`, phase: mapped.phase ?? undefined });
+    } catch { /* telemetry never fails a run */ }
+  };
+}

package/bin/engine/telemetry-seam.test.mjs

@@ -0,0 +1,60 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { makeEmitTelemetry, mapRecord } from "./telemetry-seam.mjs";
+
+const attempt = { event: "PHASE_ATTEMPT_USAGE", phase: "build", attempt: 2, issue: 7, duration_ms: 1234, cost_usd: 0.123456789, model: "sonnet", turns: null,
+  usage: { input_tokens: 1, output_tokens: 2, cache_read_input_tokens: 3, cache_creation_input_tokens: 4 } };
+
+function harness(over = {}) {
+  const calls = [];
+  const emit = makeEmitTelemetry({ repo: "o/r", emitFn: (...a) => { calls.push(a); }, now: () => 5000, env: {}, ...over });
+  return { calls, emit };
+}
+
+describe("engine telemetry seam", () => {
+  it("flattens usage, omits nulls and passes repo/issue/run/phase as ctx (not payload)", async () => {
+    const { calls, emit } = harness();
+    await emit(attempt);
+    const [event, payload, ctx] = calls[0];
+    assert.equal(event, "phase_attempt");
+    assert.deepEqual(payload, { attempt: 2, model: "sonnet", duration_ms: 1234, cost_usd: 0.123457, input_tokens: 1, output_tokens: 2, cache_read_tokens: 3, cache_creation_tokens: 4 });
+    assert.equal(ctx.repo, "o/r");
+    assert.equal(ctx.issue, 7);
+    assert.equal(ctx.phase, "build");
+    assert.match(ctx.run, /^r_7_\d+$/);
+    for (const v of Object.values(payload)) assert.notEqual(typeof v, "object");
+  });
+  it("maps RUN_TERMINAL with reason, code and wall time; ignores other records", async () => {
+    let t = 1000;
+    const { calls, emit } = harness({ now: () => t });
+    t = 61000;
+    await emit({ event: "RUN_TERMINAL", reason: "needs-human", code: "review.escalated", issue: 7 });
+    await emit({ event: "PHASE_START", phase: "build", issue: 7 });
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0][0], "run_terminal");
+    assert.deepEqual(calls[0][1], { reason: "needs-human", code: "review.escalated", wall_ms: 60000 });
+    assert.equal(calls[0][2].phase, undefined);
+  });
+  it("null usage yields a record with no token fields", () => {
+    assert.deepEqual(mapRecord({ event: "PHASE_ATTEMPT_USAGE", phase: "build", attempt: 1, usage: null, duration_ms: 5 }).payload, { attempt: 1, duration_ms: 5 });
+  });
+  it("never throws, even when the emitter throws, and honours FORGE_TELEMETRY=off", async () => {
+    const boom = harness({ emitFn: () => { throw new Error("down"); } });
+    await boom.emit(attempt);
+    const off = harness({ env: { FORGE_TELEMETRY: "off" } });
+    await off.emit(attempt);
+    assert.equal(off.calls.length, 0);
+  });
+  it("drops records with no resolvable repo (the Node emitter would drop them) and resolves lazily once", async () => {
+    let resolves = 0;
+    const none = harness({ repo: null, resolveRepo: () => { resolves++; return null; } });
+    await none.emit(attempt); await none.emit(attempt);
+    assert.equal(none.calls.length, 0);
+    assert.equal(resolves, 1);
+    const some = harness({ repo: null, resolveRepo: () => "a/b" });
+    await some.emit(attempt);
+    assert.equal(some.calls[0][2].repo, "a/b");
+  });
+});

package/bin/engine/telemetry.mjs

@@ -0,0 +1,148 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Node twin of scripts/lib/telemetry.sh: same record shape, same upsert into the trusted
+ * `<!-- FORGE:TELEMETRY v1 -->` comment, same rollover and local buffer. emit() NEVER throws and never
+ * rejects its caller; FORGE_TELEMETRY=off disables it. Records hold ids, counts and codes only.
+ */
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { accessSync, appendFileSync, constants, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(here, "..", "..");
+const RESERVED = new Set(["v", "ts", "forge_version", "repo", "issue", "pr", "run", "phase", "event", "eid"]);
+const MARKER_RE = /^<!-- FORGE:TELEMETRY v1( part=(\d+))? -->/;
+const REVIEW_SIDE = new Set(["review_panel", "finding_disposition", "ci_gate"]);
+
+const clean = (v) => String(v).replace(/[\n\r\t]/g, " ").replace(/[^A-Za-z0-9 _.:/#@+=,-]/g, "_").slice(0, 200);
+const num = (s) => (/^[0-9]+$/.test(s ?? "") ? Number(s) : null);
+const str = (s) => (s ? String(s) : null);
+
+function forgeVersion() {
+  try { return JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version || null; } catch { return null; }
+}
+
+/** Same JSON line the shell emitter writes (key order included). `ctx` overrides the FORGE_* env. */
+export function buildRecord(event, payload = {}, ctx = {}, now = new Date()) {
+  const env = process.env;
+  const c = {
+    repo: ctx.repo ?? env.FORGE_REPO, issue: ctx.issue ?? env.FORGE_ISSUE, pr: ctx.pr ?? env.FORGE_PR,
+    run: ctx.run ?? env.FORGE_RUN, phase: ctx.phase ?? env.FORGE_PHASE,
+  };
+  const extra = {};
+  for (const [k, raw] of Object.entries(payload)) {
+    if (!/^[A-Za-z0-9_]+$/.test(k) || RESERVED.has(k)) continue;
+    const v = clean(raw);
+    extra[k] = /^-?[0-9]+$/.test(v) ? Number(v) : v === "true" ? true : v === "false" ? false : v;
+  }
+  return {
+    v: 1, ts: now.toISOString().replace(/\.\d+Z$/, "Z"), forge_version: forgeVersion(), repo: str(c.repo),
+    issue: num(String(c.issue ?? "")), pr: num(String(c.pr ?? "")), run: str(c.run), phase: str(c.phase), event,
+    eid: `${Math.floor(now.getTime() / 1000)}-${process.pid}-${randomBytes(4).toString("hex")}`, ...extra,
+  };
+}
+
+function target(event, rec) {
+  const order = REVIEW_SIDE.has(event) ? [rec.pr, rec.issue] : [rec.issue, rec.pr];
+  const n = order.find((x) => x != null);
+  return n != null && rec.repo && rec.repo.includes("/") ? n : null;
+}
+
+function gh(args) {
+  const bin = process.env.FORGE_TELEMETRY_GH || "gh";
+  const r = spawnSync(bin, args, { encoding: "utf8", timeout: 30000, maxBuffer: 64 * 1024 * 1024 });
+  if (r.error || r.status !== 0) throw new Error("gh failed");
+  return r.stdout;
+}
+
+function trusted(comment) {
+  const tc = join(ROOT, "scripts", "trusted-comments.sh");
+  const r = spawnSync("bash", [tc, "count", MARKER_RE.source], { input: JSON.stringify([comment]), encoding: "utf8" });
+  return r.status === 0 && r.stdout.trim() === "1";
+}
+
+function upsert(repo, n, lines) {
+  const max = Number(process.env.FORGE_TELEMETRY_MAX_CHARS) || 60000;
+  const raw = gh(["api", "--paginate", `repos/${repo}/issues/${n}/comments`]).trim();
+  const pages = raw ? JSON.parse(`[${raw.replace(/\]\s*\[/g, "],[")}]`) : [[]];
+  let best = null;
+  const parts = [];
+  for (const c of pages.flat()) {
+    const m = MARKER_RE.exec(c.body || "");
+    if (!m || !trusted(c)) continue;
+    const part = m[2] ? Number(m[2]) : 1;
+    parts.push({ body: c.body });
+    if (!best || part >= best.part) best = { id: c.id, part, body: c.body };
+  }
+  const all = parts.map((p) => p.body).join("\n");
+  const fresh = lines.filter((l) => !all.includes(l));
+  if (fresh.length === 0) return;
+  if (best) {
+    const cut = best.body.lastIndexOf("\n```");
+    const out = `${cut >= 0 ? best.body.slice(0, cut) : best.body}\n${fresh.join("\n")}\n\`\`\``;
+    if (out.length <= max) { gh(["api", "-X", "PATCH", `repos/${repo}/issues/comments/${best.id}`, "-f", `body=${out}`]); return; }
+  }
+  const hdr = best ? `<!-- FORGE:TELEMETRY v1 part=${best.part + 1} -->` : "<!-- FORGE:TELEMETRY v1 -->";
+  gh(["api", "-X", "POST", `repos/${repo}/issues/${n}/comments`, "-f", `body=${hdr}\n\`\`\`jsonl\n${fresh.join("\n")}\n\`\`\``]);
+}
+
+/** Emit one event. Returns the record when written or buffered, null when disabled/dropped. Never throws. */
+export function emit(event, payload = {}, ctx = {}) {
+  try {
+    if ((process.env.FORGE_TELEMETRY || "on") === "off") return null;
+    if (!/^[A-Za-z0-9_.-]+$/.test(event || "")) return null;
+    const rec = buildRecord(event, payload, ctx);
+    const n = target(event, rec);
+    if (n == null) return null;
+    const dir = process.env.FORGE_TELEMETRY_BUFFER_DIR || join(homedir(), ".forge", "telemetry-buffer");
+    const buf = join(dir, `${rec.repo.replace("/", "_")}__${n}.jsonl`);
+    const line = JSON.stringify(rec);
+    // Per-target lock (mkdir is atomic): serializes emitters on this host so the unversioned GitHub read-modify-write
+    // cannot lose a record or double-POST a part. Bounded wait (50 x 0.1s); a lock over 5 min old is stale and is
+    // reclaimed by an atomic rename (one winner); the holder writes an owner token and releases only its own lock.
+    // A non-writable buffer dir skips locking; on timeout the record is buffered.
+    let canLock = true;
+    try { mkdirSync(dir, { recursive: true }); accessSync(dir, constants.W_OK); } catch { canLock = false; }
+    const lock = join(dir, `.lock-${rec.repo.replace("/", "_")}__${n}`);
+    const token = `${process.pid}.${randomBytes(4).toString("hex")}`;
+    let got = !canLock;
+    for (let i = 0; i < 50 && !got; i++) {
+      try { mkdirSync(lock); writeFileSync(join(lock, "owner"), token); got = true; } catch {
+        let stale = false;
+        try { stale = Date.now() - statSync(lock).mtimeMs > 300000; } catch { /* raced */ }
+        if (stale) { try { renameSync(lock, `${lock}.stale.${token}`); rmSync(`${lock}.stale.${token}`, { recursive: true, force: true }); } catch { /* lost the race */ } }
+        else spawnSync("sleep", ["0.1"]);
+      }
+    }
+    if (!got) { appendFileSync(buf, `${line}\n`); return rec; }
+    const unlock = () => { if (!canLock) return; try { if (readFileSync(join(lock, "owner"), "utf8") === token) rmSync(lock, { recursive: true, force: true }); } catch { /* already gone */ } };
+    // Claim the buffer by renaming it: records appended meanwhile land in a fresh file and are never deleted. Holding
+    // the lock, any other "<buf>.flush.*" is an orphan of a killed emitter: fold it in.
+    const claimed = `${buf}.flush.${token}`;
+    let pending = [line];
+    try {
+      if (existsSync(buf)) renameSync(buf, claimed);
+      for (const f of readdirSync(dir)) {
+        const full = join(dir, f);
+        if (f.startsWith(`${basename(buf)}.flush.`) && full !== claimed) { appendFileSync(claimed, readFileSync(full, "utf8")); rmSync(full, { force: true }); }
+      }
+      if (existsSync(claimed)) pending = [...readFileSync(claimed, "utf8").split("\n").filter(Boolean), line];
+    } catch { /* nothing claimed */ }
+    try {
+      upsert(rec.repo, n, pending);
+      rmSync(claimed, { force: true });
+    } catch {
+      try {
+        if (existsSync(claimed)) { appendFileSync(buf, readFileSync(claimed, "utf8")); rmSync(claimed, { force: true }); }
+        appendFileSync(buf, `${line}\n`);
+      } catch { /* lost record costs completeness only */ }
+    } finally { unlock(); }
+    return rec;
+  } catch {
+    return null;
+  }
+}

package/bin/engine/telemetry.test.mjs

@@ -0,0 +1,120 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { chmodSync, existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { buildRecord, emit } from "./telemetry.mjs";
+
+let td; let saved;
+const KEYS = ["FORGE_TELEMETRY", "FORGE_TELEMETRY_GH", "FORGE_TELEMETRY_BUFFER_DIR", "FORGE_TELEMETRY_MAX_CHARS", "FORGE_REPO", "FORGE_ISSUE", "FORGE_PR", "FORGE_RUN", "FORGE_PHASE", "TD"];
+
+// Stub gh: lists $TD/comments.json, records the last PATCH/POST body in $TD/patched|posted, logs calls.
+function stubGh(fail = false) {
+  const p = join(td, "gh");
+  writeFileSync(p, `#!/usr/bin/env bash
+echo "$*" >> "$TD/calls"
+${fail ? "exit 1" : ""}
+case "$*" in
+  "api --paginate "*) if [ -f "$TD/comments.json" ]; then cat "$TD/comments.json"; else echo '[]'; fi ;;
+  "api -X PATCH"*) b="\${@: -1}"; printf '%s' "\${b#body=}" > "$TD/patched" ;;
+  "api -X POST"*) b="\${@: -1}"; printf '%s' "\${b#body=}" > "$TD/posted" ;;
+esac
+`);
+  chmodSync(p, 0o755);
+  process.env.FORGE_TELEMETRY_GH = p;
+}
+const setComments = (bodies) => writeFileSync(join(td, "comments.json"),
+  JSON.stringify(bodies.map((b, i) => ({ id: 100 + i, body: b, user: { type: "Bot" }, author_association: "NONE" }))));
+
+beforeEach(() => {
+  saved = Object.fromEntries(KEYS.map((k) => [k, process.env[k]]));
+  td = mkdtempSync(join(tmpdir(), "tel-"));
+  Object.assign(process.env, { TD: td, FORGE_TELEMETRY_BUFFER_DIR: join(td, "buf"), FORGE_REPO: "o/r", FORGE_ISSUE: "5" });
+  for (const k of ["FORGE_TELEMETRY", "FORGE_PR", "FORGE_RUN", "FORGE_PHASE", "FORGE_TELEMETRY_MAX_CHARS"]) delete process.env[k];
+});
+afterEach(() => {
+  for (const k of KEYS) { if (saved[k] === undefined) delete process.env[k]; else process.env[k] = saved[k]; }
+  rmSync(td, { recursive: true, force: true });
+});
+
+describe("telemetry emitter (node twin)", () => {
+  it("builds the shared record shape with null context and typed payload", () => {
+    const r = buildRecord("diff_size", { lines: "10", excluded: 0, threshold: 0, result: "OK", bad: "a`b\nc" });
+    assert.deepEqual(Object.keys(r).slice(0, 9), ["v", "ts", "forge_version", "repo", "issue", "pr", "run", "phase", "event"]);
+    assert.equal(r.v, 1); assert.equal(r.issue, 5); assert.equal(r.pr, null); assert.equal(r.run, null);
+    assert.equal(r.lines, 10); assert.equal(r.result, "OK"); assert.equal(r.bad, "a_b c");
+    assert.match(r.forge_version, /^\d+\.\d+\.\d+/);
+  });
+
+  it("drops reserved and malformed keys", () => {
+    const r = buildRecord("x", { repo: "evil", "a b": 1, ok: 1 });
+    assert.equal(r.repo, "o/r"); assert.equal(r.ok, 1); assert.equal("a b" in r, false);
+  });
+
+  it("creates then upserts one trusted comment", () => {
+    stubGh();
+    emit("ci_gate", { result: "PASS", rc: 0, checks: 3 });
+    const posted = readFileSync(join(td, "posted"), "utf8");
+    assert.match(posted, /^<!-- FORGE:TELEMETRY v1 -->\n```jsonl\n\{.*"event":"ci_gate".*\}\n```$/);
+    setComments([posted]);
+    emit("liveness", { decision: "DEFER", why: "lease" });
+    const patched = readFileSync(join(td, "patched"), "utf8");
+    assert.equal(patched.split("\n").filter((l) => l.startsWith("{")).length, 2);
+    assert.deepEqual(existsSync(join(td, "buf")) ? readdirSync(join(td, "buf")) : [], []);
+  });
+
+  it("ignores an untrusted telemetry comment", () => {
+    stubGh();
+    writeFileSync(join(td, "comments.json"), JSON.stringify([{ id: 1, body: "<!-- FORGE:TELEMETRY v1 -->\n```jsonl\n```", user: { type: "User" }, author_association: "NONE" }]));
+    emit("ci_gate", { result: "PASS" });
+    assert.ok(existsSync(join(td, "posted")));
+    assert.equal(existsSync(join(td, "patched")), false);
+  });
+
+  it("rolls over to part=N near the size limit", () => {
+    stubGh();
+    process.env.FORGE_TELEMETRY_MAX_CHARS = "300";
+    setComments(["<!-- FORGE:TELEMETRY v1 -->\n```jsonl\n" + '{"a":"' + "x".repeat(250) + '"}\n```']);
+    emit("ci_gate", { result: "PASS" });
+    assert.match(readFileSync(join(td, "posted"), "utf8"), /^<!-- FORGE:TELEMETRY v1 part=2 -->/);
+  });
+
+  it("buffers on a failed write and flushes on the next emit", () => {
+    stubGh(true);
+    assert.doesNotThrow(() => emit("diff_size", { lines: 1 }));
+    const files = readdirSync(join(td, "buf"));
+    assert.deepEqual(files, ["o_r__5.jsonl"]);
+    stubGh(false);
+    emit("diff_size", { lines: 2 });
+    const posted = readFileSync(join(td, "posted"), "utf8");
+    assert.equal(posted.split("\n").filter((l) => l.startsWith("{")).length, 2);
+    assert.equal(existsSync(join(td, "buf", "o_r__5.jsonl")), false);
+  });
+
+  it("never throws with an unwritable buffer dir and no gh", () => {
+    process.env.FORGE_TELEMETRY_GH = "/nonexistent/gh";
+    writeFileSync(join(td, "afile"), "x");
+    process.env.FORGE_TELEMETRY_BUFFER_DIR = join(td, "afile", "buf"); // parent is a file: mkdir fails
+    assert.doesNotThrow(() => emit("diff_size", { lines: 1 }));
+  });
+
+  it("honours FORGE_TELEMETRY=off and drops records with no target", () => {
+    stubGh();
+    process.env.FORGE_TELEMETRY = "off";
+    assert.equal(emit("ci_gate", { result: "PASS" }), null);
+    assert.equal(existsSync(join(td, "calls")), false);
+    delete process.env.FORGE_TELEMETRY; delete process.env.FORGE_ISSUE;
+    assert.equal(emit("ci_gate", { result: "PASS" }), null);
+  });
+
+  it("shell and node emitters produce the same keys", () => {
+    process.env.FORGE_PR = "9"; process.env.FORGE_RUN = "r1"; process.env.FORGE_PHASE = "build";
+    const sh = spawnSync("bash", ["-c", `. "${join(import.meta.dirname, "..", "..", "scripts", "lib", "telemetry.sh")}"; _forge_tel_record diff_size lines=10 result=OK`], { encoding: "utf8", env: process.env });
+    const a = JSON.parse(sh.stdout); const b = buildRecord("diff_size", { lines: 10, result: "OK" });
+    assert.deepEqual(Object.keys(a), Object.keys(b));
+    for (const k of Object.keys(a)) if (k !== "ts" && k !== "eid") assert.deepEqual(a[k], b[k], k);
+  });
+});

package/bin/engine-cli.mjs

@@ -13,6 +13,7 @@ import { runIssue, DEFAULT_MAX_ATTEMPTS, sanitizeLeaseHost } from "./engine.mjs"
 import { makeProjector } from "./engine/projector.mjs";
 import { readLog, deriveState } from "./engine/runlog.mjs";
 import { assertOpenCodeNativeRuntime } from "./runner.mjs";
+import { makeEmitTelemetry } from "./engine/telemetry-seam.mjs";
 
 /**
  * Workflow labels that mark an issue as "in the pipeline" (not yet terminal).
@@ -77,8 +78,16 @@ export function runDir() { return join(homedir(), ".forge", "runs"); }
 export function aggregateUsage(events) {
   let found = false;
   const total = { input_tokens: 0, output_tokens: 0, cache_creation_input_tokens: 0, cache_read_input_tokens: 0 };
+  // forge#3696: PHASE_COMMIT.usage is cumulative over all attempts, so summing it with
+  // PHASE_FAILED would double count. For a phase that has PHASE_ATTEMPT_USAGE events,
+  // sum ONLY those; otherwise (old logs) fall back to the legacy COMMIT + FAILED sum.
+  const attemptPhases = new Set(events.filter((e) => e.event === "PHASE_ATTEMPT_USAGE").map((e) => e.phase));
   for (const e of events) {
-    if (e.event !== "PHASE_COMMIT" && e.event !== "PHASE_FAILED") continue;
+    if (e.event === "PHASE_ATTEMPT_USAGE") {
+      // counted as-is (usage null => nothing to add)
+    } else if (e.event === "PHASE_COMMIT" || e.event === "PHASE_FAILED") {
+      if (attemptPhases.has(e.phase)) continue;
+    } else continue;
     if (!e.usage || typeof e.usage !== "object") continue;
     found = true;
     total.input_tokens += e.usage.input_tokens ?? 0;
@@ -393,6 +402,8 @@ export async function runFromCli(argv, deps = {}) {
     ...(repo ? { repo } : {}),
     runner: (await import("./runner.mjs")).runCommand, now: () => Date.now(),
     onProgress,
+    // forge#3835: phase_attempt / run_terminal records reach GitHub so `forgedock stats` works from any machine.
+    emitTelemetry: deps.emitTelemetry ?? makeEmitTelemetry({ repo }),
     // Only forwarded when explicitly provided — omitting them preserves
     // runIssue's/runner.mjs's existing defaults (forge#2028).
     ...(backend ? { backend } : {}),
@@ -409,6 +420,11 @@ export async function runFromCli(argv, deps = {}) {
     console.log(res.detail ?? "run is not retryable");
     return res;
   }
+  // forge#3932: refused before any state write (open or unreadable **Depends on**); nothing ran.
+  if (res.terminalReason === "dependency-open" || res.terminalReason === "dependency-unreadable") {
+    console.log(res.detail ?? "run refused: dependency check");
+    return res;
+  }
   // forge#2175: a non-success termination previously printed nothing beyond
   // the bare reason above — the actual failing phase/attempt/reason was only
   // recoverable by manually reading ~/.forge/runs/{issue}.jsonl and then the