in2-agent-server 0.20260821.185429

package/dist/core/telemetry.js

@@ -0,0 +1,1297 @@
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { REPO_ROOT } from "./paths.js";
+import { sessionDir } from "./workspace.js";
+import { installedVersion } from "./install.js";
+import { harnessVersion } from "./paths.js";
+import { batchTelemetryClosed, bindBatchContext, closeBatchTelemetry, onBatchContext, processTelemetryIdentity, emitDomainTelemetryEvent, onDomainTelemetryEvent, registerBatchCloser, registerBoundaryFlusher, setProcessTelemetryIdentity } from "./telemetryContext.js";
+import { TelemetryGrantStore, TelemetrySpool } from "./telemetrySpool.js";
+import { announce, findTranscript, findTranscriptsForSession, shipSessionTranscripts, transcriptEndpointFrom, transcriptUploadEnabled } from "./transcriptUpload.js";
+import { announceParcelUpload, flushParcels } from "./parcels.js";
+import { announceOperatorQa, operatorQaEndpointFrom, shipOperatorQa } from "./operatorQa.js";
+import { announceBeta, flushFeedback, redactSecrets } from "./betaFeedback.js";
+// The ONE batch grading rule, shared with `composeBatchReport`. A dependency-free leaf (node:fs and
+// node:path only) so this static import pulls nothing else across the core/direct line — see
+// `writeReport` for why the report itself is imported lazily instead.
+import { gradeWaves, readWaveBundles } from "../direct/waveGrade.js";
+// PIPELINE TELEMETRY — where does a run's wall-clock actually go?
+//
+// A config run takes ~20-30 min against ~5 min for the old manual VFP process. Some of that is
+// expected (interactive, verified, far more complete), but "expected" is not a number. Wall-clock
+// splits three ways and only ONE of them is a performance problem:
+//
+//   tool time     — org round-trips (checkOnly, deploy, projections). Real cost, optimizable.
+//   agent time    — the model reading, planning, authoring XML between tool calls.
+//   operator time — the human answering a question card. NOT a system cost, and must never be
+//                   counted against the run; a run that waited 8 minutes for an answer is not slow.
+//
+// Every record carries the gap SINCE THE PREVIOUS TOOL CALL and classifies it, so the three are
+// separable after the fact. The classifier is the one load-bearing rule: a gap that follows
+// `ask_operator` is operator wait, because that tool exists precisely to hand control to the human.
+//
+// Bodies are never logged — only SHAPES (counts, flags, ids). Metadata XML, content bodies and
+// note text stay out of the log: they are large, they are the client's, and they answer no timing
+// question.
+const STAGE_BY_TOOL = {
+    create_session: "intake",
+    import_requirements: "intake",
+    org_login: "auth",
+    activate_session: "intake",
+    project_org: "grounding",
+    list_components: "probe",
+    describe_object: "probe",
+    sf_read: "probe",
+    read_campfire_requirements: "probe",
+    direct_lint: "lint",
+    direct_apply: "deploy",
+    // Reading the org mirror. Its own stage rather than "probe": it is a LOCAL read of what this
+    // install already did, so counting it as org round-trip time would misattribute the wall-clock
+    // split this table exists to measure.
+    direct_history: "history",
+    ask_operator: "operator-gate",
+    // The other half of the gate. NOT a `classifyGap` case: the gap AFTER this call is the agent
+    // working with the answer, whereas the gap after `ask_operator` is the human deciding.
+    record_operator_answers: "operator-gate",
+    // Its own stage rather than folded into the chapter it enters. A boundary is not work — it is the
+    // moment between two stretches of work — so counting it as `grounding` or `deploy` would inflate
+    // whichever chapter happened to follow it with the cost of a flush.
+    advance_phase: "boundary",
+    resume_session: "boundary",
+    campfire_config_item_plan: "writeback-plan",
+    campfire_write_config_items: "writeback",
+    create_campfire_deployment_tasks: "writeback",
+    update_campfire_requirements: "writeback",
+    close_batch: "settle",
+};
+export function stageForTool(tool) {
+    return STAGE_BY_TOOL[tool] ?? "other";
+}
+/**
+ * THE ONE PHASE VOCABULARY THIS SYSTEM SPEAKS — derived from the table above, never restated.
+ *
+ * The beta feedback channel's `stage` argument enumerates exactly this (tools/feedback.ts), so a
+ * friction report joins the timing data instead of inventing a second phase language for the same
+ * run. Derived rather than listed so a tool added to `STAGE_BY_TOOL` with a new stage extends the
+ * feedback vocabulary in the same edit — a hand-copied enum is how the two would come to disagree.
+ *
+ * `other` is included because `stageForTool` returns it for anything unmapped, so it is a stage the
+ * timing data genuinely contains rather than a placeholder.
+ */
+export const TELEMETRY_STAGES = [...new Set([...Object.values(STAGE_BY_TOOL), "other"])].sort();
+/** Batch close reports every step it could not complete, so failures need a printable form. */
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Exit backstops are process-wide, so they are installed once however many Telemetry objects exist. */
+let exitBackstopsInstalled = false;
+// Shape-only input summary. Anything not named here is dropped, so a new tool can never
+// accidentally start logging client metadata.
+export function summarizeInput(input) {
+    if (!input || typeof input !== "object")
+        return {};
+    const i = input;
+    const out = {};
+    const passthrough = ["targetOrg", "consultantOrg", "sessionId", "label", "requirement", "extId", "typeName", "metadataType", "alias", "mode", "dryRunOnly"];
+    for (const k of passthrough)
+        if (i[k] !== undefined)
+            out[k] = i[k];
+    const arrays = ["components", "deletes", "objectFacetUpdates", "bundleDirs", "requirements", "names", "args", "ackLints"];
+    for (const k of arrays)
+        if (Array.isArray(i[k]))
+            out[`${k}Count`] = i[k].length;
+    const flags = ["sourceDir", "projectionDir", "sessionDir", "corpusDir", "compareTo", "content"];
+    for (const k of flags)
+        if (i[k] !== undefined)
+            out[`has_${k}`] = true;
+    if (i.campfire && typeof i.campfire === "object") {
+        const c = i.campfire;
+        out.campfireNames = Array.isArray(c.names) ? c.names.length : undefined;
+    }
+    if (i.scope && typeof i.scope === "object") {
+        const s = i.scope;
+        out.scope = {
+            objects: Array.isArray(s.objects) ? s.objects.length : undefined,
+            components: Array.isArray(s.components) ? s.components.length : undefined,
+            prefix: s.prefix ? true : undefined
+        };
+    }
+    return out;
+}
+// Shape-only output summary: the few fields that explain WHAT happened, never the payload.
+export function summarizeOutput(result) {
+    if (!result || typeof result !== "object")
+        return {};
+    const r = result;
+    const out = { ok: !r.isError };
+    const s = r.structuredContent;
+    if (!s)
+        return out;
+    const err = s.error;
+    if (err?.code)
+        out.errorCode = err.code;
+    for (const k of ["verdict", "action", "id", "componentsLinted", "blocked", "referentialTier", "truncated"]) {
+        if (s[k] !== undefined)
+            out[k] = s[k];
+    }
+    // The self-update lifecycle, so the ledger can answer "which runs checked, which applied, and did
+    // the session need a restart afterwards" — the question QA round 1 left unanswerable when two
+    // stale builds each cost a run. Flags and version strings only; the changed-tool NAMES stay in
+    // the tool result (they are our own vocabulary, but the ledger's discipline is shape, not lists).
+    for (const k of [
+        "updated", "applied", "swappedLive", "launcherUpdated", "instructionsChanged",
+        "updateAvailable", "staleness", "behindDays", "currentVersion", "latestVersion", "previousVersion"
+    ]) {
+        if (s[k] !== undefined)
+            out[k] = s[k];
+    }
+    for (const [k, source] of [["addedCount", "added"], ["removedCount", "removed"], ["changedCount", "changed"]]) {
+        if (Array.isArray(s[source]))
+            out[k] = s[source].length;
+    }
+    if (Array.isArray(s.rows))
+        out.rowCount = s.rows.length;
+    if (Array.isArray(s.findings))
+        out.findingCount = s.findings.length;
+    if (Array.isArray(s.imported))
+        out.importedCount = s.imported.length;
+    const counts = s.counts;
+    if (counts)
+        out.counts = counts;
+    const writebackCounts = {};
+    for (const key of ["created", "updated", "skipped", "failed", "total", "readbackConfirmed"]) {
+        if (s[key] !== undefined)
+            writebackCounts[key] = s[key];
+    }
+    if (Object.keys(writebackCounts).length > 0)
+        out.writebackCounts = writebackCounts;
+    if (Array.isArray(s.failures)) {
+        // SLICED TO THE VALIDATOR'S CAP. The ingest check refuses `failedRows` past 100 outright, and
+        // the tool result this reads carries the FULL failure list, so a writeback with 101+ failures
+        // used to reject its own `tool.completed` permanently — losing the tool call from the ledger
+        // beside the domain event it belongs to. The sibling emitter for `writeback.completed` already
+        // slices; this path was simply missed. Truncating loses nothing the payload does not still
+        // state: the count rides on `writebackCounts.failed` regardless.
+        out.failedRows = s.failures.slice(0, 100).map((failure) => ({
+            ...(failure.metadataKey !== undefined ? { metadataKey: failure.metadataKey } : {}),
+            ...(failure.requirement !== undefined ? { requirement: failure.requirement } : {}),
+            ...(failure.externalId !== undefined ? { externalId: failure.externalId } : {})
+        }));
+    }
+    return out;
+}
+export function classifyGap(previousTool) {
+    if (previousTool === null)
+        return "first";
+    return previousTool === "ask_operator" ? "operator" : "agent";
+}
+// REMOTE TELEMETRY — the same shape-only records, shipped to the launch service so runs across
+// every install are visible in one place (which tools fail, which versions are live, how many
+// installs are active). ON BY DEFAULT; the same records already written locally, nothing more.
+// Opt-outs: CC_MCP_TELEMETRY=0 kills all telemetry, CC_MCP_TELEMETRY_REMOTE=0 kills just the
+// remote ship. The authenticated endpoint is bound by activate_session after it redeems the
+// batch-scoped grant, including when the launch URL was passed as a tool argument.
+//
+// FAIL-OPEN IS LOAD-BEARING: telemetry must never slow, block, or break a tool call. Batches
+// ship on a timer (unref'd, so the process never stays alive for it); a failed POST re-queues
+// up to a hard cap and is retried next tick; past the cap, events are dropped and counted.
+/** Stable anonymous id for THIS install — lets the collector tell five consultants apart. */
+export function installId() {
+    const file = path.join(REPO_ROOT, ".local", "cc-mcp", "install-id");
+    try {
+        return readFileSync(file, "utf8").trim();
+    }
+    catch {
+        const id = `ins_${randomBytes(8).toString("hex")}`;
+        try {
+            mkdirSync(path.dirname(file), { recursive: true });
+            writeFileSync(file, `${id}\n`, "utf8");
+        }
+        catch {
+            /* unwritable disk — a per-process id is still useful */
+        }
+        return id;
+    }
+}
+/** Longest gap between delivery-health reports while nothing about delivery has changed. */
+const HEALTH_REPORT_FLOOR_MS = 5 * 60_000;
+/** Where this install keeps its outbox and its grants. One place, so a reader cannot pick a different one. */
+function localTelemetryRoot() {
+    return path.join(REPO_ROOT, ".local", "cc-mcp");
+}
+/**
+ * Re-bind a batch this MACHINE already has a grant for, so a resumed run can ship again.
+ *
+ * WHY THIS IS NEEDED AT ALL. `bindBatchContext` is called by `activate_session`, and activation
+ * happens once — it redeems a single-use code. A fresh server process picking up a dead run has
+ * therefore never bound a batch, so `close_batch` reports "no batch bound to this server process",
+ * the boundary flush does the same, and the resumed run's events and transcript never leave the
+ * machine EVEN THOUGH the original run's grant is sitting in the grant store, valid, keyed by the
+ * batchId the session file records.
+ *
+ * The grant is the authority, exactly as everywhere else: this mints nothing and asserts nothing.
+ * It reads a credential this install was already issued for this batch, and binds it back. An
+ * expired or absent grant returns false, which the caller reports as a fact rather than working
+ * around — a resumed run whose grant has gone still DELIVERS, it just cannot ship its evidence, and
+ * saying so is the whole point.
+ */
+export function rebindStoredBatch(input) {
+    try {
+        const grant = new TelemetryGrantStore(path.join(localTelemetryRoot(), "telemetry-grants")).get(input.batchId);
+        if (!grant)
+            return false;
+        const identity = processTelemetryIdentity();
+        bindBatchContext({
+            batchId: input.batchId,
+            // The RESUMING process's identity, not the dead run's: install stays the same machine, but
+            // runId names which process produced the events, and claiming the old one would merge two
+            // runs into one in the ledger.
+            installId: identity?.installId ?? grant.installId,
+            runId: identity?.runId ?? grant.runId,
+            sessionId: input.sessionId,
+            serverVersion: identity?.serverVersion ?? grant.serverVersion,
+            credential: grant.credential,
+            expiresAt: grant.expiresAt,
+            endpoint: grant.endpoint
+        });
+        return true;
+    }
+    catch {
+        // Telemetry is fail-open everywhere else and is fail-open here: a resume must never break on it.
+        return false;
+    }
+}
+/**
+ * The one event type that flushes the moment it is emitted.
+ *
+ * Named as a constant rather than inlined so the cadence is one decision in one place: the next
+ * domain event added is NOT a boundary unless somebody puts it here on purpose.
+ */
+const WAVE_BOUNDARY_EVENT = "deployment.wave_completed";
+/**
+ * Upper bound on startup drain passes — 200 events each, so 40,000 events, far beyond what any run
+ * strands and well under the outbox's own 10 MB cap. A backstop against a non-shrinking outbox,
+ * not a real limit; the loop normally exits on "no progress" or "nothing pending".
+ */
+const MAX_DRAIN_PASSES = 200;
+export function cloudEvent(record) {
+    if (record.event === "server_start") {
+        return {
+            eventId: record.eventId ?? `evt_${randomBytes(16).toString("hex")}`,
+            eventType: "server.started",
+            occurredAt: record.ts,
+            outcome: "started",
+            payload: { ...(record.pid !== undefined ? { pid: record.pid } : {}) }
+        };
+    }
+    const output = record.output ?? {};
+    const errorCode = typeof output.errorCode === "string"
+        ? output.errorCode
+        : record.threw
+            ? "TOOL_THREW"
+            : undefined;
+    return {
+        eventId: record.eventId ?? `evt_${randomBytes(16).toString("hex")}`,
+        eventType: record.threw ? "tool.threw" : "tool.completed",
+        occurredAt: record.ts,
+        ...(record.stage ? { stage: record.stage } : {}),
+        ...(record.ms !== undefined ? { durationMs: Math.max(0, Math.round(record.ms)) } : {}),
+        ...(record.gapMs !== undefined ? { gapMs: Math.max(0, Math.round(record.gapMs)) } : {}),
+        ...(record.gapClass ? { gapClass: record.gapClass } : {}),
+        outcome: record.threw ? "threw" : output.ok === false ? String(errorCode ?? "error") : "ok",
+        payload: record.threw
+            ? { tool: record.tool ?? "unknown", ...(errorCode ? { errorCode } : {}) }
+            : { tool: record.tool ?? "unknown", input: record.input ?? {}, output }
+    };
+}
+export class DurableRemoteSink {
+    options;
+    /**
+     * Where a full transcript would go, and the credential to send it with — the SAME batch-scoped
+     * grant the events use, so a transcript can only be attributed to the batch that uploaded it.
+     * Null until a grant exists, which is also the point before which there is nothing to attribute.
+     */
+    transcriptEndpoint() {
+        const batchId = this.context?.batchId;
+        if (!batchId)
+            return null;
+        const grant = this.options.grants.get(batchId);
+        return grant ? transcriptEndpointFrom(grant.endpoint) : null;
+    }
+    /**
+     * The batch-scoped grant, which every content route uses — transcript, parcel and operator Q&A.
+     * One credential rather than three: the grant is what BINDS an upload to a batch, so a route with
+     * its own would be a second, weaker claim about whose run this is.
+     */
+    batchCredential() {
+        const batchId = this.context?.batchId;
+        if (!batchId)
+            return null;
+        return this.options.grants.get(batchId)?.credential ?? null;
+    }
+    /**
+     * Where the question cards and their answers go. Same host, same grant, different route — and
+     * resolved from the same grant store for the same reason: a Q&A record can only ever be
+     * attributed to the batch whose credential sent it.
+     */
+    operatorQaEndpoint() {
+        const batchId = this.context?.batchId;
+        if (!batchId)
+            return null;
+        const grant = this.options.grants.get(batchId);
+        return grant ? operatorQaEndpointFrom(grant.endpoint) : null;
+    }
+    /**
+     * Strings that identify this IN2 session inside a Claude Code transcript.
+     *
+     * The session id is the reliable one: every org-touching tool takes it as an argument, so the
+     * client records it as tool input on essentially every call. batchId is included because a
+     * session that ended before its first org call still names its batch. The activation code is
+     * deliberately NOT used — it is a credential, and matching on it would mean reading it back out
+     * of state it has no reason to leave.
+     */
+    /** The IN2 session this batch is running, once activation has bound one. */
+    batchSessionId() {
+        return this.context?.sessionId ?? null;
+    }
+    transcriptMarkers() {
+        return [this.context?.sessionId, this.context?.batchId].filter((v) => typeof v === "string" && v.length >= 8);
+    }
+    context = null;
+    beforeContext = [];
+    fetchFn;
+    maxPreContext;
+    /** The flush currently on the wire, or null. Both the concurrency guard and the thing to await. */
+    active = null;
+    /**
+     * The flush currently in flight, so a caller can await a shipment it did not start.
+     *
+     * `flush()` is deliberately fire-and-forget at every call site — telemetry may never delay a tool
+     * — which leaves no handle on "has the wave's event actually gone". This is that handle, and it
+     * exists for the same reason the cadence does: the interesting question about a wave-boundary
+     * flush is whether it COMPLETED, and a test that polls a timer is measuring the timer.
+     */
+    pending = Promise.resolve();
+    warned = false;
+    retries = 0;
+    rejectedSchemaEventIds = new Set();
+    /** Distinct rejection REASONS already printed this process — see reportRejection. */
+    reportedRejectionReasons = new Set();
+    /** Events the ledger has ACCEPTED on this sink — what `drainOutbox` reports as recovered. */
+    acceptedEvents = 0;
+    lastAcknowledgedEventId;
+    lastHealthSignature = "";
+    lastHealthAt = 0;
+    constructor(options) {
+        this.options = options;
+        this.fetchFn = options.fetchFn ?? fetch;
+        this.maxPreContext = options.maxPreContext ?? 500;
+        onBatchContext((context) => this.bind(context));
+    }
+    bind(context) {
+        this.context = context;
+        try {
+            if (context.credential)
+                this.options.grants.put(context);
+            for (const record of this.beforeContext.splice(0)) {
+                if (!this.options.spool.append({ batchId: context.batchId, event: cloudEvent(record) })) {
+                    this.warnOnce(new Error("local telemetry outbox is unavailable"));
+                }
+            }
+            void this.flush();
+        }
+        catch (error) {
+            this.warnOnce(error);
+        }
+    }
+    push(record) {
+        if (!this.context) {
+            this.beforeContext.push(record);
+            if (this.beforeContext.length > this.maxPreContext)
+                this.beforeContext.shift();
+            return;
+        }
+        if (!this.options.spool.append({ batchId: this.context.batchId, event: cloudEvent(record) })) {
+            this.warnOnce(new Error("local telemetry outbox is unavailable"));
+        }
+    }
+    pushDomain(event) {
+        if (!this.context)
+            return;
+        if (!this.options.spool.append({
+            batchId: this.context.batchId,
+            event: {
+                eventId: event.eventId,
+                eventType: event.eventType,
+                occurredAt: event.occurredAt,
+                ...(event.stage ? { stage: event.stage } : {}),
+                ...(event.outcome ? { outcome: event.outcome } : {}),
+                payload: event.payload
+            }
+        })) {
+            this.warnOnce(new Error("local telemetry outbox is unavailable"));
+        }
+        // A WAVE BOUNDARY SHIPS IMMEDIATELY.
+        //
+        // Everything else waits for the 20-second timer or for `close_batch`, and both are bets on the
+        // process surviving. A Windows run whose waves took ~8 minutes each died before either, and its
+        // whole ledger stayed on disk — the events were never lost, they were never SENT, and no later
+        // run flushed them because the drain did not exist yet (it does now; see drainOutbox).
+        //
+        // A wave boundary is the right cadence and not merely a convenient one: it is RARE (a handful
+        // per batch, against a health tick every 20s and a tool event per call), its payload is a few
+        // hundred bytes, and it lands at the one moment the run has just finished the longest and
+        // riskiest thing it does. Flushing on every emit would put a network hop behind the health
+        // heartbeat; flushing here costs one POST per delivered wave.
+        //
+        // Unawaited, like every other flush: the contract is that telemetry never delays a tool. The
+        // event is already durable on disk (appendFileSync), so the only thing at risk is the hop.
+        if (event.eventType === WAVE_BOUNDARY_EVENT)
+            this.flushSoon();
+    }
+    /**
+     * Start a flush without waiting for it, and keep a handle on the one in flight.
+     *
+     * CHAINED ONTO WHATEVER IS RUNNING, not fired blind. `flush()` returns immediately when another
+     * flush is in flight, and that guard is a silent no-op — so a wave boundary landing during the
+     * 20-second timer's flush would ship NOTHING, and the running flush cannot carry the event either
+     * because it read its batch off the outbox before the event was appended. The boundary therefore
+     * has to WAIT for the in-flight flush and then start a fresh one. (Caught by test, and it is the
+     * exact failure this cadence exists to prevent: the wave that most needs shipping, on the run
+     * least likely to survive to the next tick.)
+     *
+     * `.catch` swallows: telemetry is fail-open, and a rejected flush must not leave the chain
+     * permanently rejected for every later boundary.
+     */
+    flushSoon() {
+        this.pending = this.pending.then(() => this.flush()).catch(() => undefined);
+    }
+    /** Resolves once no flush this sink started is still running. Test and shutdown seam only. */
+    async settled() {
+        await this.pending;
+    }
+    /** Events still on disk. Batch close reports a non-zero count rather than implying success. */
+    pendingEventCount() {
+        return this.options.spool.stats().pendingEvents;
+    }
+    /**
+     * Ship EVERYTHING the outbox is holding, not just one delivery batch.
+     *
+     * `flush()` sends at most 200 events, which is right for a timer tick and wrong for the two
+     * moments a run is trying to leave nothing behind. Both callers are here:
+     *
+     * SERVER START — the recovery window. Every event is durable the moment it is emitted, so a
+     * killed process costs the network hop and not the record — but that promise only pays out if
+     * something later actually performs the hop. Nothing did: the only things that flushed were a
+     * timer inside the dead process and a batch close it never reached, so "a later run flushes it"
+     * was true of the outbox format and false of the code, and a stranded segment sat there until its
+     * 30-day age cap dropped it. At start, everything in the outbox is by construction a PRIOR run's
+     * — this process has emitted nothing yet.
+     *
+     * BATCH CLOSE — the explicit end. A real run emits far more than 200 events (a tool event per
+     * call, a health tick every 20 seconds), so a single flush there left the remainder to a timer
+     * that is about to stop ticking: the same "never reached the ledger" shape, on the path that is
+     * supposed to be the reliable one.
+     *
+     * FAIL-OPEN AND BOUNDED. It stops the moment a flush makes no progress — an unreachable ledger,
+     * or a batch whose grant has expired — so an offline machine pays one failed POST and never a
+     * retry storm. Events it could not ship stay on disk for the next start, which is the honest
+     * state: "could not ship" and "shipped" must not look the same from outside.
+     *
+     * Returns how many events actually reached the ledger, for the line that reports it.
+     */
+    async drainOutbox() {
+        const started = this.acceptedEvents;
+        // Settle any flush ALREADY on the wire before measuring progress. One started earlier read its
+        // batch off the outbox before these events existed, so counting it as this drain's first pass
+        // would see the queue unchanged, conclude "no progress" and give up with the outbox full — the
+        // drain reporting success while shipping nothing.
+        await this.settled();
+        // A hard bound as well as the progress check: the loop's exit depends on the outbox shrinking,
+        // and a bug that made it not shrink must cost a bounded number of POSTs, not an infinite run.
+        for (let pass = 0; pass < MAX_DRAIN_PASSES; pass++) {
+            const before = this.options.spool.stats().pendingEvents;
+            if (before === 0)
+                break;
+            await this.flush();
+            // Progress is measured on the OUTBOX (a schema rejection retires an event without delivering
+            // it, and a pass that only rejects must still terminate); the RETURN is measured on what the
+            // ledger accepted, because that is the number the startup line claims reached IN2.
+            if (this.options.spool.stats().pendingEvents >= before)
+                break;
+        }
+        return this.acceptedEvents - started;
+    }
+    /**
+     * Ship one batch, at most one flush at a time.
+     *
+     * A concurrent call AWAITS the running flush rather than returning immediately. It used to be a
+     * silent no-op, which is harmless for the 20-second timer (two POSTs racing gain nothing) and
+     * wrong for a wave boundary: the running flush read its batch off the outbox BEFORE the wave
+     * event was appended, so it cannot be carrying it, and the boundary's own flush would vanish. The
+     * awaited promise is what lets `flushSoon` chain a fresh flush behind it.
+     */
+    async flush() {
+        if (this.active)
+            return this.active;
+        const run = this.runFlush().finally(() => {
+            this.active = null;
+        });
+        this.active = run;
+        // Anything awaiting `settled()` observes this flush even when nothing chained it.
+        this.pending = run.catch(() => undefined);
+        return run;
+    }
+    async runFlush() {
+        let entries = [];
+        let grant = null;
+        for (const batchId of this.options.spool.pendingBatchIds()) {
+            const candidate = this.options.grants.get(batchId);
+            if (!candidate)
+                continue;
+            entries = this.options.spool.readBatch(200, batchId);
+            if (entries.length > 0) {
+                grant = candidate;
+                break;
+            }
+        }
+        // An expired/unavailable grant for an older batch must not head-of-line block a newer batch.
+        // The old segment remains bounded on disk for explicit reconciliation or later recovery.
+        if (entries.length === 0 || !grant)
+            return;
+        try {
+            const res = await this.fetchFn(grant.endpoint, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${grant.credential}`
+                },
+                // Stamp the producing build and the harness the install is RUNNING onto every event. Batches
+                // carried a version; individual events did not, so a regression could not be attributed to a
+                // release, and a machine running new server code against stale skill files was invisible.
+                body: JSON.stringify({
+                    schemaVersion: 2,
+                    events: entries.map((entry) => ({
+                        ...entry.event,
+                        ...(installedVersion() ? { serverVersion: installedVersion() } : {}),
+                        ...(harnessVersion() ? { skillVersion: harnessVersion() } : {})
+                    }))
+                }),
+                signal: AbortSignal.timeout(10_000)
+            });
+            if (!res.ok) {
+                throw new Error(`HTTP ${res.status}`);
+            }
+            const response = (await res.json());
+            const accepted = Array.isArray(response.acceptedEventIds) ? response.acceptedEventIds : [];
+            // A schema rejection is PERMANENT: the same bytes will be refused every time. Retaining a
+            // rejected event means re-sending it every flush for the life of the outbox, and once enough
+            // of them collect at the head of a segment they crowd out the events that would be accepted.
+            // So they are retired from the outbox and counted as lost, which is the truth, rather than
+            // retried forever while delivery-health reports "ok".
+            const rejected = [];
+            for (const entry of response.rejectedEvents ?? []) {
+                if (typeof entry.eventId === "string") {
+                    this.rejectedSchemaEventIds.add(entry.eventId);
+                    rejected.push(entry.eventId);
+                }
+                this.reportRejection(entry);
+            }
+            this.options.spool.acknowledge([...accepted, ...rejected], rejected.length);
+            this.acceptedEvents += accepted.length;
+            this.lastAcknowledgedEventId = accepted.at(-1);
+            this.warned = false;
+        }
+        catch (error) {
+            this.retries += 1;
+            this.warnOnce(error);
+        }
+    }
+    /**
+     * Delivery health, but only when it CARRIES INFORMATION. Spooling a heartbeat every 20 seconds
+     * made health events the majority of a run's ledger rows — a 30-minute run emits ~90 of them
+     * against a few dozen real tool events — which skews any per-event-type analysis and consumes
+     * the 200-event delivery batch. A report is emitted when the meaningful fields change (pending,
+     * retries, rejections, drops, last acknowledgement) or when the floor elapses, so silence still
+     * proves liveness without drowning the signal.
+     */
+    informativeHealthEvent(now) {
+        const event = this.healthEvent();
+        const p = event.payload;
+        // oldestEventAgeMs is excluded deliberately: it advances every tick while a queue is pending,
+        // so including it would make every heartbeat look like a change.
+        const signature = JSON.stringify([
+            event.outcome, p.pendingEvents, p.retries, p.rejectedSchemas, p.droppedEvents,
+            p.lastAcknowledgedEventId ?? null
+        ]);
+        if (signature === this.lastHealthSignature && now - this.lastHealthAt < HEALTH_REPORT_FLOOR_MS) {
+            return null;
+        }
+        this.lastHealthSignature = signature;
+        this.lastHealthAt = now;
+        return event;
+    }
+    healthEvent() {
+        const stats = this.options.spool.stats();
+        return {
+            eventId: `evt_${randomBytes(16).toString("hex")}`,
+            eventType: "telemetry.delivery_health",
+            occurredAt: new Date().toISOString(),
+            outcome: stats.droppedEvents > 0 || this.rejectedSchemaEventIds.size > 0 ? "degraded" : "ok",
+            payload: {
+                pendingEvents: stats.pendingEvents,
+                oldestEventAgeMs: stats.oldestEventAgeMs,
+                retries: this.retries,
+                rejectedSchemas: this.rejectedSchemaEventIds.size,
+                droppedEvents: stats.droppedEvents,
+                ...(this.lastAcknowledgedEventId ? { lastAcknowledgedEventId: this.lastAcknowledgedEventId } : {})
+            }
+        };
+    }
+    /**
+     * SAY WHY AN EVENT WAS REFUSED, ONCE PER DISTINCT REASON.
+     *
+     * A schema rejection is permanent — the same bytes are refused every time, so the event is
+     * retired from the outbox and counted lost. That makes this the ONLY moment the cause exists
+     * anywhere: after it, the record is gone and all that remains is `rejectedSchemas: N` in a
+     * delivery-health payload that names neither the event nor the reason.
+     *
+     * DEDUPED BY REASON, NOT BY EVENT. A break usually retires every event of one type (132 in one
+     * observed batch), and 132 identical lines would bury a second, different cause arriving later
+     * in the same run — which is exactly the case that matters, since #66 and #72 surfaced together.
+     * The reason is the diagnostic unit; the first event id is carried along to tie it to a record.
+     *
+     * NOT `warnOnce`, deliberately: that gate is for a channel that is DOWN, where one line per
+     * outage is right and the second line says nothing new. Here every distinct reason is new
+     * information about a different contract break.
+     *
+     * SAFE TO PRINT. These strings are the validator's own vocabulary — a field name and a bound
+     * ("writeback.completed.payload has unknown field(s): adopted"). They quote the CONTRACT, never
+     * the value that violated it, and the server bounds them to 512 characters. Passed through
+     * `redactSecrets` anyway: this lands on a consultant's terminal, and the one thing worse than a
+     * silent drop is a diagnostic that leaks.
+     */
+    reportRejection(entry) {
+        const reason = typeof entry.error === "string" && entry.error.trim() ? entry.error.trim() : "";
+        if (!reason || this.reportedRejectionReasons.has(reason))
+            return;
+        this.reportedRejectionReasons.add(reason);
+        const at = typeof entry.eventId === "string" ? ` (${entry.eventId})` : "";
+        process.stderr.write(`[cc-mcp] telemetry event REJECTED by the ledger and permanently dropped${at}: ` +
+            `${redactSecrets(reason)} — this is a schema contract break between the emitter and ` +
+            `convex/lib/events.ts, not a network failure; the event will not be retried\n`);
+    }
+    warnOnce(error) {
+        if (this.warned)
+            return;
+        this.warned = true;
+        process.stderr.write(`[cc-mcp] remote telemetry unavailable (${error instanceof Error ? error.message : String(error)}) — events remain in the local outbox; tools are unaffected\n`);
+    }
+}
+/**
+ * How much a transcript must have grown before a BOUNDARY re-uploads it. 256 KB is roughly a few
+ * dozen turns of a real run, so an ordinary chapter ships and a boundary crossed twice in quick
+ * succession does not re-gzip the same file for nothing. Not a correctness threshold — the close
+ * uploads unconditionally.
+ */
+export const BOUNDARY_TRANSCRIPT_GROWTH_BYTES = 256 * 1024;
+export class Telemetry {
+    previousTool = null;
+    previousEnd = null;
+    file;
+    remote;
+    /** Bytes last shipped per transcript file, so a boundary can tell a grown capture from a static one. */
+    uploadedTranscriptBytes = new Map();
+    runId;
+    constructor(now = Date.now) {
+        this.now = now;
+        this.runId = `run_${new Date().toISOString().replace(/[:.]/g, "-")}_${process.pid}`;
+        const machineInstallId = installId();
+        const serverVersion = installedVersion();
+        setProcessTelemetryIdentity({ installId: machineInstallId, runId: this.runId, serverVersion });
+        if (process.env.CC_MCP_TELEMETRY === "0") {
+            this.file = null;
+            this.remote = null;
+            return;
+        }
+        const dir = process.env.CC_MCP_TELEMETRY_DIR?.trim() || path.join(REPO_ROOT, ".local", "cc-mcp", "telemetry");
+        let file = null;
+        try {
+            mkdirSync(dir, { recursive: true });
+            file = path.join(dir, `${this.runId}.jsonl`);
+        }
+        catch {
+            file = null; // telemetry must never break the server
+        }
+        this.file = file;
+        // The sink is ready before activation so it can buffer server-start and activation timing.
+        // Its authenticated endpoint arrives with bindBatchContext; no unauthenticated default URL is
+        // contacted in a development checkout.
+        let durable = null;
+        if (process.env.CC_MCP_TELEMETRY_REMOTE !== "0") {
+            try {
+                const localRoot = localTelemetryRoot();
+                durable = new DurableRemoteSink({
+                    spool: new TelemetrySpool({
+                        dir: path.join(localRoot, "telemetry-outbox"),
+                        runId: this.runId
+                    }),
+                    grants: new TelemetryGrantStore(path.join(localRoot, "telemetry-grants"))
+                });
+            }
+            catch {
+                durable = null;
+            }
+        }
+        this.remote = durable;
+        if (this.remote) {
+            onDomainTelemetryEvent((event) => this.remote?.pushDomain(event));
+            const timer = setInterval(() => {
+                const health = this.remote?.informativeHealthEvent(Date.now());
+                if (health)
+                    this.remote?.pushDomain(health);
+                void this.remote?.flush();
+            }, 20_000);
+            timer.unref(); // never keep the process alive for telemetry
+            // THE STALE OUTBOX — every event a PRIOR run on this machine left stranded.
+            //
+            // Anything in the outbox at this instant belongs to a previous process: this one has not
+            // emitted its own server_start yet. The events were durable all along (appendFileSync), and
+            // the comments throughout this file promise that "a later run flushes" them — until now
+            // nothing did, so a run killed mid-batch left its whole ledger on disk until the outbox's
+            // 30-day age cap silently dropped it. That is the Windows incident: eight-minute waves, a
+            // process that died before `close_batch`, and a batch that never appeared in IN2.
+            //
+            // Deliberately NOT awaited and never blocking: startup must not wait on the network, and an
+            // offline machine pays exactly one failed POST here (see drainOutbox's progress check).
+            // Reported to stderr only when it actually recovered something — a clean start stays quiet.
+            void this.remote
+                .drainOutbox()
+                .then((shipped) => {
+                if (shipped > 0) {
+                    process.stderr.write(`[cc-mcp] shipped ${shipped} telemetry event(s) a previous run left in the local outbox\n`);
+                }
+            })
+                .catch(() => undefined);
+        }
+        // FULL transcript capture, opt-in and separate from everything above — see transcriptUpload.ts
+        // for why it does not ride on telemetry's consent. Announced at startup so a machine where it
+        // is on can never be mistaken for one where it is not, and shipped at batch close, when the
+        // transcript is as complete as it will get.
+        //
+        // The endpoint is resolved AT CLOSE, not here: this constructor runs before any batch is bound
+        // — activate_session happens later — so transcriptEndpoint() is necessarily null at this
+        // moment. Capturing it in a closure and reusing that null at exit meant the upload could never
+        // run, on any install, ever (caught in review, 2026-07-31).
+        if (transcriptUploadEnabled())
+            announce(null);
+        // PROVENANCE PARCELS (plan 2026-08-02-002 U6; origin R7) — announced here for the same reason
+        // transcripts are, and flushed here for one specific one: a parcel is attributable only through
+        // the batch grant that uploads it, so anything still in the outbox when the process ends has to
+        // go out BEFORE the batch closes rather than waiting for a run whose grant may have expired.
+        //
+        // Announcement carries no endpoint at this point: like the transcript line above, this runs
+        // before any batch is bound. The once-guard lives in the module, so whichever comes first — this
+        // or the first wave's build — is the only line the operator sees.
+        //
+        // Sits with the transcript block deliberately: CC_MCP_TELEMETRY=0 returns above and takes both
+        // with it. One switch that stops everything leaving the machine is the behaviour an operator
+        // reaching for it expects, and CC_MCP_PARCEL_UPLOAD=0 remains the narrow way out.
+        announceParcelUpload();
+        // OPERATOR Q&A — the question cards and what came back, shipped at close by their own route.
+        // Announced here beside the other two because it is content leaving the machine, and stated
+        // separately from the transcript line for the reason the narrow opt-out exists: the transcript
+        // announcement already says the whole session goes, so what this adds is that the questions and
+        // answers are also stored in a form somebody can search. Endpoint is null at this point for the
+        // same reason as the two above — no batch is bound until activation.
+        announceOperatorQa();
+        // BETA FEEDBACK — announced beside the other three because it is content leaving the machine,
+        // and stated separately because what it adds is a category the other three do not carry: the
+        // MODEL's own account of the run, plus the operator's ratings and words if they give them.
+        // Silent on an install that is not in beta. Endpoint is null here for the same reason as the
+        // three above — no batch is bound until activation.
+        //
+        // Below the `CC_MCP_TELEMETRY=0` early return with the rest of them, deliberately: one switch
+        // that stops everything leaving the machine is what an operator reaching for it expects, and
+        // `feedbackUploadEnabled` states the same rule again at the flush rather than inheriting it.
+        announceBeta();
+        // ONE explicit end for the batch, replacing five separate guesses at one.
+        //
+        // Everything that used to hang off its own `process.once("beforeExit", …)` — remote flush,
+        // transcript ship, parcel flush, finalizeBatch, contamination — now runs here, in order, as
+        // awaitable work. `close_batch` drives it while the server is alive; the exit hooks below are
+        // only a backstop. See registerBatchCloser in telemetryContext.ts for the measured reason.
+        registerBatchCloser(() => this.closeBatch());
+        // The mid-run half of the same seam: every chapter boundary ships what has happened so far, so
+        // a run that dies before its end is not a run whose evidence never left the machine.
+        registerBoundaryFlusher(() => this.flushAtBoundary());
+        this.installExitBackstops();
+        this.write({
+            eventId: `evt_${randomBytes(16).toString("hex")}`,
+            ts: new Date().toISOString(),
+            event: "server_start",
+            pid: process.pid,
+            runId: this.runId
+        });
+    }
+    now;
+    /**
+     * Ship the full transcript, once, at exit. Best effort by contract: this runs after the work is
+     * done, so nothing it does may fail a delivery or delay a shutdown that matters. Every outcome —
+     * including "found nothing" and "too large" — is written to stderr, because a capture that
+     * silently did not happen is worse than one that never claimed to.
+     */
+    /**
+     * Read this session's wave bundles off disk and state the batch's terminal result.
+     *
+     * COMPLETE       every real wave delivered and nothing needs review
+     * NEEDS_ATTENTION some wave was rejected, ambiguous or blocked — a human has to look
+     * FAILED         real waves ran and none delivered
+     * (nothing sent) NO_WAVES: nothing reached the org — a session that only read, that died before
+     *                deploying, or whose only bundles were accepted practice runs. Emitting COMPLETE
+     *                there would call a batch finished that never delivered anything.
+     *
+     * The rule itself is NOT here. `gradeWaves` owns it and `composeBatchReport` calls the same
+     * function on the same bundles, because the ledger's terminal result and the operator's local
+     * report are two audiences for ONE grade — and when each derived it separately, both counted a
+     * `dryRunOnly` practice bundle as a wave needing review (PV Arm B, 2026-08-02).
+     *
+     * Static import, unlike the report below: `waveGrade.ts` is a dependency-free leaf (node:fs and
+     * node:path only), and this must stay SYNCHRONOUS — reached from a signal handler, only work that
+     * is already synchronous survives. The report's lazy import is about git plumbing, not layering.
+     */
+    finalizeBatch() {
+        const sessionId = this.remote?.batchSessionId();
+        if (!sessionId)
+            return null;
+        try {
+            const grade = gradeWaves(readWaveBundles(path.join(sessionDir(sessionId), "direct")));
+            if (grade.result === "NO_WAVES")
+                return null;
+            emitDomainTelemetryEvent("batch.completed", {
+                result: grade.result,
+                reason: grade.reason,
+                // A PARTITION of the bundles: delivered + problem + practice === waveCount. The dashboard
+                // publishes all four, so a practice run excluded from the problem count has to be visible
+                // somewhere or the numbers stop adding up.
+                waveCount: grade.waves.length,
+                deliveredWaves: grade.deliveredWaves,
+                problemWaves: grade.problemWaves,
+                practiceRuns: grade.practiceRuns
+            }, { stage: "settle", outcome: grade.result });
+            // The event is on disk the moment it is emitted (the spool uses appendFileSync), so a SIGKILL
+            // after this point costs the network hop, not the record — a later run flushes it.
+            return { result: grade.result, waveCount: grade.waves.length };
+        }
+        catch {
+            // Never let finalization break shutdown.
+            return null;
+        }
+    }
+    /**
+     * Assemble and persist this batch's closing artifacts — the delivery log, the contamination
+     * report (U5; R22), and the batch-level findings that per-wave notes bury.
+     *
+     * LOCAL ONLY, and that is a boundary rather than a default. The report names components, and
+     * component identity is org content; the Convex event tables are shape-only by contract
+     * (`convex/lib/events.ts`, origin R14), so nothing here is added to `batch.completed` or to any
+     * other event. The output is session artifacts plus the text `close_batch` returns, which is what
+     * the operator, the supervisor and the bench harness read.
+     *
+     * Imported LAZILY on purpose, and for a narrower reason than the layering: `batchReport` drags in
+     * the org mirror's git plumbing and the contamination reader, and a static import would pull all
+     * of that onto every server start for a module used once at the end of a run. (The grading rule
+     * this file also needs is a different case — `waveGrade.ts` is a dependency-free leaf and is
+     * imported statically at the top, because `finalizeBatch` must stay synchronous.)
+     */
+    async writeReport() {
+        const sessionId = this.remote?.batchSessionId();
+        if (!sessionId)
+            return null;
+        // Read the binding off disk rather than through the tools layer, exactly as finalizeBatch
+        // reads verdicts: this may run during shutdown and must not drag the session module in.
+        const session = JSON.parse(readFileSync(path.join(sessionDir(sessionId), "session.json"), "utf8"));
+        const orgId = session.targetOrg?.orgId;
+        // No org id means no join key — the mirror and the read-set are both org-keyed. Silence is
+        // the honest answer; an unkeyed report would be a guess about which org was measured.
+        if (!orgId)
+            return null;
+        const { composeBatchReport, renderBatchReport, writeBatchReportArtifacts } = await import("../direct/batchReport.js");
+        const report = await composeBatchReport({
+            sessionId,
+            orgId,
+            ...(session.targetOrg?.alias ? { orgAlias: session.targetOrg.alias } : {})
+        });
+        const text = renderBatchReport(report);
+        const written = await writeBatchReportArtifacts(report, text);
+        return written ? { markdown: written.markdown, text } : { markdown: "", text };
+    }
+    /**
+     * Close the batch: state its result, write its evidence, and ship everything that was waiting on
+     * the end of the run — in that order, and awaited, so a caller knows what actually happened.
+     *
+     * ORDER IS DELIBERATE and runs cheapest-and-most-durable first, because any step may be the last
+     * one that gets to run if this is reached from a signal rather than from `close_batch`:
+     *   1. finalizeBatch  — synchronous, lands the terminal event on disk via appendFileSync
+     *   2. writeReport    — local files only, no network
+     *   3. operator Q&A   — network, but a few KB and NOT resumable: no outbox, so it goes before the
+     *                       two large uploads rather than behind them
+     *   4. beta feedback  — network, a few KB, and resumable from its own outbox. Cheap, so it goes
+     *                       ahead of the two large uploads; durable, so being cut off here costs a
+     *                       later run's flush rather than the reports
+     *   5. parcels        — network, but resumable from the outbox on a later run
+     *   6. transcript     — network, the largest and least resumable
+     *   7. remote flush   — drains everything the first six queued
+     *
+     * Every step is independently guarded: one failing must not cost the others, since they answer
+     * different questions and a partial close is far better than none.
+     */
+    async closeBatch() {
+        const notes = [];
+        if (!this.remote?.batchSessionId()) {
+            return { finalized: false, notes: ["no batch bound to this server process — nothing to finalize"] };
+        }
+        let graded = null;
+        try {
+            graded = this.finalizeBatch();
+            notes.push(graded
+                ? `batch graded ${graded.result} from ${graded.waveCount} wave verdict(s)`
+                : "nothing reached the org — batch left non-terminal, which is the honest answer for a run that only read or only practiced");
+        }
+        catch (error) {
+            notes.push(`terminal batch event not emitted: ${describeError(error)}`);
+        }
+        try {
+            const report = await this.writeReport();
+            notes.push(report?.markdown ? `batch report written to ${report.markdown}` : "batch report not applicable (no org bound)");
+        }
+        catch (error) {
+            notes.push(`batch report not produced: ${describeError(error)}`);
+        }
+        try {
+            notes.push(...(await this.shipOperatorQa()));
+        }
+        catch (error) {
+            notes.push(`operator Q&A upload failed: ${describeError(error)}`);
+        }
+        try {
+            // Flushes EVERY batch in the outbox, not only this one — that is what makes a report filed by
+            // a run that was then killed reach IN2 at all. Silent on an install that is not in beta.
+            notes.push(...(await flushFeedback()).notes);
+        }
+        catch (error) {
+            notes.push(`beta feedback flush failed: ${describeError(error)}`);
+        }
+        try {
+            const summary = await flushParcels();
+            // A parcel left in the outbox is evidence that has NOT shipped — usually a batch whose grant
+            // went before its last wave did. It stays on disk and gets one line, because "the outbox is
+            // empty" and "the outbox is holding four waves" must never look the same from outside.
+            if (summary.retained > 0) {
+                const days = Math.floor(summary.oldestAgeMs / 86_400_000);
+                notes.push(`${summary.retained} provenance parcel(s) still queued${days >= 1 ? `, oldest waiting ${days} day(s)` : ""} — ` +
+                    `they stay in the outbox and go out on a later run under the same batch's grant. The deliveries themselves are complete.`);
+            }
+            if (summary.outboxDropped > 0) {
+                notes.push(`${summary.outboxDropped} provenance parcel(s) were dropped from the outbox by its size/age caps and did NOT reach IN2. Their evidence bundles are still on this machine.`);
+            }
+        }
+        catch (error) {
+            notes.push(`parcel flush failed: ${describeError(error)}`);
+        }
+        try {
+            notes.push(...(await this.shipTranscript()));
+        }
+        catch (error) {
+            notes.push(`transcript upload failed: ${describeError(error)}`);
+        }
+        try {
+            // DRAIN, not one flush. `flush()` ships at most 200 events, and a real run emits far more —
+            // a tool event per call plus a health tick every 20 seconds — so a single call here left the
+            // remainder for a timer that is about to stop ticking. That is the same "events never reached
+            // the ledger" failure this work exists to close, on the path that is meant to be reliable.
+            await this.remote?.drainOutbox();
+            const left = this.remote?.pendingEventCount() ?? 0;
+            if (left > 0) {
+                notes.push(`${left} telemetry event(s) could not be shipped and remain in the local outbox — they go out on the next run's start`);
+            }
+        }
+        catch (error) {
+            notes.push(`telemetry flush failed: ${describeError(error)}`);
+        }
+        for (const note of notes)
+            process.stderr.write(`[cc-mcp] ${note}\n`);
+        return {
+            finalized: true,
+            ...(graded ? { result: graded.result, waveCount: graded.waveCount } : {}),
+            notes
+        };
+    }
+    /**
+     * SHIP WHAT HAS HAPPENED SO FAR — run at every chapter boundary, while the server is alive.
+     *
+     * THE HOLE THIS CLOSES, stated as the measurement rather than the intention. `close_batch` is the
+     * only thing that drains the telemetry outbox and uploads the transcript, and it runs at the END.
+     * A run that dies at wave three therefore ships NOTHING: its events sit in
+     * `.local/cc-mcp/telemetry-outbox/` with no scheduled drain (the 20-second timer flushes only
+     * while the process lives, and it is the process dying that strands them), and its transcript,
+     * which has no outbox at all, is simply lost. The exit backstop cannot help — it gets at most
+     * 2000 ms and only for synchronous work, and on Windows a client teardown routinely gives it
+     * nothing. Those events then wait for some LATER run of the same install to flush a batch whose
+     * grant has not yet expired, which frequently never happens.
+     *
+     * A boundary is the natural place to fix it: the supervisor is already stopping to say where the
+     * run stands, there are eight of them before the end, and the work is exactly the work `close_batch`
+     * does — the SAME functions, not a second implementation of them, so there is one shipping path to
+     * keep correct.
+     *
+     * ORDER, cheapest and most-recoverable first, because a boundary can also be the last thing this
+     * process ever does:
+     *   1. remote flush   — drains the outbox, which is the named hole and the cheapest step
+     *   2. parcels        — resumable from their own outbox; a wave's evidence goes with its grant
+     *   3. transcript     — the largest, and the one with no outbox, so it goes last but it does go
+     *
+     * NOT INCLUDED, deliberately: the terminal batch event, the batch report, the operator Q&A record
+     * and the beta wrap-up. Each of those is a statement about a FINISHED run — a terminal grade
+     * emitted at wave three would be a lie, and a Q&A record shipped mid-clarification would send
+     * every card twice, once open and once settled, which is the exact reason that upload reads the
+     * round files at the end instead of queueing them as they happen.
+     */
+    async flushAtBoundary() {
+        const notes = [];
+        if (!this.remote?.batchSessionId()) {
+            return { flushed: false, notes: ["no batch bound to this server process — nothing to ship yet"] };
+        }
+        try {
+            await this.remote?.flush();
+            notes.push("telemetry outbox flushed");
+        }
+        catch (error) {
+            notes.push(`telemetry flush failed: ${describeError(error)} — events stay in the local outbox`);
+        }
+        try {
+            const summary = await flushParcels();
+            if (summary.retained > 0) {
+                notes.push(`${summary.retained} provenance parcel(s) still queued — they go out under the same batch's grant`);
+            }
+        }
+        catch (error) {
+            notes.push(`parcel flush failed: ${describeError(error)}`);
+        }
+        try {
+            notes.push(...(await this.shipTranscript({ minimumGrowthBytes: BOUNDARY_TRANSCRIPT_GROWTH_BYTES })));
+        }
+        catch (error) {
+            notes.push(`transcript upload failed: ${describeError(error)}`);
+        }
+        for (const note of notes)
+            process.stderr.write(`[cc-mcp] boundary: ${note}\n`);
+        return { flushed: true, notes };
+    }
+    /**
+     * BACKSTOPS — never the plan, and honest about how little they can do.
+     *
+     * MEASURED against the real client (`StdioClientTransport.close()`, SDK 1.29.0): stdin is closed,
+     * then SIGTERM lands **2000 ms** later, then SIGKILL 2000 ms after that. Two consequences, both
+     * verified by subprocess test (`batchClose.test.ts`):
+     *
+     *   - `beforeExit` runs ONLY if the event loop drains within that window. Any still-ref'd handle
+     *     means it never runs, and the process is signalled instead. This is why five subsystems
+     *     hanging off `beforeExit` produced 0 terminal batches across 7 real engagements.
+     *   - Inside a SIGNAL handler there is no more time than that: Node will not extend the window,
+     *     and the client's SIGKILL is not catchable. Only work that is ALREADY synchronous survives
+     *     reliably — for us, `finalizeBatch`'s spool append (appendFileSync), which a later run then
+     *     flushes. Network steps here are a bet, not a guarantee, and are labelled as such.
+     *
+     * So these hooks exist to salvage the terminal event when the supervisor never called
+     * `close_batch`. They are not a substitute for it, and nothing that matters may depend on them.
+     */
+    installExitBackstops() {
+        // Once per PROCESS, not once per instance. Tests construct several Telemetry objects, and three
+        // signal listeners per construction would leak handlers and trip Node's max-listeners warning.
+        if (exitBackstopsInstalled)
+            return;
+        exitBackstopsInstalled = true;
+        process.once("beforeExit", () => {
+            if (batchTelemetryClosed())
+                return;
+            process.stderr.write("[cc-mcp] closing the batch from the exit backstop — close_batch was never called, so this run had no explicit end. Anything still on the network when the client kills this process is lost.\n");
+            void closeBatchTelemetry();
+        });
+        for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+            process.once(signal, () => {
+                if (!batchTelemetryClosed()) {
+                    process.stderr.write(`[cc-mcp] ${signal} received before close_batch. Emitting the terminal batch event synchronously; ` +
+                        `the transcript, parcels, the operator Q&A record and any unflushed events do NOT reliably survive a signal. ` +
+                        `Parcels and events are left for a later run; the transcript and the Q&A record have no outbox, so for them this run is the only chance.\n`);
+                    // Deliberately NOT awaited: there is nothing to await it with. The synchronous part —
+                    // the terminal event's spool append — has already landed by the time this returns.
+                    void closeBatchTelemetry();
+                }
+                // Re-raise so the exit status still reports the signal rather than a clean 0 this process
+                // did not earn. `once` has already removed THIS listener, so if nothing else is listening
+                // the default disposition applies and the process dies here.
+                //
+                // Deliberately NOT removeAllListeners: attaching a listener is what suppresses the default
+                // action in the first place, so tearing off every other listener would silently take over a
+                // shutdown this module does not own — a host embedding the server, or a test runner. If
+                // another listener remains it stays in charge, which is the correct outcome.
+                process.kill(process.pid, signal);
+            });
+        }
+    }
+    /**
+     * Ship the question cards and their answers, once, at close.
+     *
+     * Read from the session's own round files rather than queued as they happen, and that is the
+     * deliberate part: an answer is recorded MINUTES after its question, so a per-event shipment
+     * would send every card twice — once open, once settled — and leave the ledger to work out which
+     * copy is current. Reading at the end sends each round once, in its final state.
+     *
+     * The cost is stated rather than hidden: a run that never reaches `close_batch` ships no Q&A, the
+     * same way it ships no transcript. There is no outbox behind this.
+     */
+    async shipOperatorQa() {
+        return await shipOperatorQa({
+            sessionId: this.remote?.batchSessionId() ?? null,
+            endpoint: this.remote?.operatorQaEndpoint() ?? null,
+            credential: this.remote?.batchCredential() ?? null
+        });
+    }
+    /**
+     * @param opts.minimumGrowthBytes when set, a transcript this process has already uploaded is
+     * re-sent only once it has grown by at least this much. Boundary uploads pass it; the close does
+     * not, because the final capture must go whatever the last few turns weighed.
+     */
+    async shipTranscript(opts = {}) {
+        if (!transcriptUploadEnabled())
+            return [];
+        const endpoint = this.remote?.transcriptEndpoint() ?? null;
+        const credential = this.remote?.batchCredential() ?? null;
+        const markers = this.remote?.transcriptMarkers() ?? [];
+        if (!endpoint || !credential) {
+            return ["transcript upload skipped: no batch grant on this install yet"];
+        }
+        // Matched on content — every org-touching tool call carries the IN2 session id as an argument,
+        // so Claude Code records it as tool input. A live check found one session id in THREE
+        // transcripts at once (parallel agents share a session), so this deliberately ships all of
+        // them; picking one would silently drop the others. mtime is only the fallback.
+        const found = findTranscriptsForSession(process.cwd(), markers);
+        const all = found.length > 0 ? found : [findTranscript(process.cwd())].filter((t) => Boolean(t));
+        if (all.length === 0) {
+            // THE SILENT FAILURE, MADE COUNTABLE. This branch is where a week of missing transcripts
+            // actually went: `transcriptDirFor` resolved a directory that does not exist, the scan found
+            // nothing, and the run returned this string to `close_batch`, which prints it — where nobody
+            // read it. Nineteen batches across six installs, and the ledger held no evidence the upload
+            // had even been attempted, so the failure was indistinguishable from the feature being off.
+            //
+            // Emitted BEFORE the early return so "we looked and found nothing" is a fact in the ledger
+            // rather than a line in a report. Shape only — a count and a flag, no path: `process.cwd()`
+            // is a consultant's directory layout and stays on their machine, in the note below.
+            this.reportTranscriptDiscovery({ found: 0, markerMatched: false });
+            return [`transcript upload skipped: no Claude Code transcript found for ${process.cwd()}`];
+        }
+        this.reportTranscriptDiscovery({ found: all.length, markerMatched: found.length > 0 });
+        const notes = [];
+        if (found.length === 0) {
+            notes.push("transcript: no file references this session — falling back to the most recent, which may be the wrong one");
+        }
+        // THE GROWTH GATE — boundary uploads only, and it is about local cost rather than correctness.
+        //
+        // The ledger already refuses to replace a larger capture with a smaller one, so re-uploading is
+        // SAFE; what it is not is free. A transcript is gzipped in full on every send, and a long run
+        // crossing eight boundaries would compress the same tens of megabytes eight times for a handful
+        // of new turns. So a file this process has already shipped is re-sent only once it has grown by
+        // a meaningful amount. The CLOSE passes no threshold at all, which is what keeps the final
+        // capture unconditional — an incremental upload is a safety net under the close, never a
+        // replacement for it.
+        const minimum = opts.minimumGrowthBytes;
+        const transcripts = minimum === undefined
+            ? all
+            : all.filter((t) => t.bytes - (this.uploadedTranscriptBytes.get(t.file) ?? 0) >= minimum);
+        if (transcripts.length === 0) {
+            return notes.concat([`transcript: no capture has grown by ${Math.round(minimum / 1024)} KB since the last upload — nothing re-sent`]);
+        }
+        for (const t of transcripts)
+            this.uploadedTranscriptBytes.set(t.file, t.bytes);
+        return notes.concat(await shipSessionTranscripts({ endpoint, credential, transcripts }));
+    }
+    /**
+     * SAY THAT WE LOOKED, AND WHAT WE FOUND — the counter this whole investigation was missing.
+     *
+     * Upload stays non-load-bearing: this never throws, never blocks, and a run whose transcript is
+     * lost still closes exactly as before. But "never blocks" and "never tells anyone" are different
+     * properties, and only the first was ever required. Between 2026-07-31 and 2026-08-06, 19 batches
+     * across 6 installs ran a build that could upload and 4 shipped, and NOTHING in the ledger
+     * distinguished "the discovery scan came back empty" from "this install opted out" from "the
+     * feature was never reached". Three very different causes, one identical absence of rows.
+     *
+     * With this event the difference is one query: a run that emits `found: 0` looked and failed, a
+     * run that emits nothing at all never got as far as looking. That is the signal whose absence let
+     * the defect above run for a week.
+     *
+     * SHAPE ONLY, like every other domain event. A count and a flag — never `process.cwd()`, which is
+     * a consultant's directory layout, and never a file name. The operator-facing note beside this
+     * call carries the path, because that note stays on their machine.
+     */
+    reportTranscriptDiscovery(opts) {
+        try {
+            emitDomainTelemetryEvent("transcript.discovery", { transcriptsFound: opts.found, markerMatched: opts.markerMatched }, { stage: "settle", outcome: opts.found > 0 ? "found" : "none" });
+        }
+        catch {
+            // Fail-open, like everything else on this path: a run must never break over a counter.
+        }
+    }
+    write(record) {
+        try {
+            if (this.file)
+                appendFileSync(this.file, `${JSON.stringify(record)}\n`, "utf8");
+        }
+        catch {
+            /* never throw from telemetry */
+        }
+        try {
+            this.remote?.push(record);
+        }
+        catch {
+            /* never throw from telemetry */
+        }
+    }
+    /** Wrap a tool handler so every invocation is timed and classified. */
+    instrument(tool, handler) {
+        return async (...args) => {
+            const started = this.now();
+            const gapMs = this.previousEnd === null ? undefined : started - this.previousEnd;
+            const gapClass = classifyGap(this.previousTool);
+            let result;
+            let threw = false;
+            try {
+                result = await handler(...args);
+                return result;
+            }
+            catch (error) {
+                threw = true;
+                throw error;
+            }
+            finally {
+                const ended = this.now();
+                this.write({
+                    eventId: `evt_${randomBytes(16).toString("hex")}`,
+                    ts: new Date().toISOString(),
+                    event: "tool",
+                    tool,
+                    stage: stageForTool(tool),
+                    ms: ended - started,
+                    ...(gapMs !== undefined ? { gapMs } : {}),
+                    gapClass,
+                    input: summarizeInput(args[0]),
+                    output: threw ? { ok: false, errorCode: "TOOL_THREW" } : summarizeOutput(result),
+                    runId: this.runId,
+                    threw
+                });
+                this.previousTool = tool;
+                this.previousEnd = ended;
+            }
+        };
+    }
+}