@bongos/core 1.17.0

package/scripts/gds/session-cost.js

@@ -0,0 +1,393 @@
+#!/usr/bin/env node
+// scripts/gds/session-cost.js — ADR 0028 path 2 (#560).
+//
+// Capture the cost of an interactive builder session. Reads the Claude Code
+// session transcript JSONL (which carries per-turn `message.usage` token
+// counts) AND this session's ad-hoc subagents (#563 — Agent/Task spawns at
+// <project-dir>/<session-id>/subagents/...), prices them via src/bongos/llm-pricing.js,
+// and POSTs ONE cost_log row (category=api, source=session, source_ref=<session-id>).
+// Grader subprocess transcripts are excluded (already captured via the worker
+// envelope, #486) — see priceSubagents / the ADR 0028 non-double-count invariant.
+//
+// Designed to run automatically at session end via a `SessionEnd` hook
+// (.claude/settings.json), which pipes { session_id, transcript_path, cwd,
+// reason } as JSON on stdin. Also runnable by hand:
+//   node scripts/gds/session-cost.js --transcript <path> [--session <id>]
+//   node scripts/gds/session-cost.js            # newest transcript for $PWD
+//
+// CONTRACT: best-effort, NON-FATAL, idempotent.
+//   - exits 0 on every path (a SessionEnd hook must never break session exit).
+//   - no GDS session / 401 / missing transcript / $0 cost → quiet skip.
+//   - idempotent on (source='session', source_ref=session_id): re-running on the
+//     same session is a no-op (cost_log ON CONFLICT DO NOTHING). One row per
+//     session, written once at end — the SessionEnd seam fires exactly once.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { cliClient, loadSession, arg } = require('./cli-lib');
+const { priceUsage } = require('../../src/bongos/llm-pricing');
+
+
+// Claude Code encodes a project transcript dir by replacing every non-alnum
+// char in the cwd with '-' (e.g. /Users/x/Claude-OTB → -Users-x-Claude-OTB).
+function encodeCwd(cwd) {
+  return cwd.replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+// The grader (src/bongos/grader.js) spawns each worker as a `claude -p` subprocess,
+// which persists its OWN transcript in the SAME project dir as the interactive
+// session. Those are captured separately via the worker's cost envelope (#486),
+// so pricing one here would DOUBLE-COUNT grader spend (Lars review, #562). A
+// grader transcript's first user message is the worker system prompt — match it
+// to exclude it from the newest-file fallback. (The SessionEnd hook path is
+// unaffected: it passes an explicit transcript_path and never calls this.)
+const GRADER_WORKER_SIGNATURE = /You are the \*\*(Quality|Hacker|Narc|Efficiency)/;
+
+function firstUserText(file) {
+  // Scan only until the first user message — avoids fully parsing a large
+  // interactive transcript just to classify it.
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); } catch (_) { return ''; }
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let o;
+    try { o = JSON.parse(line); } catch (_) { continue; }
+    if (o && o.message && o.message.role === 'user') {
+      const c = o.message.content;
+      return typeof c === 'string' ? c : JSON.stringify(c);
+    }
+  }
+  return '';
+}
+
+function looksLikeGraderTranscript(file) {
+  return GRADER_WORKER_SIGNATURE.test(firstUserText(file).slice(0, 400));
+}
+
+function newestTranscriptFor(cwd) {
+  const dir = path.join(os.homedir(), '.claude', 'projects', encodeCwd(cwd));
+  let files;
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
+  } catch (_) {
+    return null;
+  }
+  if (!files.length) return null;
+  const withMtime = files.map((f) => {
+    const full = path.join(dir, f);
+    return { full, mtime: fs.statSync(full).mtimeMs };
+  });
+  withMtime.sort((a, b) => b.mtime - a.mtime);
+  // Newest transcript that is NOT a grader worker subprocess (those are #486's,
+  // not ours — see GRADER_WORKER_SIGNATURE). Fall back to the plain newest only
+  // if every candidate looks like a grader (shouldn't happen in practice).
+  const picked = withMtime.find((c) => !looksLikeGraderTranscript(c.full)) || withMtime[0];
+  console.error(`session-cost: no --transcript/stdin given; using newest non-grader transcript ${path.basename(picked.full)}`);
+  return picked.full;
+}
+
+// Read piped stdin (the SessionEnd hook payload) if any; null when run on a TTY.
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve(null);
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (c) => { data += c; });
+    process.stdin.on('end', () => resolve(data || null));
+    // guard: if nothing arrives promptly (non-TTY but not piped), don't hang
+    setTimeout(() => resolve(data || null), 400);
+  });
+}
+
+// --- Per-tier USD split (task 1344, System 1) --------------------------------
+// priceUsage() returns a per-tier `components` map; the ledger persists the
+// 4-way split so spend can be attributed to the tier it came from (cache_read
+// is the marathon sink). cache_write here SUMS the 5m + 1h creation tiers into
+// one figure (migration 123 has a single cache_write_usd column). Pure.
+function emptyTiers() {
+  return { fresh_input_usd: 0, cache_read_usd: 0, cache_write_usd: 0, output_usd: 0 };
+}
+// Fold one priceUsage().components object into a tier accumulator.
+function addComponents(acc, components) {
+  if (!components) return acc;
+  acc.fresh_input_usd += (components.input && components.input.usd) || 0;
+  acc.cache_read_usd += (components.cache_read && components.cache_read.usd) || 0;
+  acc.cache_write_usd += ((components.cache_write_5m && components.cache_write_5m.usd) || 0)
+                       + ((components.cache_write_1h && components.cache_write_1h.usd) || 0);
+  acc.output_usd += (components.output && components.output.usd) || 0;
+  return acc;
+}
+// Fold one tiers object into an accumulator (merging two priced subtrees).
+function addTiers(acc, t) {
+  if (!t) return acc;
+  acc.fresh_input_usd += Number(t.fresh_input_usd) || 0;
+  acc.cache_read_usd += Number(t.cache_read_usd) || 0;
+  acc.cache_write_usd += Number(t.cache_write_usd) || 0;
+  acc.output_usd += Number(t.output_usd) || 0;
+  return acc;
+}
+function roundTiers(t) {
+  return {
+    fresh_input_usd: Math.round((Number(t.fresh_input_usd) || 0) * 10000) / 10000,
+    cache_read_usd: Math.round((Number(t.cache_read_usd) || 0) * 10000) / 10000,
+    cache_write_usd: Math.round((Number(t.cache_write_usd) || 0) * 10000) / 10000,
+    output_usd: Math.round((Number(t.output_usd) || 0) * 10000) / 10000,
+  };
+}
+
+// Sum usage per model across the transcript, then price each model's total.
+function priceTranscript(transcriptPath) {
+  const raw = fs.readFileSync(transcriptPath, 'utf8');
+  const perModel = new Map(); // model -> {input, output, read, c5, c1h}
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let o;
+    try { o = JSON.parse(line); } catch (_) { continue; }
+    const msg = o && o.message;
+    const usage = msg && msg.usage;
+    // Skip non-API turns: `<synthetic>` is Claude Code's marker for locally
+    // generated messages (compaction, interrupts) — no real API call, usage is
+    // a zero placeholder. Pricing them would mislabel them as an unknown model.
+    if (!usage || !msg.model || msg.model === '<synthetic>') continue;
+    const m = perModel.get(msg.model) || { input: 0, output: 0, read: 0, c5: 0, c1h: 0 };
+    m.input += Number(usage.input_tokens) || 0;
+    m.output += Number(usage.output_tokens) || 0;
+    m.read += Number(usage.cache_read_input_tokens) || 0;
+    const cc = usage.cache_creation;
+    if (cc && (cc.ephemeral_5m_input_tokens != null || cc.ephemeral_1h_input_tokens != null)) {
+      m.c5 += Number(cc.ephemeral_5m_input_tokens) || 0;
+      m.c1h += Number(cc.ephemeral_1h_input_tokens) || 0;
+    } else {
+      m.c5 += Number(usage.cache_creation_input_tokens) || 0; // no breakdown → 5m
+    }
+    perModel.set(msg.model, m);
+  }
+  let total = 0;
+  const unknownModels = [];
+  const breakdown = [];
+  const tiers = emptyTiers();
+  for (const [model, m] of perModel) {
+    const synthUsage = {
+      input_tokens: m.input,
+      output_tokens: m.output,
+      cache_read_input_tokens: m.read,
+      cache_creation_input_tokens: m.c5 + m.c1h,
+      cache_creation: { ephemeral_5m_input_tokens: m.c5, ephemeral_1h_input_tokens: m.c1h },
+    };
+    const priced = priceUsage(model, synthUsage);
+    total += priced.usd;
+    addComponents(tiers, priced.components);
+    if (priced.unknown_model) unknownModels.push(model);
+    breakdown.push({ model, usd: priced.usd });
+  }
+  // Invariant: the four tiers sum to total (each priceUsage().usd is its own
+  // component sum). The cost ledger relies on this for the session/cron rows.
+  return { total, breakdown, unknownModels, tiers };
+}
+
+// Recursively collect *.jsonl under a dir (the session's subagents subtree).
+function listJsonlRecursive(dir) {
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return out; }
+  for (const e of entries) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...listJsonlRecursive(p));
+    else if (e.name.endsWith('.jsonl')) out.push(p);
+  }
+  return out;
+}
+
+// #563 (ADR 0028, Q2 gap): price this session's ad-hoc subagents. Agent/Task-tool
+// spawns persist at <project-dir>/<session-id>/subagents/...  — a sibling of the
+// main transcript FILE (<project-dir>/<session-id>.jsonl). Their token usage is
+// in no other ledger (the main transcript has 0 sidechain; #486 only covers the
+// grader). SKIP grader-signature transcripts: a grader run CAN nest inside a
+// subagents/ dir (an autonomous-builder subagent that ran a ship), and its cost
+// is already captured via the worker envelope (#486) — re-pricing it here would
+// double-count (the ADR 0028 invariant Lars flagged). Exclusion is by signature,
+// not location, precisely because the grader can appear in either place.
+function priceSubagents(sessionDir) {
+  const files = listJsonlRecursive(sessionDir);
+  let subagentTotal = 0;
+  let subagentFiles = 0;
+  let graderSkipped = 0;
+  const unknownModels = [];
+  const tiers = emptyTiers();
+  for (const f of files) {
+    if (looksLikeGraderTranscript(f)) { graderSkipped++; continue; }
+    let priced;
+    try { priced = priceTranscript(f); } catch (_) { continue; }
+    if (priced.total > 0) { subagentTotal += priced.total; subagentFiles++; }
+    addTiers(tiers, priced.tiers); // a $0 file contributes 0 → tiers stay == subagentTotal
+    unknownModels.push(...priced.unknownModels);
+  }
+  return { subagentTotal, subagentFiles, graderSkipped, unknownModels, tiers };
+}
+
+// Pure: turn a priced session (interactive transcript + subagent subtree) into
+// the cost_log row payload(s). Task 1344 splits the single legacy 'session' row
+// into TWO call-site-tagged rows — source='<base>:interactive' (source_ref =
+// sessionId) and '<base>:subagent' (source_ref = sessionId+':sub'), distinct on
+// the (source,source_ref) idempotency index — each carrying its tier split. A
+// cron-launched session sets OTB_COST_CRON_ROUTINE=<name> so base='cron:<name>'
+// instead of 'session'. The rows' amounts reconcile to the prior single-row
+// figure (priorSingle vs rowsTotal, equal within independent-rounding epsilon).
+function buildCostRows({ sessionId, inter, sub, cronRoutine }) {
+  const base = cronRoutine ? `cron:${cronRoutine}` : 'session';
+  const id8 = String(sessionId).slice(0, 8);
+  const unknownModels = [...new Set([...(inter.unknownModels || []), ...(sub.unknownModels || [])])];
+  const unkNote = unknownModels.length ? ` [unpriced model(s) priced as opus: ${unknownModels.join(',')}]` : '';
+  const round4 = (n) => Math.round((Number(n) || 0) * 10000) / 10000;
+
+  const rows = [];
+  const interAmt = round4(inter.total);
+  if (interAmt > 0) {
+    rows.push({
+      amount_usd: interAmt,
+      category: 'api',
+      source: `${base}:interactive`,
+      source_ref: sessionId,
+      description: `session ${id8} interactive — $${inter.total.toFixed(4)}${unkNote}`.slice(0, 1000),
+      tiers: roundTiers(inter.tiers),
+    });
+  }
+  const subAmt = round4(sub.subagentTotal);
+  if (subAmt > 0) {
+    const skipNote = sub.graderSkipped > 0 ? ` (skipped ${sub.graderSkipped} grader transcript(s) — in #486)` : '';
+    rows.push({
+      amount_usd: subAmt,
+      category: 'api',
+      source: `${base}:subagent`,
+      source_ref: `${sessionId}:sub`,
+      description: `session ${id8} subagent — ${sub.subagentFiles} file(s) $${sub.subagentTotal.toFixed(4)}${skipNote}${unkNote}`.slice(0, 1000),
+      tiers: roundTiers(sub.tiers),
+    });
+  }
+  const priorSingle = round4(inter.total + sub.subagentTotal);
+  // Degenerate guard: total>0 but each leg rounds to $0 → still log it as one
+  // interactive row so spend is never silently dropped.
+  if (rows.length === 0 && priorSingle > 0) {
+    rows.push({
+      amount_usd: priorSingle,
+      category: 'api',
+      source: `${base}:interactive`,
+      source_ref: sessionId,
+      description: `session ${id8} — $${priorSingle.toFixed(4)}${unkNote}`.slice(0, 1000),
+      tiers: roundTiers(addTiers(addTiers(emptyTiers(), inter.tiers), sub.tiers)),
+    });
+  }
+  const rowsTotal = round4(rows.reduce((s, r) => s + r.amount_usd, 0));
+  return { rows, base, priorSingle, rowsTotal, unknownModels };
+}
+
+async function main() {
+  // Watchdog: a SessionEnd hook must never stall session exit. If the read or
+  // the POST hangs (slow/offline network — fetch has no default timeout), bail
+  // after 6s. unref() so it never keeps the process alive on its own.
+  const watchdog = setTimeout(() => process.exit(0), 6000);
+  watchdog.unref();
+  try {
+    const stdinRaw = await readStdin();
+    let transcriptPath = arg('--transcript');
+    let sessionId = arg('--session');
+    let cwd = process.cwd();
+
+    if (stdinRaw) {
+      try {
+        const hook = JSON.parse(stdinRaw);
+        transcriptPath = transcriptPath || hook.transcript_path || null;
+        sessionId = sessionId || hook.session_id || null;
+        if (hook.cwd) cwd = hook.cwd;
+      } catch (_) { /* not JSON — ignore, fall through to defaults */ }
+    }
+
+    if (!transcriptPath) transcriptPath = newestTranscriptFor(cwd);
+    if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+      // nothing to price — quiet skip
+      process.exit(0);
+    }
+    if (!sessionId) sessionId = path.basename(transcriptPath, '.jsonl');
+
+    // No GDS session → nothing to attribute spend to; skip quietly.
+    const session = await loadSession();
+    if (!session || !session.token) process.exit(0);
+
+    const inter = priceTranscript(transcriptPath);
+
+    // #563: also capture this session's ad-hoc subagents (sibling subtree of the
+    // main transcript file), excluding grader-signature ones (already in #486).
+    const sessionDir = path.join(path.dirname(transcriptPath), sessionId);
+    const sub = priceSubagents(sessionDir);
+
+    const total = inter.total + sub.subagentTotal;
+    if (!(total > 0)) process.exit(0);
+
+    // task 1344: split into call-site-tagged, tier-carrying rows; cron sessions
+    // are tagged via OTB_COST_CRON_ROUTINE.
+    const cronRoutine = (process.env.OTB_COST_CRON_ROUTINE || '').trim();
+    const built = buildCostRows({ sessionId, inter, sub, cronRoutine });
+    const id8 = sessionId.slice(0, 8);
+
+    // --dry-run: price + print, never POST (for verification / inspection).
+    if (process.argv.includes('--dry-run')) {
+      console.log(`session-cost (dry-run): session ${id8} → $${built.rowsTotal.toFixed(4)} across ${built.rows.length} row(s) [base=${built.base}]`);
+      for (const r of built.rows) {
+        console.log(`  ${r.source} (${r.source_ref}) $${r.amount_usd.toFixed(4)}  tiers: fresh $${r.tiers.fresh_input_usd} / cache_read $${r.tiers.cache_read_usd} / cache_write $${r.tiers.cache_write_usd} / output $${r.tiers.output_usd}`);
+      }
+      console.log(`  reconcile: prior-single $${built.priorSingle.toFixed(4)} vs rows-sum $${built.rowsTotal.toFixed(4)} (Δ $${Math.abs(built.priorSingle - built.rowsTotal).toFixed(4)})`);
+      process.exit(0);
+    }
+
+    const api = await cliClient({ allowUnauthenticated: true });
+    for (const r of built.rows) {
+      const res = await api.cost.postCost({
+        body: {
+          amount_usd: r.amount_usd,
+          category: r.category,
+          source: r.source,
+          source_ref: r.source_ref,
+          description: r.description,
+          fresh_input_usd: r.tiers.fresh_input_usd,
+          cache_read_usd: r.tiers.cache_read_usd,
+          cache_write_usd: r.tiers.cache_write_usd,
+          output_usd: r.tiers.output_usd,
+        },
+      });
+
+      if (res.ok && res.data && res.data.skipped) {
+        console.error(`session-cost: already logged ${r.source} for session ${id8} (idempotent skip)`);
+      } else if (res.ok) {
+        console.error(`session-cost: logged $${r.amount_usd.toFixed(4)} for session ${id8} (source=${r.source})`);
+      } else {
+        console.error(`session-cost: skipped (non-fatal): HTTP ${res.status} for ${r.source}`);
+      }
+    }
+    process.exit(0);
+  } catch (err) {
+    // Best-effort: never break session exit.
+    console.error('session-cost: skipped (non-fatal):', err && err.message ? err.message : err);
+    process.exit(0);
+  }
+}
+
+// Run only when invoked directly (the SessionEnd hook / CLI). When required by a
+// test, expose the pure-ish helpers without firing the IIFE / network / exit.
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  priceTranscript,
+  priceSubagents,
+  listJsonlRecursive,
+  looksLikeGraderTranscript,
+  newestTranscriptFor,
+  // task 1344 — pure tier-split + row-building helpers (unit-tested)
+  buildCostRows,
+  emptyTiers,
+  addComponents,
+  addTiers,
+  roundTiers,
+};

