in2-agent-server 0.20260821.185429

package/dist/core/operatorQa.js

@@ -0,0 +1,462 @@
+import { promises as fs } from "node:fs";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { questionsDir } from "./workspace.js";
+import { transcriptUploadEnabled } from "./transcriptUpload.js";
+// OPERATOR Q&A UPLOAD — what each question card asked, and what the operator answered.
+//
+// THE GAP THIS CLOSES. `operator.question_presented` carries `{questionCount}`, which can say a run
+// asked four questions and never which four, nor what came back. The question text lived only in
+// this machine's round files and the answers only in plan.json blockers, so "what did users get
+// asked and what did they say" — across installs, the question a product team actually has — could
+// not be answered from the ledger at all.
+//
+// WHY THIS IS NOT A TELEMETRY EVENT. The event stream is shape-only by contract
+// (`convex/lib/events.ts` allowlists every payload key and admits no prose), and a question card is
+// prose: it is written in the operator's language about their business. Widening that allowlist to
+// carry it would end the shape-only property for every consumer of the stream, permanently. So this
+// takes the route the two existing content channels took — its own endpoint, its own table, its own
+// stated reason — and the shape-only event is left exactly as it was.
+//
+// WHY THE DEFAULT IS HONEST. A card is relayed into the Claude Code chat and answered there, so
+// both halves are ALREADY inside the transcript this install uploads by default, under a consent
+// paragraph that names "the full text of the Claude Code session for that batch, which includes
+// anything either of us pastes into the chat". This route sends no category of content that was not
+// already leaving the machine; it makes an already-uploaded fact queryable rather than buried in a
+// 20 MB blob.
+//
+// That argument is CONDITIONAL, and the condition is enforced below: with transcript upload off,
+// this is off too. An install that asked for "the timings and outcomes without the session text"
+// must not have the session's questions and answers arrive by a different door.
+//
+// FAIL-OPEN, like every other reporting path here: nothing in this module may fail, delay or mask a
+// delivery. Every entry point returns notes instead of throwing.
+/** Bumped when the ROUND FILE layout changes. v1 files are read identically — see readQuestionRounds. */
+export const QUESTIONS_SCHEMA_VERSION = "cc-operator-questions-v2";
+/** Bumped when the WIRE shape changes; the ledger refuses a version it does not know. */
+export const OPERATOR_QA_WIRE_VERSION = 1;
+/**
+ * THE LEDGER'S FIELD CAPS, MIRRORED.
+ *
+ * Every number here is the same number as `LIMITS` in `apps/campfire-launch/convex/operatorQa.ts`,
+ * which is the validator that actually refuses an over-long field — and refuses it with a 400 for
+ * the whole request, at batch close, when the run is over and there is no later attempt.
+ *
+ * Mirroring them on this side moves that refusal to where the card is COMPOSED: `ask_operator`
+ * rejects a 3,000-character option description with a zod error naming the field, at the moment the
+ * model wrote it, when re-composing costs one tool call. Before this the client schemas said
+ * `z.string().min(1)` and the tool description advertised the field as uncapped, so the first news
+ * of a limit arrived as a lost round.
+ *
+ * `operatorQaLimits.test.ts` reads both files and fails if these drift apart.
+ */
+export const WIRE_LIMITS = {
+    questionId: 64,
+    header: 24,
+    question: 4_000,
+    label: 120,
+    description: 2_000,
+    freeText: 4_000
+};
+/**
+ * The CARD's own caps, deliberately stricter than the wire.
+ *
+ * These are composition rules, not storage limits: a 60-character label is what keeps an option
+ * readable as a verdict, and a 12-character header is what fits the chip. The wire would accept
+ * twice each. The cross-app test asserts they stay INSIDE `WIRE_LIMITS` — a card that composes must
+ * always be a card that uploads.
+ */
+export const CARD_LIMITS = {
+    header: 12,
+    label: 60
+};
+/** Ledger counterparts: MAX_QUESTIONS / MAX_OPTIONS / MAX_CHOSEN in convex/operatorQa.ts. */
+export const WIRE_COUNTS = {
+    questionsPerRound: 8,
+    optionsPerQuestion: 8,
+    chosenPerAnswer: 8
+};
+/** The ledger accepts 25 rounds per request (MAX_ROUNDS). A session with more still delivers all. */
+const ROUNDS_PER_REQUEST = 25;
+/**
+ * Mirrors MAX_BODY_BYTES in convex/operatorQa.ts, which measures the raw request text and answers
+ * 413 above it. Counting rounds alone was not enough: 25 rounds of 8 questions at the field caps
+ * above is far over a megabyte, so a pathological session could build a chunk the ledger refuses
+ * whole for a reason no round of it is individually guilty of.
+ */
+const MAX_REQUEST_BYTES = 1024 * 1024;
+/**
+ * The stable address of one question, `r3q2` — round 3, question 2.
+ *
+ * DERIVED from position rather than minted, which is what makes the file-format bump a non-event: a
+ * v1 round file, written before ids existed, yields exactly the ids a v2 file would. Nothing has to
+ * migrate and no reader has to branch on version.
+ */
+export function questionIdFor(round, index) {
+    return `r${round}q${index + 1}`;
+}
+/** Every question in a round, with its id filled in whether or not the file recorded one. */
+export function withQuestionIds(round) {
+    return round.questions.map((question, index) => ({
+        ...question,
+        questionId: question.questionId ?? questionIdFor(round.round, index)
+    }));
+}
+/** ANSWERED once every question has one; PARTIALLY_ANSWERED once at least one does. */
+export function statusFor(questions) {
+    const answered = questions.filter((question) => question.answer !== undefined).length;
+    if (answered === 0)
+        return "PENDING";
+    return answered === questions.length ? "ANSWERED" : "PARTIALLY_ANSWERED";
+}
+const DISABLED_VALUES = new Set(["0", "false", "off", "no"]);
+/**
+ * ON BY DEFAULT, and gated on the superset.
+ *
+ * Two switches, and the order matters. `CC_MCP_TRANSCRIPT_UPLOAD=0` turns this off because the
+ * consent this rides on is the transcript's: the questions and answers are part of the session text
+ * that install declined to send, and routing them out separately would make that decline meaningless.
+ * `CC_MCP_OPERATOR_QA_UPLOAD=0` is the narrower one, for an install content to ship the raw
+ * transcript but not a queryable table of what its operator was asked.
+ *
+ * `CC_MCP_TELEMETRY=0` covers both without appearing here: with no telemetry there is no batch
+ * grant, and the grant is the only way an upload can be attributed to anything.
+ */
+export function operatorQaUploadEnabled(env = process.env) {
+    if (!transcriptUploadEnabled(env))
+        return false;
+    const raw = env.CC_MCP_OPERATOR_QA_UPLOAD?.trim().toLowerCase();
+    return raw === undefined || raw === "" ? true : !DISABLED_VALUES.has(raw);
+}
+let announced = false;
+/** Test seam — the once-guard is module state, and a suite asserting the line needs it reset. */
+export function resetOperatorQaAnnouncementForTests() {
+    announced = false;
+}
+const defaultLog = (line) => void process.stderr.write(`[cc-mcp] ${line}\n`);
+/**
+ * Say it at startup, in the operator's language, whichever way the switches are set.
+ *
+ * The transcript announcement already says the whole session leaves, so this line is not the first
+ * disclosure of the content — it is the disclosure that the content is also stored in a form
+ * somebody can query, which is a different thing to know and the reason the narrow opt-out exists.
+ */
+export function announceOperatorQa(opts = {}) {
+    if (announced)
+        return;
+    announced = true;
+    const env = opts.env ?? process.env;
+    const write = opts.log ?? defaultLog;
+    if (!transcriptUploadEnabled(env)) {
+        // Deliberately named as a consequence rather than as a second setting to find: an operator who
+        // set the transcript variable has already made this decision and should be told it took effect.
+        write("operator question cards are NOT being uploaded either — CC_MCP_TRANSCRIPT_UPLOAD=0 covers them, because they are part of the session text.");
+        return;
+    }
+    if (!operatorQaUploadEnabled(env)) {
+        write("operator question cards are NOT being uploaded (CC_MCP_OPERATOR_QA_UPLOAD=0). They stay on this machine; the session transcript is unaffected.");
+        return;
+    }
+    write("OPERATOR QUESTION CARDS ARE UPLOADED (the default). Every question you are asked, its options, and the answer you give " +
+        `are sent to ${opts.endpoint ?? "the configured endpoint"} as records IN2 can search — the same words the session transcript already carries. ` +
+        "Set CC_MCP_OPERATOR_QA_UPLOAD=0 to send the transcript without them, or CC_MCP_TRANSCRIPT_UPLOAD=0 to send neither.");
+}
+/** Same host, same grant, different route — derived exactly as the transcript endpoint is. */
+export function operatorQaEndpointFrom(telemetryEndpoint) {
+    try {
+        const url = new URL(telemetryEndpoint);
+        url.pathname = "/api/operator-qa/v1";
+        return url.toString();
+    }
+    catch {
+        return telemetryEndpoint.replace(/\/api\/telemetry\/v\d+$/, "/api/operator-qa/v1");
+    }
+}
+/**
+ * Every round this session recorded, in asked order.
+ *
+ * Tolerant by construction: an unreadable or malformed round file is skipped rather than failing the
+ * sweep, because one bad file must not cost the rounds beside it — this runs at batch close, after
+ * the work, and there is no later attempt.
+ */
+export async function readQuestionRounds(sessionId) {
+    const dir = questionsDir(sessionId);
+    if (!existsSync(dir))
+        return [];
+    let names;
+    try {
+        names = await fs.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const rounds = [];
+    for (const name of names.sort()) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            const parsed = JSON.parse(await fs.readFile(path.join(dir, name), "utf8"));
+            if (!parsed || typeof parsed !== "object")
+                continue;
+            if (!Number.isSafeInteger(parsed.round) || parsed.round < 1)
+                continue;
+            if (!Array.isArray(parsed.questions) || parsed.questions.length === 0)
+                continue;
+            rounds.push(parsed);
+        }
+        catch {
+            // A half-written or hand-edited round file is skipped, not fatal.
+        }
+    }
+    return rounds.sort((a, b) => a.round - b.round);
+}
+/** The wire shape for one round — the local file with its ids materialized and nothing else added. */
+export function wireRound(round) {
+    return {
+        round: round.round,
+        askedAt: round.askedAt,
+        ...(round.answeredAt ? { answeredAt: round.answeredAt } : {}),
+        questions: withQuestionIds(round).map((question) => ({
+            questionId: question.questionId,
+            ...(question.header ? { header: question.header } : {}),
+            question: question.question,
+            ...(question.multiSelect ? { multiSelect: true } : {}),
+            options: (question.options ?? []).map((option) => ({
+                label: option.label,
+                ...(option.description ? { description: option.description } : {}),
+                ...(option.recommended ? { recommended: true } : {})
+            })),
+            ...(question.answer
+                ? {
+                    answer: {
+                        chosenLabels: question.answer.chosenLabels ?? [],
+                        ...(question.answer.freeText ? { freeText: question.answer.freeText } : {}),
+                        ...(question.answer.answeredAt ? { answeredAt: question.answer.answeredAt } : {})
+                    }
+                }
+                : {})
+        }))
+    };
+}
+/**
+ * The first way this round would breach the ledger's caps, or null if it would not.
+ *
+ * Checked HERE so a length can never cost a request. The zod schemas on `ask_operator` already stop
+ * an over-long field being written, but a round file can also be hand-edited, restored from an older
+ * version, or written by a build whose caps differ from the ledger it happens to be pointed at — and
+ * at batch close the only remedy left is to not send the round rather than to lose the ones beside it.
+ */
+export function roundLimitProblem(round) {
+    const questions = round.questions ?? [];
+    if (questions.length > WIRE_COUNTS.questionsPerRound) {
+        return `it has ${questions.length} questions, over the limit of ${WIRE_COUNTS.questionsPerRound}`;
+    }
+    const tooLong = (value, max, field) => value !== undefined && value.length > max ? `${field} is ${value.length} characters, over the limit of ${max}` : null;
+    for (const [index, question] of questions.entries()) {
+        const at = `question ${index + 1}`;
+        const options = question.options ?? [];
+        if (options.length > WIRE_COUNTS.optionsPerQuestion) {
+            return `${at} has ${options.length} options, over the limit of ${WIRE_COUNTS.optionsPerQuestion}`;
+        }
+        const problem = tooLong(question.questionId, WIRE_LIMITS.questionId, `${at} id`) ??
+            tooLong(question.header, WIRE_LIMITS.header, `${at} header`) ??
+            tooLong(question.question, WIRE_LIMITS.question, `${at} text`);
+        if (problem)
+            return problem;
+        for (const [optionIndex, option] of options.entries()) {
+            const optionAt = `${at} option ${optionIndex + 1}`;
+            const optionProblem = tooLong(option.label, WIRE_LIMITS.label, `${optionAt} label`) ??
+                tooLong(option.description, WIRE_LIMITS.description, `${optionAt} description`);
+            if (optionProblem)
+                return optionProblem;
+        }
+        const answer = question.answer;
+        if (!answer)
+            continue;
+        const chosen = answer.chosenLabels ?? [];
+        if (chosen.length > WIRE_COUNTS.chosenPerAnswer) {
+            return `${at} records ${chosen.length} chosen labels, over the limit of ${WIRE_COUNTS.chosenPerAnswer}`;
+        }
+        for (const [labelIndex, label] of chosen.entries()) {
+            const labelProblem = tooLong(label, WIRE_LIMITS.label, `${at} chosen label ${labelIndex + 1}`);
+            if (labelProblem)
+                return labelProblem;
+        }
+        const freeTextProblem = tooLong(answer.freeText, WIRE_LIMITS.freeText, `${at} free text`);
+        if (freeTextProblem)
+            return freeTextProblem;
+    }
+    return null;
+}
+function envelope(rounds) {
+    return JSON.stringify({ schemaVersion: OPERATOR_QA_WIRE_VERSION, rounds });
+}
+/**
+ * Chunks bounded by BOTH caps the ledger enforces — 25 rounds, and a megabyte of request text.
+ *
+ * A single round larger than the whole budget still gets its own chunk rather than being dropped
+ * here: it will be refused on its own, which costs exactly one round, and being refused with the
+ * ledger's own message is more use than a guess made locally.
+ */
+function planChunks(rounds) {
+    const overhead = Buffer.byteLength(envelope([]), "utf8");
+    const chunks = [];
+    let current = [];
+    let bytes = overhead;
+    for (const round of rounds) {
+        const cost = round.bytes + 1; // the comma that will separate it from the previous round
+        if (current.length > 0 && (current.length >= ROUNDS_PER_REQUEST || bytes + cost > MAX_REQUEST_BYTES)) {
+            chunks.push(current);
+            current = [];
+            bytes = overhead;
+        }
+        current.push(round);
+        bytes += cost;
+    }
+    if (current.length > 0)
+        chunks.push(current);
+    return chunks;
+}
+/**
+ * Ship the rounds. The grant is the same batch-scoped credential telemetry uses, so a Q&A record can
+ * only ever be attributed to the batch whose credential sent it — the ledger derives identity from
+ * the grant and ignores anything the client claims.
+ *
+ * Chunked at the ledger's per-request round cap AND its body-size cap, so a pathological session
+ * delivers every round rather than being refused whole. Chunks are independent: rows are keyed on
+ * (batch, round), so a chunk that fails costs only its own rounds.
+ *
+ * ONE BAD ROUND MUST NOT COST ITS CHUNKMATES. The ledger validates a request whole and answers 400
+ * for the first field it dislikes, so a single malformed round used to discard the 24 answered ones
+ * travelling with it — silently, at batch close, with no second attempt. A payload refusal now
+ * re-sends the chunk one round at a time, which turns "25 rounds lost" into "the one round the
+ * ledger actually refused". The retry is deliberately NOT made for network errors or 5xx: those are
+ * not round-specific, and re-sending 25 rounds one at a time against a dead endpoint would only make
+ * a slow close slower.
+ */
+export async function uploadOperatorQa(opts) {
+    const fetchFn = opts.fetchFn ?? fetch;
+    let uploaded = 0;
+    let failed = 0;
+    let reason;
+    // Length-refused before anything is sent, so a 400 for a field size cannot happen at all.
+    const sendable = [];
+    for (const round of opts.rounds) {
+        const problem = roundLimitProblem(round);
+        if (problem !== null) {
+            failed += 1;
+            reason ??= `round ${round.round} exceeds the ledger's limits: ${problem}`;
+            continue;
+        }
+        const body = wireRound(round);
+        sendable.push({ round: round.round, body, bytes: Buffer.byteLength(JSON.stringify(body), "utf8") });
+    }
+    const post = async (chunk) => {
+        try {
+            const res = await fetchFn(opts.endpoint, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${opts.credential}`
+                },
+                body: envelope(chunk.map((round) => round.body)),
+                signal: AbortSignal.timeout(30_000)
+            });
+            if (res.ok)
+                return { ok: true };
+            // The ledger's own message names the field it refused, which is the only useful thing to
+            // print when a client and a server disagree about a shape.
+            const detail = res.status === 400 ? `: ${(await res.text()).slice(0, 200)}` : "";
+            return { ok: false, status: res.status, reason: `HTTP ${res.status}${detail}` };
+        }
+        catch (error) {
+            return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+        }
+    };
+    /** The statuses that mean "this payload", and so the ones worth re-trying a round at a time. */
+    const payloadRefusal = (status) => status === 400 || status === 413;
+    for (const chunk of planChunks(sendable)) {
+        const sent = await post(chunk);
+        if (sent.ok) {
+            uploaded += chunk.length;
+            continue;
+        }
+        if (chunk.length === 1 || !payloadRefusal(sent.status)) {
+            failed += chunk.length;
+            reason ??= sent.reason;
+            continue;
+        }
+        // Deliberately no chunk-level reason recorded here: the per-round attempt below produces the
+        // message naming the round that is actually at fault, which is the one worth reporting.
+        for (const round of chunk) {
+            const retry = await post([round]);
+            if (retry.ok) {
+                uploaded += 1;
+                continue;
+            }
+            failed += 1;
+            reason ??= `round ${round.round}: ${retry.reason ?? "unknown error"}`;
+        }
+    }
+    return { uploaded, failed, ...(reason ? { reason } : {}) };
+}
+/**
+ * THE UNDERCOUNT WARNING — said mechanically, from the round files, not left to a prompt.
+ *
+ * A question round is closed by `record_operator_answers`. But an operator's answer ALSO reaches the
+ * work through `resolve_blocker`, which records it on requirements/<extId>/plan.json with no link
+ * back to the round it came from — and through the chat, which records it nowhere at all. So a run
+ * whose operator answered every question and delivered successfully can still close with rounds
+ * marked PENDING, and it is then indistinguishable from a run that stopped dead at the gate. The
+ * ledger reads `answeredCount: 0` as exactly that meaningful "stopped at the gate" state.
+ *
+ * There is no cheap way to link the two records — one card question can settle three requirements or
+ * none — so the honest move is to stop the reading being certain. Naming the open rounds at close
+ * costs nothing and puts the doubt where the number is read.
+ */
+export function openRoundCaveat(open) {
+    if (open.length === 0)
+        return [];
+    const numbers = open.map((round) => round.round).join(", ");
+    return [
+        `${open.length} question round(s) still open at close (${open.length === 1 ? "round" : "rounds"} ${numbers}) — ` +
+            "if the operator answered through resolve_blocker or in the chat, this batch's Q&A record undercounts what they were asked and told. " +
+            "record_operator_answers is what puts the answer on the round."
+    ];
+}
+/**
+ * The batch-close step: read what this session asked, ship it, and say what happened.
+ *
+ * Returns notes rather than throwing, and reports "nothing to send" as plainly as a failure — a run
+ * that asked no questions and a run whose upload silently did nothing must not look the same.
+ */
+export async function shipOperatorQa(opts) {
+    if (!operatorQaUploadEnabled(opts.env ?? process.env))
+        return [];
+    if (!opts.sessionId)
+        return ["operator Q&A upload skipped: no session bound to this run"];
+    if (!opts.endpoint || !opts.credential) {
+        return ["operator Q&A upload skipped: no batch grant on this install yet"];
+    }
+    const rounds = await readQuestionRounds(opts.sessionId);
+    if (rounds.length === 0)
+        return ["operator Q&A: no question rounds were recorded for this session"];
+    const open = rounds.filter((round) => statusFor(round.questions) === "PENDING");
+    const result = await uploadOperatorQa({
+        endpoint: opts.endpoint,
+        credential: opts.credential,
+        rounds,
+        ...(opts.fetchFn ? { fetchFn: opts.fetchFn } : {})
+    });
+    const notes = [];
+    if (result.uploaded > 0) {
+        notes.push(`operator Q&A uploaded: ${result.uploaded} question round(s)` +
+            (open.length > 0 ? `, ${open.length} of them with no answer recorded` : ""));
+    }
+    if (result.failed > 0) {
+        notes.push(`operator Q&A upload failed for ${result.failed} round(s): ${result.reason ?? "unknown error"}`);
+    }
+    // Last, and independent of how the upload went: the subject is the RECORD, not the transfer.
+    notes.push(...openRoundCaveat(open));
+    return notes;
+}

package/dist/core/orgCallMeter.js

@@ -0,0 +1,178 @@
+// WHERE A WAVE'S ORG TIME ACTUALLY GOES — measured, per phase, in the ledger.
+//
+// THE QUESTION. A Windows run was observed taking up to ~8 minutes per wave against a Mac's ~34s
+// median (.audit/timing-profile.md). Nothing in the ledger could apportion that, so the cause was
+// argued from anecdote.
+//
+// THE PREMISE THAT WAS WRONG, and why this file is not what it first was. The obvious hypothesis is
+// "Windows spawns the `sf` CLI many times and each spawn is expensive". It does not: the whole
+// direct tier spawns `sf` exactly THREE times per wave (retrieve, deploy, destructive deploy — all
+// in applyLoop.ts), `orgRepo.ts` spawns `git` only, and every projection read goes through jsforce
+// via @salesforce/core, already batched at the API cap of 10 with 5 in flight
+// (orgread/salesforceOrgReader.ts). Both "batch the reads" targets were already optimal. A meter
+// that counted only sf spawns would therefore measure the three cheapest events in the wave and
+// miss the ~50 jsforce round-trips a projection actually makes.
+//
+// So this counts BOTH KINDS, tagged by kind, and the remaining hypotheses are the ones the numbers
+// can now separate:
+//   - per-call network latency (jsforce round-trips, steady state)
+//   - process startup — node boot, CLI load, and on Windows an sf.cmd shim resolved to its JS entry
+//     and run under this process's node (see core/spawn.ts)
+//   - on-access AV scanning, which taxes process start and file I/O rather than the network
+//
+// FIRST CALL VS STEADY STATE is split for exactly that reason. A cost that lands entirely on the
+// first call is startup — connection setup, module load, an AV scan of a freshly touched binary. A
+// cost spread evenly across every call is latency. One number cannot tell those apart; two can, and
+// it is the difference between "the org is far away" and "this machine is slow to start things",
+// which have opposite fixes.
+//
+// WHY A MODULE-LEVEL METER AND NOT A PARAMETER THREADED THROUGH. The calls happen across five
+// modules, several behind fail-open helpers with no result channel to carry a measurement back on
+// (`retrievePreImageSource` returns ok/error; the snapshot readers return envelopes). Threading a
+// counter through all of them to serve one telemetry field would put an observability concern into
+// every signature on the read and deploy paths. The meter sits where the calls already funnel and
+// the apply loop reads it.
+//
+// SHAPE ONLY, and structurally so: a phase LABEL from this codebase's own closed vocabulary, a
+// kind, counts and durations. No argv, no SOQL, no component names, no org alias — which matters
+// because the wave event is validated against a shape-only allowlist on ingest
+// (campfire-launch/convex/lib/events.ts), and argv and SOQL are where org content lives.
+//
+// PROCESS-WIDE, NOT REQUEST-SCOPED. One MCP server serves one session's waves serially, so a
+// process-global meter reset at the start of each wave measures that wave. Stated rather than
+// assumed: `resetOrgCallMeter` is what makes the reading a wave's and not a run's.
+/**
+ * Where a call is filed when no phase is open.
+ *
+ * Auth checks, the org gate and session binding all reach the org outside any wave phase. They are
+ * counted rather than dropped, because a meter whose phases do not sum to its total quietly
+ * under-reports the very cost it exists to expose.
+ */
+const UNPHASED = "other";
+// Keyed on a global symbol for the same reason telemetryContext.ts is: this module can legitimately
+// be loaded more than once in a process (a lazy import from the apply loop, a static one from a
+// tool), and two module instances holding two meters would silently halve every count.
+const KEY = Symbol.for("in2.org.call.meter.v1");
+const globals = globalThis;
+const state = (globals[KEY] ??= {
+    count: 0,
+    totalMs: 0,
+    cliCount: 0,
+    cliMs: 0,
+    apiCount: 0,
+    apiMs: 0,
+    firstCallMs: null,
+    byPhase: new Map(),
+    phase: null
+});
+/**
+ * Clear the meter. Called at the start of each wave so a reading measures ONE wave.
+ *
+ * `firstCallMs` is cleared too, deliberately: it means "first call of this WAVE", which is the
+ * comparison the ledger can actually make — first against steady state, within one wave, on one
+ * machine. A process-lifetime first call would be one number per run with nothing to compare it to.
+ */
+export function resetOrgCallMeter() {
+    state.count = 0;
+    state.totalMs = 0;
+    state.cliCount = 0;
+    state.cliMs = 0;
+    state.apiCount = 0;
+    state.apiMs = 0;
+    state.firstCallMs = null;
+    state.byPhase.clear();
+    state.phase = null;
+}
+/**
+ * Record one org call.
+ *
+ * `durationMs` is full wall clock — for a CLI child that is launch plus work, for an API call the
+ * round-trip. Splitting launch from work is not available from outside the child, and inventing the
+ * split would be a fabricated number rather than a measured one; the first-call/steady-state
+ * comparison is what stands in for it.
+ */
+export function recordOrgCall(kind, durationMs) {
+    const ms = Number.isFinite(durationMs) && durationMs > 0 ? Math.round(durationMs) : 0;
+    state.count += 1;
+    state.totalMs += ms;
+    if (kind === "cli") {
+        state.cliCount += 1;
+        state.cliMs += ms;
+    }
+    else {
+        state.apiCount += 1;
+        state.apiMs += ms;
+    }
+    if (state.firstCallMs === null)
+        state.firstCallMs = ms;
+    const key = state.phase ?? UNPHASED;
+    const phase = state.byPhase.get(key) ?? { count: 0, totalMs: 0 };
+    phase.count += 1;
+    phase.totalMs += ms;
+    state.byPhase.set(key, phase);
+}
+/**
+ * Attribute every org call inside `fn` to `label`.
+ *
+ * Restores the ENCLOSING phase rather than clearing to null, and in a `finally`, so a nested phase
+ * and a throwing one both leave the outer attribution intact. Getting that wrong would file the
+ * rest of a wave under `other` after the first inner failure — the failure mode that makes a meter
+ * worse than no meter, because it still looks like a measurement.
+ */
+export async function orgCallPhase(label, fn) {
+    const previous = state.phase;
+    state.phase = label;
+    try {
+        return await fn();
+    }
+    finally {
+        state.phase = previous;
+    }
+}
+/** Time `fn` as one API round-trip, whatever it returns or throws. */
+export async function meteredApiCall(fn) {
+    const started = Date.now();
+    try {
+        return await fn();
+    }
+    finally {
+        // A failed round-trip still cost the wall clock the operator waited through. Counting only
+        // successes would under-report exactly the runs that hurt.
+        recordOrgCall("api", Date.now() - started);
+    }
+}
+/** The meter as plain data. */
+export function readOrgCallMeter() {
+    return {
+        count: state.count,
+        totalMs: state.totalMs,
+        cliCount: state.cliCount,
+        cliMs: state.cliMs,
+        apiCount: state.apiCount,
+        apiMs: state.apiMs,
+        firstCallMs: state.firstCallMs,
+        byPhase: Object.fromEntries([...state.byPhase].map(([key, value]) => [key, { ...value }]))
+    };
+}
+/**
+ * The meter as the wave event's payload fragment — spread into the emit, absent when there is
+ * nothing to say.
+ *
+ * A wave that never reached the org (LINT_BLOCKED) legitimately made no calls, and an absent key is
+ * how the rest of this payload says "not applicable". Zeroes would be equally true and would make a
+ * blocked wave indistinguishable from an install running an older build that sends no meter.
+ */
+export function orgCallMeterSnapshot() {
+    if (state.count === 0)
+        return {};
+    return {
+        orgCallCount: state.count,
+        orgCallMs: state.totalMs,
+        orgCliCount: state.cliCount,
+        orgCliMs: state.cliMs,
+        orgApiCount: state.apiCount,
+        orgApiMs: state.apiMs,
+        ...(state.firstCallMs !== null ? { orgFirstCallMs: state.firstCallMs } : {}),
+        orgCallsByPhase: Object.fromEntries([...state.byPhase].map(([key, value]) => [key, { ...value }]))
+    };
+}