@mmerterden/multi-agent-pipeline 20.27.2 → 20.29.0

package/pipeline/scripts/usage-register-beacon.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * usage-register-beacon.mjs  -  tell the reporting site that registration failed.
+ *
+ * A machine whose registration fails sends nothing else, so whoever runs the
+ * reporting site cannot see that the person tried at all. This sends one small
+ * report to `<register URL>/failure`: { u, v, reason, os }. `u` is the login
+ * registration used (proven or declared), `v` the installed pipeline version,
+ * `reason` one word from REASONS, `os` darwin when known. Nothing else: no
+ * token, no header beyond Content-Type, no host name, no failure text.
+ *
+ * usage-register.mjs starts it detached once a registration ends in a failure
+ * the person did not choose, so it never blocks or fails the caller. It sends
+ * at most once per (reason, version) per day; a report that was not delivered
+ * is tried again on the next failed registration. The state lives in
+ * `~/.claude/logs/multi-agent/usage-register-beacon.json` and holds no secret.
+ *
+ * Usage (internal): MULTI_AGENT_REGISTER_BEACON='<json>' node usage-register-beacon.mjs
+ *
+ * @module pipeline/scripts/usage-register-beacon
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { postJson } from "./_http-post.mjs";
+
+export const BEACON_FILE = "usage-register-beacon.json";
+export const BEACON_TIMEOUT_MS = 3000;
+export const BEACON_ENV = "MULTI_AGENT_REGISTER_BEACON";
+
+export const REASONS = Object.freeze([
+  "endpoint-unreachable",
+  "tls-untrusted",
+  "proxy-refused",
+  "timeout",
+  "redirected",
+  "not-collaborator",
+  "gh-account-mismatch",
+  "proof-rejected",
+  "proof-required",
+  "no-proof",
+  "rate-limited",
+  "server-error",
+  "credential-store",
+  "prefs-write",
+  "other",
+]);
+
+const LOGIN_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,38}$/;
+const VERSION_RE = /^v?\d{1,5}\.\d{1,5}\.\d{1,5}(-[0-9A-Za-z.-]{1,24})?$/;
+
+const TLS_FETCH =
+  /CERT|SELF_SIGNED|UNABLE_TO_GET_ISSUER|UNABLE_TO_VERIFY|DEPTH_ZERO|ERR_TLS|ERR_SSL|EPROTO/;
+const TLS_CURL = new Set([35, 51, 53, 54, 58, 59, 60, 64, 66, 77, 80, 82, 83, 90, 91]);
+const PROXY_CURL = new Set([5, 56, 97]);
+
+function curlExit(failure) {
+  const m = /^curl-exit-(\d+)$/.exec(String(failure ?? ""));
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * The reason for a request that reached no HTTP answer, from the fetch cause
+ * and curl's exit code (_http-post.mjs). curl is asked second and honours the
+ * proxy and the system trust store, so its verdict is read first.
+ */
+export function transportReason(fetchFailure, curlFailure) {
+  const exit = curlExit(curlFailure);
+  if (exit !== null && PROXY_CURL.has(exit)) return "proxy-refused";
+  if (exit !== null && TLS_CURL.has(exit)) return "tls-untrusted";
+  if (exit === 28 || fetchFailure === "timeout") return "timeout";
+  if (TLS_FETCH.test(String(fetchFailure ?? ""))) return "tls-untrusted";
+  return "endpoint-unreachable";
+}
+
+/** The reason for an HTTP answer that issued no token. */
+export function httpReason(status, code) {
+  if (code === "login_mismatch") return "gh-account-mismatch";
+  if (code === "not_collaborator") return "not-collaborator";
+  if (code === "proof_required") return "proof-required";
+  if (status >= 300 && status < 400) return "redirected";
+  if (status === 401) return "proof-rejected";
+  if (status === 403) return "not-collaborator";
+  if (status === 407) return "proxy-refused";
+  if (status === 429) return "rate-limited";
+  if (status >= 500) return "server-error";
+  return "other";
+}
+
+/** The failure URL next to the register URL. */
+export function beaconUrl(registerUrl) {
+  return `${String(registerUrl).replace(/\/+$/, "")}/failure`;
+}
+
+/** The installed pipeline version: the host's stamp, else the package next to this script. */
+export function pipelineVersion(home = homedir()) {
+  for (const root of [".claude", ".copilot", ".codex"]) {
+    try {
+      const v = readFileSync(join(home, root, ".pipeline-version"), "utf8").trim();
+      if (VERSION_RE.test(v)) return v.replace(/^v/, "");
+    } catch {
+      /* no stamp for this host */
+    }
+  }
+  try {
+    const v = JSON.parse(
+      readFileSync(join(import.meta.dirname, "..", "..", "package.json"), "utf8"),
+    ).version;
+    if (typeof v === "string" && VERSION_RE.test(v)) return v.replace(/^v/, "");
+  } catch {
+    /* not inside a package */
+  }
+  return null;
+}
+
+/** The exact body sent, or null when any field would be refused. */
+export function beaconBody({ login, version, reason, os = process.platform }) {
+  if (typeof login !== "string" || !LOGIN_RE.test(login)) return null;
+  if (typeof version !== "string" || !VERSION_RE.test(version)) return null;
+  if (!REASONS.includes(reason)) return null;
+  const body = { u: login, v: version.replace(/^v/, ""), reason };
+  if (os === "darwin") body.os = os;
+  return body;
+}
+
+export function beaconStatePath(home = homedir()) {
+  return join(home, ".claude", "logs", "multi-agent", BEACON_FILE);
+}
+
+function today(now) {
+  return new Date(now).toISOString().slice(0, 10);
+}
+
+export function readBeaconState(home = homedir()) {
+  try {
+    const j = JSON.parse(readFileSync(beaconStatePath(home), "utf8"));
+    return j && typeof j === "object" && !Array.isArray(j) ? j : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeBeaconState(home, state) {
+  const target = beaconStatePath(home);
+  const tmp = `${target}.${process.pid}.tmp`;
+  try {
+    if (!existsSync(join(home, ".claude"))) return;
+    mkdirSync(join(home, ".claude", "logs", "multi-agent"), { recursive: true });
+    writeFileSync(tmp, JSON.stringify(state) + "\n", { mode: 0o600 });
+    renameSync(tmp, target);
+  } catch {
+    /* logs dir unwritable - never break the caller */
+  }
+}
+
+/** Was this (reason, version) already delivered today? */
+export function alreadySent(state, body, now = Date.now()) {
+  return state?.sent?.[`${body.reason}@${body.v}`] === today(now);
+}
+
+/**
+ * Send one beacon unless the same (reason, version) was delivered today.
+ * Resolves to { outcome: "sent" | "failed" | "duplicate" | "invalid", status? };
+ * never throws.
+ */
+export async function sendRegisterBeacon({
+  home = homedir(),
+  url,
+  login,
+  version = pipelineVersion(home),
+  reason,
+  os = process.platform,
+  now = Date.now(),
+  post = postJson,
+  timeoutMs = BEACON_TIMEOUT_MS,
+}) {
+  const body = beaconBody({ login, version, reason, os });
+  if (!body || typeof url !== "string" || !url) return { outcome: "invalid" };
+  const state = readBeaconState(home);
+  if (alreadySent(state, body, now)) return { outcome: "duplicate" };
+  let r;
+  try {
+    r = await post({ url, headers: {}, body: JSON.stringify(body), timeoutMs });
+  } catch {
+    r = { failure: "error" };
+  }
+  const delivered = !r.failure && r.status >= 200 && r.status < 300;
+  const day = today(now);
+  const sent = Object.fromEntries(
+    Object.entries(state.sent && typeof state.sent === "object" ? state.sent : {}).filter(
+      ([, d]) => d === day,
+    ),
+  );
+  if (delivered) sent[`${body.reason}@${body.v}`] = day;
+  const last = {
+    t: new Date(now).toISOString(),
+    reason: body.reason,
+    version: body.v,
+    outcome: delivered ? "sent" : "failed",
+  };
+  if (r.failure) last.cause = String(r.failure).slice(0, 40);
+  else last.status = r.status;
+  writeBeaconState(home, { sent, last });
+  return delivered ? { outcome: "sent", status: r.status } : { outcome: "failed", ...last };
+}
+
+function isEntrypoint() {
+  const arg = process.argv[1];
+  if (!arg) return false;
+  try {
+    return import.meta.url === pathToFileURL(arg).href;
+  } catch {
+    return false;
+  }
+}
+
+function payloadFromEnv() {
+  try {
+    return JSON.parse(process.env[BEACON_ENV] || "null");
+  } catch {
+    return null;
+  }
+}
+
+if (isEntrypoint()) {
+  const payload = payloadFromEnv();
+  if (payload && typeof payload === "object" && existsSync(payload.home || homedir())) {
+    sendRegisterBeacon({
+      home: payload.home || homedir(),
+      url: payload.url,
+      login: payload.login,
+      reason: payload.reason,
+    }).finally(() => {
+      process.exitCode = 0;
+    });
+  }
+}

package/pipeline/scripts/usage-register.mjs

@@ -52,7 +52,16 @@
  * @module pipeline/scripts/usage-register
  */
 
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { postJson as postHttp } from "./_http-post.mjs";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { spawn, spawnSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { join } from "node:path";
@@ -70,6 +79,7 @@ import {
   sshKeygenBin,
 } from "./usage-identity.mjs";
 import { lockTimeoutFrom, updateJsonFileSync } from "../lib/json-file-lock.mjs";
+import { BEACON_ENV, beaconUrl, httpReason, transportReason } from "./usage-register-beacon.mjs";
 
 const DEFAULT_ENDPOINT = "https://mmerterden.com/api/usage/ingest";
 const BUILT_IN_HOSTS = ["mmerterden.com"];
@@ -196,30 +206,39 @@ export function registerUrlAllowed(url, trustedHosts = []) {
   return trusted.has(u.hostname.toLowerCase());
 }
 
+// Transport goes through _http-post.mjs, which retries a connection-level
+// failure through curl (proxy variables, system trust store). The failure text
+// keeps both causes so a blocked corporate network is diagnosable.
 async function postJson(url, body, bearer = null) {
-  const ctrl = new AbortController();
-  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
-  const headers = { "Content-Type": "application/json" };
-  if (bearer) headers.Authorization = `Bearer ${bearer}`;
-  try {
-    const res = await fetch(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(body),
-      redirect: "error",
-      signal: ctrl.signal,
-    });
-    const json = await res.json().catch(() => null);
-    return { res, json, failure: null };
-  } catch (e) {
+  const headers = bearer ? { Authorization: `Bearer ${bearer}` } : {};
+  const r = await postHttp({ url, headers, body: JSON.stringify(body), timeoutMs: TIMEOUT_MS });
+  if (r.failure) {
+    const causes = [r.fetchFailure && `fetch ${r.fetchFailure}`, `curl ${r.failure}`]
+      .filter(Boolean)
+      .join(", ");
+    const what = r.fetchFailure === "timeout" ? "endpoint timed out" : "endpoint unreachable";
     return {
       res: null,
       json: null,
-      failure: e?.name === "AbortError" ? "endpoint timed out" : "endpoint unreachable",
+      failure: `${what} (${causes})`,
+      reason: transportReason(r.fetchFailure, r.failure),
     };
-  } finally {
-    clearTimeout(timer);
   }
+  if (r.status >= 300 && r.status < 400) {
+    return {
+      res: null,
+      json: null,
+      failure: `endpoint redirected (${r.status})`,
+      reason: "redirected",
+    };
+  }
+  let json = null;
+  try {
+    json = JSON.parse(r.body);
+  } catch {
+    /* non-JSON answer: the status alone decides */
+  }
+  return { res: { ok: r.status >= 200 && r.status < 300, status: r.status }, json, failure: null };
 }
 
 const SSH_REFUSALS = {
@@ -265,11 +284,16 @@ function refusal(status, json, body, method) {
 }
 
 async function requestToken(url, body, proof, method) {
-  const { res, json, failure } = await postJson(url, body, proof);
-  if (failure) return { token: null, why: failure };
+  const { res, json, failure, reason } = await postJson(url, body, proof);
+  if (failure) return { token: null, why: failure, reason };
   if (!res.ok) {
     const code = typeof json?.code === "string" ? json.code : null;
-    return { token: null, code, why: refusal(res.status, json, body, method) };
+    return {
+      token: null,
+      code,
+      why: refusal(res.status, json, body, method),
+      reason: httpReason(res.status, code),
+    };
   }
   if (json?.accepted === false)
     return { token: null, declined: true, why: "the endpoint declined this login" };
@@ -277,7 +301,7 @@ async function requestToken(url, body, proof, method) {
   const pinnedLogin = typeof json?.u === "string" && json.u.trim() ? json.u.trim() : null;
   return token
     ? { token, why: null, login: pinnedLogin }
-    : { token: null, why: "endpoint returned no token" };
+    : { token: null, why: "endpoint returned no token", reason: "other" };
 }
 
 /**
@@ -323,20 +347,26 @@ export function challengeUrl(url) {
 
 async function requestTokenWithSsh(url, body, key) {
   const ch = await postJson(challengeUrl(url), { u: body.u });
-  if (ch.failure) return { token: null, why: ch.failure };
+  if (ch.failure) return { token: null, why: ch.failure, reason: ch.reason };
   if (!ch.res.ok) {
     if (ch.res.status === 404 || ch.res.status === 405) {
       return {
         token: null,
         why: `the endpoint does not accept an SSH key as proof yet (challenge answered ${ch.res.status})`,
+        reason: "other",
       };
     }
-    return { token: null, why: refusal(ch.res.status, ch.json, body, "ssh") };
+    const code = typeof ch.json?.code === "string" ? ch.json.code : null;
+    return {
+      token: null,
+      why: refusal(ch.res.status, ch.json, body, "ssh"),
+      reason: httpReason(ch.res.status, code),
+    };
   }
   const challenge = typeof ch.json?.challenge === "string" ? ch.json.challenge : "";
   const namespace = typeof ch.json?.namespace === "string" ? ch.json.namespace : "";
   if (!challenge || !/^[A-Za-z0-9@._-]{1,128}$/.test(namespace)) {
-    return { token: null, why: "the endpoint returned no usable SSH challenge" };
+    return { token: null, why: "the endpoint returned no usable SSH challenge", reason: "other" };
   }
   const signature = sshSign(key, namespace, challenge);
   if (!signature) {
@@ -344,6 +374,7 @@ async function requestTokenWithSsh(url, body, key) {
     return {
       token: null,
       why: `could not sign with the SSH key ${shown} (it needs a passphrase and is not in ssh-agent); run \`ssh-add ${shown}\`, then retry with --refresh`,
+      reason: "no-proof",
     };
   }
   return requestToken(url, { ...body, ssh: { challenge, signature } }, null, "ssh");
@@ -538,6 +569,57 @@ function reportingStaysOff(status, detail) {
   return status === "skipped" && !QUIET_REASONS.has(detail);
 }
 
+export const LAST_REGISTER_FILE = "usage-last-register.json";
+
+/**
+ * Overwrites the record of the most recent registration attempt. Registration
+ * runs quietly from setup, update and Phase 0, so this file is where a machine
+ * that never registers shows why; doctor reads it. It holds no token.
+ */
+function recordRegister(home, status, detail) {
+  const dir = join(home, ".claude", "logs", "multi-agent");
+  const target = join(dir, LAST_REGISTER_FILE);
+  const tmp = `${target}.${process.pid}.tmp`;
+  try {
+    mkdirSync(dir, { recursive: true });
+    const entry = {
+      t: new Date().toISOString(),
+      status,
+      detail: String(detail ?? "").slice(0, 300),
+    };
+    writeFileSync(tmp, JSON.stringify(entry) + "\n", { mode: 0o600 });
+    renameSync(tmp, target);
+  } catch {
+    /* logs dir unwritable - never break the caller */
+  }
+}
+
+/**
+ * Report a failed registration to the site, detached so it never delays or
+ * fails the caller (usage-register-beacon.mjs). Only for a failure the person
+ * did not choose, never on a dry run or for an opted-out machine, only under a
+ * login this run had, and only to a register URL the proof may go to.
+ */
+function sendFailureBeacon({ home, prefsPath, login, reason, dryRun }) {
+  if (dryRun || !reason || typeof login !== "string" || !LOGIN_RE.test(login)) return;
+  const usageLog = readJson(prefsPath)?.global?.usageLog || {};
+  if (usageLog.optOut === true) return;
+  const url = registerUrl(usageLog.endpoint);
+  if (!registerUrlAllowed(url, usageLog.trustedHosts || [])) return;
+  try {
+    spawn(process.execPath, [join(import.meta.dirname, "usage-register-beacon.mjs")], {
+      detached: true,
+      stdio: "ignore",
+      env: {
+        ...process.env,
+        [BEACON_ENV]: JSON.stringify({ home, url: beaconUrl(url), login, reason }),
+      },
+    }).unref();
+  } catch {
+    // reporting never fails the caller
+  }
+}
+
 async function main(argv) {
   const opts = {
     quiet: false,
@@ -566,7 +648,16 @@ async function main(argv) {
     if (!opts.quiet) process.stdout.write(`${line}\n`);
   };
   const identity = { login: undefined };
-  const done = (status, detail) => {
+  const beacon = { login: null };
+  const done = (status, detail, reason = null) => {
+    if (!opts.dryRun) recordRegister(HOME, status, detail);
+    sendFailureBeacon({
+      home: HOME,
+      prefsPath,
+      login: beacon.login,
+      reason,
+      dryRun: opts.dryRun,
+    });
     if (opts.json) {
       const needsPersonalAccount = personalAccountMissing(readJson(prefsPath), identity.login);
       process.stdout.write(`${JSON.stringify({ status, detail, needsPersonalAccount })}\n`);
@@ -602,7 +693,8 @@ async function main(argv) {
     }
     if (!opts.dryRun && !declareLogin(prefsPath, name)) {
       say("  -> operational reporting: could not write preferences");
-      return done("unavailable", "prefs write failed");
+      beacon.login = name;
+      return done("unavailable", "prefs write failed", "prefs-write");
     }
     opts.refresh = true;
   }
@@ -629,6 +721,7 @@ async function main(argv) {
     who = { login: declared, method: "claim", key: null, reason: "declared by the person" };
   }
   identity.login = who.login;
+  beacon.login = who.login || null;
   const decision = decideRegistration(current, {
     hasStoredToken: has,
     forFeedback: opts.feedback,
@@ -649,7 +742,8 @@ async function main(argv) {
           return done("enabled", decision.reason);
         }
         say("  -> operational reporting: could not write preferences");
-        return done("unavailable", "prefs write failed");
+        beacon.login = beacon.login || cu.registeredAs || null;
+        return done("unavailable", "prefs write failed", "prefs-write");
       }
     }
     if (
@@ -702,11 +796,11 @@ async function main(argv) {
           ? `the git credential helper no longer returns a GitHub token for ${user}; retry with --refresh`
           : `gh has no token for ${user}; run \`gh auth login\` for that account`;
       say(`  -> operational reporting left off (${why})`);
-      return done("unavailable", why);
+      return done("unavailable", why, "no-proof");
     }
     result = await requestToken(url, { u: user, c: host }, proof, who.method || "gh");
   }
-  const { token, why, declined, code, login: pinnedLogin } = result;
+  const { token, why, declined, code, reason, login: pinnedLogin } = result;
   if (who.method === "claim" && ["not_collaborator", "proof_required"].includes(code))
     declareLogin(prefsPath, null);
   else if (who.method === "claim" && !token && !declined)
@@ -717,7 +811,7 @@ async function main(argv) {
   }
   if (!token) {
     say(`  -> operational reporting left off (${why})`);
-    return done("unavailable", why);
+    return done("unavailable", why, reason || "other");
   }
 
   const optedOut = prefs.global?.usageLog?.optOut === true;
@@ -729,7 +823,8 @@ async function main(argv) {
   });
   if (set.status !== 0) {
     say("  -> operational reporting left off (the credential store refused the token)");
-    return done("unavailable", "credential store write failed");
+    beacon.login = pinnedLogin || user;
+    return done("unavailable", "credential store write failed", "credential-store");
   }
   persistPrefs(prefsPath, entry, {
     enableTelemetry: !optedOut,

package/pipeline/scripts/usage-report.mjs

@@ -22,6 +22,7 @@
  * Usage:
  *   node usage-report.mjs --state /path/to/agent-state.json [--event <kind>]
  *   node usage-report.mjs --task-id PROJ-123 [--phase N] [--event <kind>]
+ *   node usage-report.mjs --task-id PROJ-123 --print-state   (prints the run's agent-state.json path)
  *
  *   node usage-report.mjs --lifecycle   (report the installed version when it changed)
  *   --event  phase | completed | halted | parked  (default: derived from state)
@@ -29,6 +30,7 @@
  * @module pipeline/scripts/usage-report
  */
 
+import { postJson } from "./_http-post.mjs";
 import {
   readFileSync,
   existsSync,
@@ -86,6 +88,7 @@ function parseArgs(argv) {
     else if (a === "--event") out.event = argv[++i];
     else if (a === "--dry-run") out.dryRun = true;
     else if (a === "--lifecycle") out.lifecycle = true;
+    else if (a === "--print-state") out.printState = true;
   }
   return out;
 }
@@ -737,40 +740,31 @@ function hostOf(url) {
  * instead, so a moved endpoint is visible rather than silent.
  */
 async function post(endpoint, token, event) {
-  const ctrl = new AbortController();
-  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+  const r = await postJson({
+    url: endpoint,
+    headers: { "X-Usage-Token": token },
+    body: JSON.stringify(event),
+    timeoutMs: TIMEOUT_MS,
+  });
+  const via = r.fetchFailure ? { transport: r.transport, fetchFailure: r.fetchFailure } : {};
+  if (r.failure) {
+    return { outcome: "failed", reason: codeOf(String(r.failure), 40), ...via };
+  }
+  if (r.status >= 300 && r.status < 400) {
+    return { outcome: "redirected", status: r.status, location: hostOf(r.location || ""), ...via };
+  }
+  if (r.status < 200 || r.status >= 300) return { outcome: "rejected", status: r.status, ...via };
+  let body = null;
   try {
-    const res = await fetch(endpoint, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "X-Usage-Token": token,
-      },
-      body: JSON.stringify(event),
-      redirect: "manual",
-      signal: ctrl.signal,
-    });
-    if (res.status >= 300 && res.status < 400) {
-      return {
-        outcome: "redirected",
-        status: res.status,
-        location: hostOf(res.headers.get("location") || ""),
-      };
-    }
-    if (!res.ok) return { outcome: "rejected", status: res.status };
-    let body = null;
-    try {
-      body = await res.json();
-    } catch {
-      /* a 2xx without a JSON body is still a delivery */
-    }
-    return { outcome: body?.accepted === false ? "not-accepted" : "accepted", status: res.status };
-  } catch (err) {
-    const reason = ctrl.signal.aborted ? "timeout" : (err?.cause?.code ?? err?.name ?? "error");
-    return { outcome: "failed", reason: codeOf(String(reason), 40) };
-  } finally {
-    clearTimeout(timer);
+    body = JSON.parse(r.body);
+  } catch {
+    /* a 2xx without a JSON body is still a delivery */
   }
+  return {
+    outcome: body?.accepted === false ? "not-accepted" : "accepted",
+    status: r.status,
+    ...via,
+  };
 }
 
 export const LAST_SEND_FILE = "usage-last-send.json";
@@ -852,6 +846,13 @@ function registeredLogin(prefs) {
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (process.env.MULTI_AGENT_SMOKE && !args.dryRun) return;
+  // Resolving the state path needs no prefs and sends nothing: a shell block
+  // whose $STATE_FILE did not survive from an earlier command gets it back here.
+  if (args.printState) {
+    const path = resolveStatePath(args);
+    if (path) process.stdout.write(`${path}\n`);
+    return;
+  }
   const prefs = resolvePrefs();
   const endpoint = canonicalEndpoint(prefs.endpoint || ENDPOINT_DEFAULT);
 
@@ -883,7 +884,16 @@ async function main() {
   let state = statePath ? readJson(statePath) : null;
 
   if (!state) {
-    if (!args.taskId) return;
+    if (!args.taskId) {
+      // An unset shell variable reaches here as --state "", and a silent return
+      // would make a run that never reports look exactly like one that did.
+      recordSend({
+        ev: EVENT_KINDS.includes(args.event) ? args.event : null,
+        outcome: "skipped",
+        reason: args.state === "" ? "empty-state-path" : "no-state",
+      });
+      return;
+    }
     state = { taskId: args.taskId };
   }
 

package/pipeline/scripts/validate-state.mjs

@@ -16,6 +16,7 @@
 //   - root is not an object
 //   - currentPhase is missing or out of the 0..5 range (resume keys on it)
 //   - phases is present but not an object, or an entry is not an object
+//   - waitingFor names a step resume cannot re-enter
 // Phase status strings are NOT enum-checked: real writers use "completed"
 // alongside the schema's "done", and an odd status does not make a resume
 // unsafe (resume keys on currentPhase, not phase status). Zero deps, same
@@ -32,6 +33,14 @@
 
 import { readFileSync } from "node:fs";
 
+const WAITING_FOR = new Set([
+  "maturity",
+  "user-channels-choice",
+  "local-test",
+  "attended-reply",
+  "question",
+]);
+
 function readInput() {
   const arg = process.argv[2];
   if (!arg) {
@@ -129,6 +138,23 @@ async function main() {
     }
   }
 
+  // waitingFor is the first field resume reads: a value it has no row for, or
+  // a question with nothing to re-ask, leaves the run unable to re-enter.
+  if (s.waitingFor !== undefined && s.waitingFor !== null) {
+    if (!WAITING_FOR.has(s.waitingFor)) {
+      errors.push(
+        `waitingFor must be one of ${[...WAITING_FOR].join(", ")} or null, got ${JSON.stringify(s.waitingFor)}`,
+      );
+    } else if (
+      s.waitingFor === "question" &&
+      (typeof s.pendingQuestion?.stepId !== "string" || !s.pendingQuestion.stepId)
+    ) {
+      errors.push(
+        'waitingFor "question" needs a pendingQuestion with a stepId; a typed wait records "attended-reply"',
+      );
+    }
+  }
+
   if (errors.length > 0) {
     emit({ ok: false, code: 1, errors });
     process.exit(1);