package/scripts/gds/session-digest.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+// scripts/gds/session-digest.js — BFG 6D session capture on the SessionEnd seam
+// (ADR 0027; follow-up to #608/#617, idea #178).
+//
+// Uploads the FULL session digest to the BFG corpus (POST /api/gds/sessions)
+// when a Claude Code session ENDS. Wired as a SessionEnd hook in
+// .claude/settings.json (sibling to session-cost.js), which pipes
+// { session_id, transcript_path, cwd, reason } as JSON on stdin.
+//
+// WHY (not just /builder-ship): the on-ship upload (ship.js) fires MID-session,
+// so it misses everything after the last ship — merge-mode landings, cleanup,
+// late work. SessionEnd fires once at the very end with the complete transcript,
+// so the corpus row reflects the WHOLE session.
+//
+// ONE RECORD PER SESSION (the invariant Lars asked to preserve): the server
+// upserts on session_id (UNIQUE) — task_ids UNION, detail/metrics/tokens
+// OVERWRITTEN. So this end-of-session upload UPDATES the single existing session
+// row in place to the final state; it never creates a duplicate "5th log".
+//
+// The transcript_path comes straight from the hook, so there is no path-guessing
+// (sidesteps the worktree-path class of bug #551 entirely).
+//
+// CONTRACT (mirrors session-cost.js): best-effort, NON-FATAL, idempotent.
+//   - exits 0 on every path (a SessionEnd hook must never break session exit).
+//   - no GDS session / missing transcript / network error → quiet skip.
+//   - idempotent: the upsert refreshes the one session row; re-running is safe.
+//   - complements (does NOT replace) the on-ship upload — SessionEnd is
+//     best-effort and a hard crash/kill can skip it.
+//
+// Also runnable by hand:
+//   node scripts/gds/session-digest.js --transcript <path> [--session <id>]
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { cliClient, loadSession, arg } = require('./cli-lib');
+const { buildSessionDigest, collectEnvSecrets } = require('./ship');
+
+
+// Claude Code encodes a project transcript dir by replacing every non-alnum
+// char in the cwd with '-' (matches session-cost.js).
+function encodeCwd(cwd) {
+  return cwd.replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+// parseHookInput — PURE. Resolve { transcriptPath, sessionId, cwd } from the
+// SessionEnd stdin payload + explicit CLI args (args win over stdin). No I/O, so
+// it is unit-tested (tests/session_digest.mjs). A non-JSON / empty stdin falls
+// back to the provided args.
+function parseHookInput(stdinRaw, opts = {}) {
+  let transcriptPath = opts.transcriptArg || null;
+  let sessionId = opts.sessionArg || null;
+  let cwd = opts.cwd || null;
+  if (stdinRaw) {
+    try {
+      const hook = JSON.parse(stdinRaw);
+      transcriptPath = transcriptPath || hook.transcript_path || null;
+      sessionId = sessionId || hook.session_id || null;
+      if (hook.cwd) cwd = hook.cwd;
+    } catch (_) {
+      /* not JSON — ignore, keep the args */
+    }
+  }
+  return { transcriptPath, sessionId, cwd };
+}
+
+// Fallback ONLY — the SessionEnd hook always supplies transcript_path, so this
+// runs just for a manual/hand invocation with no --transcript. n is bounded (a
+// project's transcript count) and this is a one-shot hook process, never a
+// server loop, so the per-file statSync is fine here.
+function newestTranscriptFor(cwd) {
+  const dir = path.join(os.homedir(), '.claude', 'projects', encodeCwd(cwd));
+  let files;
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
+  } catch (_) {
+    return null;
+  }
+  if (!files.length) return null;
+  const withMtime = files.map((f) => {
+    const full = path.join(dir, f);
+    return { full, mtime: fs.statSync(full).mtimeMs };
+  });
+  withMtime.sort((a, b) => b.mtime - a.mtime);
+  return withMtime[0].full;
+}
+
+// Read piped stdin (the SessionEnd hook payload); null on a TTY / nothing piped.
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve(null);
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (c) => { data += c; });
+    process.stdin.on('end', () => resolve(data || null));
+    // guard: non-TTY but not actually piped — don't hang
+    setTimeout(() => resolve(data || null), 400);
+  });
+}
+
+function parseTranscript(transcriptPath) {
+  const raw = fs.readFileSync(transcriptPath, 'utf8');
+  const entries = [];
+  for (const line of raw.split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    try {
+      entries.push(JSON.parse(t));
+    } catch (_) {
+      /* skip a malformed line — best-effort */
+    }
+  }
+  return entries;
+}
+
+async function main() {
+  // Watchdog: a SessionEnd hook must never stall session exit. If the read or
+  // POST hangs (slow/offline network — fetch has no default timeout), bail.
+  const watchdog = setTimeout(() => process.exit(0), 6000);
+  watchdog.unref();
+  try {
+    const stdinRaw = await readStdin();
+    let { transcriptPath, sessionId, cwd } = parseHookInput(stdinRaw, {
+      transcriptArg: arg('--transcript'),
+      sessionArg: arg('--session'),
+      cwd: process.cwd(),
+    });
+
+    if (!transcriptPath) transcriptPath = newestTranscriptFor(cwd || process.cwd());
+    if (!transcriptPath || !fs.existsSync(transcriptPath)) process.exit(0); // nothing to capture
+    if (!sessionId) sessionId = path.basename(transcriptPath, '.jsonl');
+
+    // No GDS session → nothing to attribute the digest to; skip quietly.
+    const session = await loadSession();
+    if (!session || !session.token) process.exit(0);
+
+    // Secret hygiene: buildSessionDigest (ship.js) is the PRIMARY scrubber — it
+    // redacts known secret PATTERNS + a high-entropy catch-all (task 1003).
+    // extraSecrets is defense-in-depth: literal dynamic values that wouldn't
+    // match a static shape — every secret-shaped env VALUE (Apple/MAC_* CI creds,
+    // baked GDS/DO token, ANTHROPIC_API_KEY, …) + this run's GDS session token.
+    // Mirrors ship.js's uploadSessionOnShip exactly — the same proven path.
+    const extraSecrets = collectEnvSecrets();
+    if (session.token) extraSecrets.push(session.token);
+
+    const digest = buildSessionDigest(parseTranscript(transcriptPath), { extraSecrets });
+
+    // task_ids:[] — the server upsert UNIONs task_ids, so the on-ship task
+    // attribution is preserved; this end-of-session upload's job is to refresh
+    // the digest to the COMPLETE session, not to (re)assign tasks.
+    const payload = {
+      session_id: sessionId,
+      task_ids: [],
+      total_tokens: digest.totalTokens,
+      duration_seconds: digest.durationSeconds,
+      started_at: digest.startedAt,
+      ended_at: digest.endedAt,
+      detail: digest.detail,
+      metrics: digest.metrics,
+    };
+    const api = await cliClient({ allowUnauthenticated: true });
+    const r = await api.sessions.postSessions({ body: payload });
+    if (r && r.ok) {
+      console.error(
+        `session-digest: stored full session (${digest.metrics.assistant_turns} turns, ${digest.totalTokens} tokens, ${digest.metrics.tool_error_count} tool errors).`
+      );
+    } else {
+      console.error(`session-digest: skipped (POST ${r && r.status}${r && r.data && r.data.error ? ' ' + r.data.error : ''}).`);
+    }
+  } catch (e) {
+    console.error('session-digest: skipped —', e && e.message ? e.message : e);
+  } finally {
+    process.exit(0);
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = { parseHookInput };