in2-agent-server 0.20260821.185429

package/dist/core/transcriptUpload.js

@@ -0,0 +1,516 @@
+import { createReadStream, existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createGzip } from "node:zlib";
+import { pipeline } from "node:stream/promises";
+// FULL session transcript capture — ON BY DEFAULT since 2026-07-31; CC_MCP_TRANSCRIPT_UPLOAD=0 opts
+// out. (It shipped off-by-default and this line went on saying so for longer than the default held;
+// `transcriptUploadEnabled` below is the authority, and it treats an unset variable as ON.)
+//
+// Why this is separate from telemetry rather than a flag on it. Telemetry ships shapes: tool name,
+// outcome, duration, never a metadata body, and the install prompt a consultant approves is written
+// to match. A Claude Code transcript is content — every prompt, every tool result, every record the
+// model read, and anything pasted into the chat, which on real machines has included activation
+// codes. Letting that ride on telemetry's consent would make the prompt a lie.
+//
+// So: its own env var and its own endpoint, never a flag on telemetry's consent — and, since the
+// default was inverted, `announce()` states on stderr at EVERY startup that the whole session is
+// going to be sent and how to stop it. That announcement is what carries the disclosure the
+// off-by-default used to carry; the install prompt (routes/callback.ts) now names transcript upload
+// as part of what installing grants.
+//
+// Nothing here is load-bearing for delivery. Every failure path returns a reason and gives up.
+/** The slug length past which Claude Code truncates and appends a hash. `A2e` in the 2.1.221 binary. */
+const CLAUDE_SLUG_MAX = 200;
+/**
+ * Claude Code's hash of a project path — JavaScript's ordinary signed 32-bit string hash.
+ *
+ * Transcribed from the 2.1.221 binary rather than reconstructed from its behaviour:
+ *
+ *   function nat(e){let t=0;for(let r=0;r<e.length;r++)t=(t<<5)-t+e.charCodeAt(r)|0;return t}
+ *   function Lig(e){return Math.abs(nat(e)).toString(36)}
+ *
+ * The `|0` is load-bearing and not a tidy-up: it forces the signed 32-bit wrap on every iteration,
+ * which is what makes the result reproducible here at all. Applied to the ORIGINAL path, never the
+ * replaced slug — two different paths can reduce to the same 200-character prefix, and this is the
+ * only thing that tells them apart.
+ */
+function claudePathHash(cwd) {
+    let hash = 0;
+    for (let i = 0; i < cwd.length; i += 1)
+        hash = ((hash << 5) - hash + cwd.charCodeAt(i)) | 0;
+    return Math.abs(hash).toString(36);
+}
+/**
+ * Claude Code's project-directory slug, as `GC(e)` computes it in the 2.1.221 binary:
+ *
+ *   function GC(e){let t=e.replace(/[^a-zA-Z0-9]/g,"-");if(t.length<=A2e)return t;
+ *                  return `${t.slice(0,A2e)}-${Lig(e)}`}      // A2e=200
+ *
+ * TWO RULES, AND ONLY THE FIRST HAD EVER BEEN IMPLEMENTED HERE.
+ *
+ * (1) EVERY NON-ALPHANUMERIC BYTE becomes `-`. This module replaced `[/\\]` only, and that is what
+ * made the whole feature look like it had never shipped. Measured against the live ledger on
+ * 2026-08-06: 19 batches across 6 installs ran a build that could upload and 4 uploaded, all from
+ * ONE install — and those four were the only runs whose cwd happened to be alphanumeric-plus-
+ * slashes (`~/Projects/in2-runs`, `~/Projects/oss`), where the broken rule is accidentally correct.
+ * Every other run resolved to a directory that does not exist, found no transcript, and gave up
+ * with a reason that went nowhere. A single dot was enough: `.claude/worktrees/…`, a folder named
+ * `acme.demo`, a space in `Config Agent Folder` (live-caught 2026-08-03, PR #78), or a Windows
+ * drive colon, which is not a separator and so survived slash-replacement as `C:`.
+ *
+ * (2) A SLUG OVER 200 CHARACTERS is truncated to 200 and given `-<hash of the original path>`.
+ * From PR #78, verified here against the binary. This one is LATENT, not observed: the longest slug
+ * in this machine's `~/.claude/projects/` is 140 characters and none of the 72 recoverable paths
+ * reaches the cap. It is carried because a consultant's path is not ours to predict — a deep
+ * worktree, a Windows profile directory, a long client folder name — and because missing it
+ * produces exactly the silent no-transcript failure this module exists to end.
+ *
+ * Checked against this machine's real `~/.claude/projects/` (2026-08-07): the old rule reproduced
+ * 17 of 72 directories; this one reproduces 68. The remaining 4 are worktrees renamed after the
+ * fact, whose stored cwd names a different directory entirely — no encoder recovers those, and
+ * nothing here pretends to.
+ *
+ * NOT IMPLEMENTED, deliberately: the binary's `PN(e)` ALSO scans the projects root for directories
+ * beginning with the truncated prefix, so it can find a transcript whose hash no longer matches
+ * (a path that moved). That is a recovery path for a case nothing here has ever hit, and the flat
+ * scan it would add is the cost `findSubagentTranscripts` was explicitly written to avoid. If a
+ * capped path is ever observed to miss, that is the next thing to add.
+ */
+function claudeProjectSlug(cwd) {
+    const replaced = cwd.replace(/[^a-zA-Z0-9]/g, "-");
+    if (replaced.length <= CLAUDE_SLUG_MAX)
+        return replaced;
+    return `${replaced.slice(0, CLAUDE_SLUG_MAX)}-${claudePathHash(cwd)}`;
+}
+/** Claude Code writes each session to `~/.claude/projects/<slug>/<uuid>.jsonl`. */
+export function transcriptDirFor(cwd, home = os.homedir()) {
+    return path.join(home, ".claude", "projects", claudeProjectSlug(cwd));
+}
+/** A session's subagent transcripts live one directory down: <projectDir>/<sessionUuid>/subagents/ */
+export function subagentDirFor(cwd, claudeSessionId, home = os.homedir()) {
+    return path.join(transcriptDirFor(cwd, home), claudeSessionId, "subagents");
+}
+export function isSubagentTranscript(t) {
+    return typeof t.agentId === "string";
+}
+/**
+ * The transcript for the session this server is serving.
+ *
+ * The MCP server is spawned BY Claude Code and inherits its working directory, so the project
+ * directory resolves exactly. Which file inside it is a heuristic — the newest by mtime — because
+ * an MCP server is told nothing about its session id. That is right in practice: the live session
+ * is the one being appended to. It is wrong if two sessions share a cwd and the other one is busier,
+ * which is why the result carries the id and the caller records it.
+ */
+export function findTranscript(cwd, home = os.homedir()) {
+    const dir = transcriptDirFor(cwd, home);
+    if (!existsSync(dir))
+        return null;
+    let best = null;
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith(".jsonl"))
+            continue;
+        try {
+            const st = statSync(path.join(dir, name));
+            if (!st.isFile())
+                continue;
+            if (!best || st.mtimeMs > best.modifiedMs) {
+                best = {
+                    file: path.join(dir, name),
+                    claudeSessionId: name.replace(/\.jsonl$/, ""),
+                    bytes: st.size,
+                    modifiedMs: st.mtimeMs
+                };
+            }
+        }
+        catch {
+            // Unreadable entry — skip it rather than fail the sweep.
+        }
+    }
+    return best;
+}
+/**
+ * Every transcript in this project that references the IN2 session — matched on content, not mtime.
+ *
+ * The first version of this picked the newest file and called it "the" transcript. Checking that
+ * against real data (2026-07-31) showed the assumption was wrong in kind, not degree: one IN2
+ * session id appeared in THREE Claude Code transcripts at once — 190, 195 and 40 occurrences —
+ * because parallel agent sessions share a session. There is no single transcript to find.
+ *
+ * Matching is a plain substring scan for the session id, which every org-touching tool call carries
+ * as an argument and Claude Code therefore records as tool input. The activation code works too and
+ * is accepted as a marker, but is deliberately never logged or stored.
+ *
+ * Newest first, so a caller that wants only the primary transcript can take the head.
+ */
+export function findTranscriptsForSession(cwd, markers, home = os.homedir(), opts = {}) {
+    const dir = transcriptDirFor(cwd, home);
+    const usable = markers.filter((m) => typeof m === "string" && m.length >= 8);
+    if (!existsSync(dir) || usable.length === 0)
+        return [];
+    const maxFiles = opts.maxFiles ?? 40;
+    const budget = opts.maxBytesScanned ?? 2 * 1024 * 1024 * 1024;
+    const candidates = [];
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith(".jsonl"))
+            continue;
+        try {
+            const st = statSync(path.join(dir, name));
+            if (!st.isFile())
+                continue;
+            candidates.push({ file: path.join(dir, name), claudeSessionId: name.replace(/\.jsonl$/, ""), bytes: st.size, modifiedMs: st.mtimeMs });
+        }
+        catch {
+            // Unreadable entry — skip.
+        }
+    }
+    candidates.sort((a, b) => b.modifiedMs - a.modifiedMs);
+    const matched = [];
+    let scanned = 0;
+    for (const c of candidates.slice(0, maxFiles)) {
+        if (scanned + c.bytes > budget)
+            break;
+        scanned += c.bytes;
+        try {
+            // Substring scan, no JSON parsing: these files reach tens of megabytes and the marker is an
+            // opaque id, so there is nothing to gain from understanding the structure.
+            const text = readFileSync(c.file, "utf8");
+            if (usable.some((m) => text.includes(m)))
+                matched.push(c);
+        }
+        catch {
+            // Unreadable file — skip rather than fail the sweep.
+        }
+    }
+    return matched;
+}
+/** Defensive cap on how many of one session's agents ship. Far above anything observed. */
+const MAX_SUBAGENTS = 100;
+/**
+ * The subagent transcripts belonging to one main session.
+ *
+ * WHY THIS EXISTS AS A SECOND FUNCTION rather than a flag on the scan above. `findTranscript*`
+ * enumerates the project directory flat, and that was not an oversight to fix in place: a recursive
+ * walk would content-scan every subagent file of every session the project ever ran looking for the
+ * marker, which on this machine is 540 files across 44 sessions for a batch that owns four of them.
+ *
+ * So the scan stays flat and this runs only under a main transcript the caller has ALREADY matched.
+ * The session's own uuid names the directory, so there is nothing to search for: at most one
+ * `readdirSync` per shipped main transcript, and no content scan at all.
+ *
+ * THE SUBAGENT FILES WERE NEVER SHIPPING, and the numbers say what that cost. Claude Code writes a
+ * `Task` subagent's turns to `<projectDir>/<sessionUuid>/subagents/agent-<id>.jsonl` and never into
+ * the parent file — measured across this machine's stored sessions on 2026-08-03, those files hold
+ * 26.0% of `output_tokens` and 13.8% of cache tokens. Every ledger total built from main
+ * transcripts alone was understating a fanned-out run by roughly that much.
+ *
+ * Each file has an `agent-<id>.meta.json` sidecar carrying `{agentType, description, name,
+ * toolUseId, spawnDepth}` — present for all 540 of them. It is read here rather than derived later
+ * because it exists ONLY on the machine that ran the agents; the transcript itself never states
+ * which agent type produced it or what the parent asked for. `toolUseId` is deliberately not
+ * carried: it addresses a tool call in a transcript nobody joins on, and the fields that are
+ * carried are the ones a ledger reader needs to tell an analyzer from a reviewer.
+ *
+ * A missing or unparseable sidecar is not a failure — the transcript still ships, with empty meta.
+ * Sorted by agent id so a run's uploads are reported in a stable order twice.
+ */
+export function findSubagentTranscripts(cwd, claudeSessionId, home = os.homedir(), opts = {}) {
+    const dir = subagentDirFor(cwd, claudeSessionId, home);
+    if (!existsSync(dir))
+        return { agents: [], skipped: 0 };
+    const maxAgents = opts.maxAgents ?? MAX_SUBAGENTS;
+    const found = [];
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return { agents: [], skipped: 0 };
+    }
+    for (const name of names.sort()) {
+        const agentId = /^agent-(.+)\.jsonl$/.exec(name)?.[1];
+        if (!agentId)
+            continue;
+        const file = path.join(dir, name);
+        try {
+            const st = statSync(file);
+            if (!st.isFile())
+                continue;
+            found.push({
+                file,
+                claudeSessionId,
+                agentId,
+                bytes: st.size,
+                modifiedMs: st.mtimeMs,
+                meta: readSubagentMeta(path.join(dir, `agent-${agentId}.meta.json`))
+            });
+        }
+        catch {
+            // Unreadable entry — skip it rather than fail the sweep.
+        }
+    }
+    // Truncation is REPORTED, never silent: a run whose agents were partly dropped must not read the
+    // same as one whose agents all shipped. The caller turns this into an operator-visible note.
+    return { agents: found.slice(0, maxAgents), skipped: Math.max(0, found.length - maxAgents) };
+}
+function readSubagentMeta(file) {
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const raw = parsed;
+        const str = (v) => (typeof v === "string" && v.length > 0 ? v : undefined);
+        const meta = {};
+        const agentType = str(raw.agentType);
+        if (agentType !== undefined)
+            meta.agentType = agentType;
+        const description = str(raw.description);
+        if (description !== undefined)
+            meta.description = description;
+        const name = str(raw.name);
+        if (name !== undefined)
+            meta.name = name;
+        if (Number.isSafeInteger(raw.spawnDepth) && raw.spawnDepth >= 0)
+            meta.spawnDepth = raw.spawnDepth;
+        return meta;
+    }
+    catch {
+        // No sidecar, or one that is not JSON. The transcript is still worth shipping without it.
+        return {};
+    }
+}
+/**
+ * ON BY DEFAULT. `CC_MCP_TRANSCRIPT_UPLOAD=0` is the way out.
+ *
+ * This inverted on 2026-07-31. It shipped opt-in because the payload is categorically unlike the
+ * rest of the ledger — shape-only everywhere else, the entire session here — and the default is now
+ * the other way because reconstructing what happened between two tool calls is the whole point of
+ * UAT and internal runs, and an opt-in nobody sets captures nothing.
+ *
+ * What has to stay true for that default to be honest, and what the rest of this module enforces:
+ *   - the install consent text names transcript upload explicitly (supervisorContract.ts). While
+ *     this was opt-in the prompt deliberately said nothing about it; a default that the consent
+ *     screen does not mention is the thing to avoid here.
+ *   - `announce` prints on EVERY startup, says what leaves and how to stop it.
+ *   - the grant is still the only authority for identity, so a transcript can only ever be
+ *     attributed to the batch whose credential uploaded it.
+ *
+ * Accepts "0", "false", "off" and "no" so an operator who reaches for the obvious spelling is not
+ * silently still uploading. Anything else — including unset — is on.
+ */
+const DISABLED_VALUES = new Set(["0", "false", "off", "no"]);
+export function transcriptUploadEnabled(env = process.env) {
+    const raw = env.CC_MCP_TRANSCRIPT_UPLOAD?.trim().toLowerCase();
+    return raw === undefined || raw === "" ? true : !DISABLED_VALUES.has(raw);
+}
+/**
+ * Say it out loud, every startup, in the operator's language.
+ *
+ * A capability that sends the whole session somewhere must never be discoverable only by reading
+ * source or env. If someone enabled this on a machine that later ran real client work, this line in
+ * the log is what makes that recoverable rather than invisible.
+ */
+export function announce(endpoint, log = (l) => process.stderr.write(`${l}\n`)) {
+    log(`[cc-mcp] FULL TRANSCRIPT UPLOAD IS ON (the default). The complete session — every prompt, ` +
+        `tool result and record read, including anything pasted into the chat, and the transcript of ` +
+        `every subagent this session dispatches — will be sent to ` +
+        `${endpoint ?? "the configured endpoint"} when this session ends. ` +
+        `Set CC_MCP_TRANSCRIPT_UPLOAD=0 to stop this.`);
+}
+/** gzip the transcript to a temp file. Streamed: a long session is tens of megabytes. */
+export async function packTranscript(file, tmpDir = os.tmpdir()) {
+    const out = path.join(tmpDir, `in2-transcript-${path.basename(file)}.gz`);
+    const { createWriteStream } = await import("node:fs");
+    await pipeline(createReadStream(file), createGzip(), createWriteStream(out));
+    return { path: out, bytes: statSync(out).size };
+}
+/**
+ * A meta value made safe to put in an HTTP header.
+ *
+ * `description` and `name` are MODEL-AUTHORED — the parent agent wrote them when it spawned the
+ * Task — so they are free text reaching a header field, where a newline is a header injection and a
+ * non-Latin-1 byte makes `fetch` throw and take the whole upload with it. Reduced to printable
+ * ASCII and capped, and an empty result means the header is simply not sent.
+ */
+function headerSafe(value, max = 200) {
+    if (value === undefined)
+        return undefined;
+    const cleaned = value.replace(/[^\x20-\x7E]+/g, " ").trim().slice(0, max).trim();
+    return cleaned.length > 0 ? cleaned : undefined;
+}
+/**
+ * The subagent headers, or `undefined` when the id itself cannot be one.
+ *
+ * THE ID GOES THROUGH THE SAME REDUCTION AS ITS SIBLINGS. It is not model-authored, but it is not
+ * validated either: it comes off a FILENAME — `/^agent-(.+)\.jsonl$/` over a directory entry — and
+ * a POSIX filename may hold every byte but `/` and NUL. Left raw it reached `fetch`, where one
+ * control byte throws inside the upload's try and degrades a perfectly readable transcript to
+ * "subagent transcript upload failed". The server caps this field at 128, so the client does too.
+ *
+ * NOTHING LEFT AFTER THE REDUCTION IS A REFUSAL, not a bare upload. `x-in2-agent-id` is the field
+ * that makes an upload a subagent: absent, the server records a MAIN row, and `record` then
+ * supersedes — deletes — the session's real main transcript with an analyzer's file.
+ */
+function subagentHeaders(t) {
+    const agentId = headerSafe(t.agentId, 128);
+    if (agentId === undefined)
+        return undefined;
+    const headers = { "x-in2-agent-id": agentId };
+    const agentType = headerSafe(t.meta.agentType, 64);
+    if (agentType)
+        headers["x-in2-agent-type"] = agentType;
+    const description = headerSafe(t.meta.description);
+    if (description)
+        headers["x-in2-agent-description"] = description;
+    const name = headerSafe(t.meta.name, 64);
+    if (name)
+        headers["x-in2-agent-name"] = name;
+    if (t.meta.spawnDepth !== undefined)
+        headers["x-in2-agent-spawn-depth"] = String(t.meta.spawnDepth);
+    return headers;
+}
+/**
+ * Ship it. The grant is the same batch-scoped credential telemetry uses, so a transcript can only
+ * ever be attributed to the batch whose credential sent it — the server derives identity from the
+ * grant and ignores anything the client claims.
+ *
+ * ONE UPLOAD PER FILE, subagents included, through this same route: same grant, same gzip, same
+ * 20 MB refuse-don't-truncate rule. A subagent adds headers and changes nothing else — it is a
+ * Claude Code transcript in every respect the server cares about, and giving it a second route
+ * would mean a second size rule and a second identity check to keep in step with this one.
+ */
+export async function uploadTranscript(opts) {
+    const maxBytes = opts.maxBytes ?? 20 * 1024 * 1024;
+    const fetchFn = opts.fetchFn ?? fetch;
+    // Before the compression, so a subagent that cannot be named does not cost a gzip of a file that
+    // is never going to be sent.
+    const subagent = isSubagentTranscript(opts.transcript) ? subagentHeaders(opts.transcript) : {};
+    if (subagent === undefined) {
+        return {
+            uploaded: false,
+            reason: `subagent agent id is empty once reduced to header-safe text — it stays on this machine at ${opts.transcript.file}`
+        };
+    }
+    let packed;
+    try {
+        packed = await packTranscript(opts.transcript.file, opts.tmpDir);
+    }
+    catch (error) {
+        return { uploaded: false, reason: `could not compress transcript: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (packed.bytes > maxBytes) {
+        // Refuse rather than truncate. A partial transcript that looks whole is worse than none: it
+        // would be analysed as if the missing turns never happened.
+        return {
+            uploaded: false,
+            reason: `compressed transcript is ${Math.round(packed.bytes / 1024 / 1024)} MB, over the ${Math.round(maxBytes / 1024 / 1024)} MB limit — it stays on this machine at ${opts.transcript.file}`
+        };
+    }
+    try {
+        const { readFileSync } = await import("node:fs");
+        const res = await fetchFn(opts.endpoint, {
+            method: "POST",
+            headers: {
+                "content-type": "application/gzip",
+                authorization: `Bearer ${opts.credential}`,
+                "x-in2-transcript-raw-bytes": String(opts.transcript.bytes),
+                "x-in2-claude-session-id": opts.transcript.claudeSessionId,
+                ...subagent,
+                ...(opts.recoveredReason ? { "x-in2-transcript-recovered": opts.recoveredReason } : {})
+            },
+            body: readFileSync(packed.path),
+            signal: AbortSignal.timeout(120_000)
+        });
+        if (!res.ok)
+            return { uploaded: false, reason: `HTTP ${res.status}` };
+        const body = (await res.json().catch(() => ({})));
+        // A 2xx MEANS "PROCESSED", NOT "KEPT". The ledger declines an upload that would replace a
+        // larger capture of the same (session, agent) with a smaller one, and says so in the body.
+        // Reading only the status here would report that as a successful upload — and "the client said
+        // it shipped" being true while the ledger held something else is the exact failure this whole
+        // path was fixed for. Not an error: nothing is lost, the better capture is already on file.
+        if (body.stored === false) {
+            return {
+                uploaded: false,
+                reason: `ledger kept the larger capture it already holds${body.reason ? ` (${body.reason})` : ""} — nothing was lost`
+            };
+        }
+        return { uploaded: true, storedBytes: body.storedBytes ?? packed.bytes };
+    }
+    catch (error) {
+        return { uploaded: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+    finally {
+        const { rmSync } = await import("node:fs");
+        try {
+            rmSync(packed.path, { force: true });
+        }
+        catch {
+            // Temp file cleanup is best effort.
+        }
+    }
+}
+/**
+ * Ship a session's transcripts — the main file, then every agent it dispatched — and say what went.
+ *
+ * HERE RATHER THAN IN `telemetry.ts` because it is upload orchestration, and it belongs beside the
+ * two functions it orchestrates. Discovery stays with the caller: which main transcripts belong to
+ * this batch is a session-marker question that only `telemetry.ts` holds the markers for.
+ *
+ * THE SUMMARY LINE IS THE POINT OF THE COUNTING. A run that fanned out to 40 agents would bury the
+ * rest of the closing report if each success got a line, and a run whose agents all silently failed
+ * to upload would look identical to one that dispatched none. So: successes are counted, failures
+ * are named individually, and the count is stated even when it is zero.
+ */
+export async function shipSessionTranscripts(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const home = opts.home ?? os.homedir();
+    const upload = opts.upload ?? uploadTranscript;
+    const notes = [];
+    let mainUploaded = 0;
+    let subUploaded = 0;
+    let subSkipped = 0;
+    for (const transcript of opts.transcripts) {
+        const result = await upload({ endpoint: opts.endpoint, credential: opts.credential, transcript });
+        if (result.uploaded)
+            mainUploaded += 1;
+        notes.push(result.uploaded
+            ? `transcript uploaded ${transcript.claudeSessionId} (${Math.round((result.storedBytes ?? 0) / 1024)} KB compressed from ${Math.round(transcript.bytes / 1024)} KB)`
+            : `transcript upload failed for ${transcript.claudeSessionId}: ${result.reason}`);
+        // The agents this session fanned out to. Enumerated ONLY under a main transcript that already
+        // matched, so the cost is one readdir per shipped file rather than a recursive walk.
+        //
+        // Attempted even when the main upload failed: the two are independent captures, and an oversize
+        // parent is no reason to leave the batch's analysis phase unrecorded as well.
+        const { agents, skipped } = findSubagentTranscripts(cwd, transcript.claudeSessionId, home, {
+            ...(opts.maxAgents !== undefined ? { maxAgents: opts.maxAgents } : {})
+        });
+        subSkipped += skipped;
+        for (const agent of agents) {
+            const agentResult = await upload({ endpoint: opts.endpoint, credential: opts.credential, transcript: agent });
+            if (agentResult.uploaded)
+                subUploaded += 1;
+            else
+                notes.push(`subagent transcript upload failed for ${agent.agentId}: ${agentResult.reason}`);
+        }
+    }
+    // Always plural. The noun covers both terms, so agreeing it with the total gives "1 main + 0
+    // subagent transcript" — a sentence whose grammar argues with the zero standing next to it.
+    notes.push(`uploaded ${mainUploaded} main + ${subUploaded} subagent transcripts`);
+    if (subSkipped > 0) {
+        notes.push(`${subSkipped} further subagent transcript(s) were NOT uploaded — this session exceeded the per-session cap`);
+    }
+    return notes;
+}
+/** Derive the transcript endpoint from the telemetry one — same host, same grant, different route. */
+export function transcriptEndpointFrom(telemetryEndpoint) {
+    try {
+        const u = new URL(telemetryEndpoint);
+        u.pathname = "/api/transcript/v1";
+        return u.toString();
+    }
+    catch {
+        return telemetryEndpoint.replace(/\/api\/telemetry\/v\d+$/, "/api/transcript/v1");
+    }
+}