@cspeach/cli 1.0.0 → 1.1.0

package/dist/session/audit-export.js

@@ -0,0 +1,459 @@
+// cspeach-cli/src/session/audit-export.ts
+//
+// UX Wave 3 / Task 4 — `/export audit`: the signable session record.
+//
+// buildAuditReport turns a SessionState + its cost log into ONE markdown
+// document an SAP team lead or auditor can read to know exactly who did what,
+// where, under which approval, and at what cost. It is a PURE builder:
+//   - no Date.now / no clock reads — every timestamp is derived from session
+//     data (toolCall completed_at / started_at, session.last_turn_at). Two
+//     calls on the same input are byte-identical.
+//   - no network, no fs. The `/export audit` command (commands/export-audit.ts)
+//     wraps this with the cost-log read and the file write.
+//
+// ── Approval → write pairing rule (load-bearing; see the auditor promise) ──
+// The `request_approval` tool mints one JWT per approved change and returns
+// them in its result as `approval_ids: string[]`. A write tool (sap_set_source,
+// sap_create_object, …) is called with `approval_id: <that exact JWT>`, and the
+// loop records the FULL tool input in `toolCalls[].args` (agent/loop.ts
+// recordCompletedToolCall — it upserts over the leaner WAL entry, so the final
+// persisted args carry approval_id). We therefore pair a write to its approval
+// by EXACT JWT STRING EQUALITY: the approval record whose `approval_ids`
+// contains the write's `args.approval_id`. This is a reliable 1:1 linkage — the
+// write literally echoes back the credential it was issued — so per-write
+// approval columns are honest, not a heuristic guess. (A declined change never
+// gets a JWT, so it can never appear in the Writes table; it surfaces only in
+// the Declined section.) Fallback for a truncated approval result (the loop
+// caps recorded result payloads at 4 kB, and many long JWTs could overflow):
+// if the result JSON won't parse, we substring-scan the raw text for the JWT
+// and regex out auto_approved / effective_risk. A write whose approval_id has
+// no match at all (e.g. minted in a prior session) renders '—' — an honest gap,
+// never an invented approval.
+import { summarise } from '../cost/cost-log.js';
+import { CLI_VERSION } from '../lib/version.js';
+/**
+ * Object-mutating tools — one row per completed call in the Writes table.
+ * Kept as a literal name set (not the tool registry) so this pure builder
+ * never triggers tool registration side-effects. sap_lock / sap_unlock are
+ * deliberately excluded: they are transient edit-lock primitives, not object
+ * change records. Mirrors the `isMutating: true` tools in tools/sap-write.ts.
+ */
+const WRITE_TOOLS = new Set([
+    'sap_set_source',
+    'sap_update_method',
+    'sap_delete_object',
+    'sap_create_object',
+    'sap_set_class_include',
+    'sap_create_domain',
+    'sap_create_data_element',
+    'sap_activate',
+    'sap_service_binding_publish',
+    'sap_service_binding_unpublish',
+    'sap_message_maintain',
+    'sap_number_range_intervals',
+    // CTS mutations (tools/transport.ts) — both isMutating + JWT-gated. A
+    // transport RELEASE never appearing in an audit document would be the
+    // wrong silence.
+    'sap_transport_create',
+    'sap_transport_release',
+]);
+/**
+ * Non-mutating tools that are interaction/plumbing, not object reads — excluded
+ * from the Reads counts so the summary reflects genuine system reads. Approvals
+ * have their own section; ask_question is a user prompt.
+ */
+const NON_READ_TOOLS = new Set(['request_approval', 'ask_question']);
+function asRecord(v) {
+    return v && typeof v === 'object' ? v : {};
+}
+function str(v) {
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+/** Timestamp of a tool call — completed_at when finished, else the pending start. */
+function tsOf(c) {
+    return c.completed ? c.completed_at : c.started_at;
+}
+/** "HH:MM:SS" slice of an ISO timestamp; '—' if unparseable. */
+function timeCell(iso) {
+    return iso.length >= 19 ? iso.slice(11, 19) : '—';
+}
+function parseApprovals(toolCalls) {
+    const recs = [];
+    for (const c of toolCalls) {
+        if (!c.completed || c.tool !== 'request_approval')
+            continue;
+        const raw = c.result ?? '';
+        const args = asRecord(c.args);
+        let rec;
+        try {
+            const r = asRecord(JSON.parse(raw));
+            const skipped = Array.isArray(r.skipped)
+                ? r.skipped.map((s) => {
+                    const so = asRecord(s);
+                    return {
+                        object: str(so.object) ?? '—',
+                        op: str(so.op) ?? '—',
+                        reason: str(so.reason) ?? 'skipped',
+                    };
+                })
+                : [];
+            rec = {
+                ids: Array.isArray(r.approval_ids) ? r.approval_ids.filter((x) => typeof x === 'string') : [],
+                approved: r.approved === true,
+                autoApproved: r.auto_approved === true,
+                risk: str(r.effective_risk),
+                skipped,
+                declineReason: r.approved === false ? str(r.reason) : undefined,
+                summary: str(args.summary),
+                raw,
+                parseFailed: false,
+            };
+        }
+        catch {
+            // Truncated / malformed result — keep raw for substring pairing.
+            rec = {
+                ids: [],
+                approved: /"approved":\s*true/.test(raw),
+                autoApproved: /"auto_approved":\s*true/.test(raw),
+                risk: /"effective_risk":\s*"(low|medium|high)"/.exec(raw)?.[1],
+                skipped: [],
+                summary: str(args.summary),
+                raw,
+                parseFailed: true,
+            };
+        }
+        recs.push(rec);
+    }
+    return recs;
+}
+/** Pair a write's approval_id (a minted JWT) to its approval record. */
+function findApproval(approvalId, recs) {
+    if (!approvalId)
+        return undefined;
+    for (const r of recs)
+        if (r.ids.includes(approvalId))
+            return r;
+    // Fallback: the approval result was truncated past its approval_ids array.
+    for (const r of recs)
+        if (r.parseFailed && r.raw.includes(approvalId))
+            return r;
+    return undefined;
+}
+function approvalCell(rec) {
+    if (!rec)
+        return '—';
+    const risk = rec.risk ? ` (${rec.risk})` : '';
+    if (rec.autoApproved)
+        return `auto ✓${risk}`;
+    if (rec.approved)
+        return `approved ✓${risk}`;
+    return `declined ✗${risk}`;
+}
+// ── Object / snapshot extraction ──────────────────────────────────────────
+function writeObject(tool, args, result) {
+    switch (tool) {
+        case 'sap_transport_create': {
+            // The created transport number lives in the RESULT (transport_number),
+            // not the args — args only carry the description.
+            let r = {};
+            try {
+                r = asRecord(JSON.parse(result ?? ''));
+            }
+            catch { /* r stays {} */ }
+            const tr = str(r.transport_number);
+            if (tr)
+                return tr;
+            // already_locked (#8): SAP made NO new transport — it returned an
+            // existing owning request. Name that request and annotate it as a
+            // transport op; never the create description, which is not an object
+            // and misreads in the Object cell.
+            if (r.already_locked === true) {
+                const locked = str(r.transport);
+                return locked ? `${locked} (already locked)` : 'transport (already locked)';
+            }
+            // Last resort: name the operation, not the raw description.
+            return 'transport';
+        }
+        case 'sap_transport_release':
+            return str(args.transport) ?? '—';
+        case 'sap_update_method': {
+            const cls = str(args.class_name) ?? '—';
+            const m = str(args.method_name);
+            return m ? `${cls}~${m}` : cls;
+        }
+        case 'sap_set_class_include': {
+            const cls = str(args.className) ?? '—';
+            const inc = str(args.includeType);
+            return inc ? `${cls} (${inc})` : cls;
+        }
+        case 'sap_activate': {
+            if (Array.isArray(args.objects)) {
+                const names = args.objects.map((o) => str(asRecord(o).name) ?? '?');
+                return names.length ? names.join(', ') : '—';
+            }
+            return '—';
+        }
+        default:
+            return str(args.name) ?? '—';
+    }
+}
+/**
+ * The type/name key a write's snapshot would be filed under. UPPERCASED on
+ * both sides (M1): a write may echo its object in lowercase while the snapshot
+ * recorded it uppercase (or vice versa); a case-sensitive key would drop
+ * legitimate restore-point evidence to an '—'. Mirrors candidates.ts, which
+ * compares `s.type.toUpperCase()` / `s.name.toUpperCase()`.
+ */
+function snapshotKey(tool, args) {
+    if (tool === 'sap_update_method' || tool === 'sap_set_class_include') {
+        const cls = str(args.class_name) ?? str(args.className);
+        return cls ? `CLAS:${cls.toUpperCase()}` : undefined;
+    }
+    const name = str(args.name);
+    const type = str(args.type);
+    return name && type ? `${type.toUpperCase()}:${name.toUpperCase()}` : undefined;
+}
+/**
+ * Index explicit sap_snapshot_take results by uppercased `TYPE:NAME` → the
+ * list of takes (id + completion epoch). Auto-snapshots fired by the write
+ * tools are NOT itemized in toolCalls (they run inside the handler and their
+ * id is never surfaced in the write result), so only on-demand
+ * sap_snapshot_take calls yield an id here — otherwise the column is an
+ * honest '—'.
+ *
+ * We keep every take (not just the newest) so a write can be paired with the
+ * newest take that completed strictly BEFORE it — see newestSnapshotBefore.
+ */
+function indexSnapshots(toolCalls) {
+    const map = new Map();
+    for (const c of toolCalls) {
+        if (!c.completed || c.tool !== 'sap_snapshot_take' || c.is_error)
+            continue;
+        try {
+            const snap = asRecord(asRecord(JSON.parse(c.result)).snapshot);
+            const id = str(snap.id);
+            const type = str(snap.type);
+            const name = str(snap.name);
+            if (!id || !type || !name)
+                continue;
+            const epoch = Date.parse(tsOf(c));
+            if (!Number.isFinite(epoch))
+                continue;
+            const key = `${type.toUpperCase()}:${name.toUpperCase()}`;
+            const list = map.get(key) ?? [];
+            list.push({ id, epoch });
+            map.set(key, list);
+        }
+        catch {
+            /* ignore malformed snapshot result */
+        }
+    }
+    return map;
+}
+/**
+ * The id of the newest snapshot take that completed STRICTLY BEFORE
+ * `beforeEpoch` — the write's own completion time. A take made after a write
+ * is not a pre-write restore point for it, so pairing it onto that write's row
+ * would make the signable record assert a restore point that never existed
+ * (I1). Newest-before wins, mirroring newestSnapshotBefore in
+ * rewind/candidates.ts.
+ */
+function newestSnapshotBefore(takes, beforeEpoch) {
+    if (!takes || !Number.isFinite(beforeEpoch))
+        return undefined;
+    let best;
+    for (const t of takes) {
+        if (t.epoch >= beforeEpoch)
+            continue; // must be strictly before the write
+        if (!best || t.epoch > best.epoch)
+            best = t;
+    }
+    return best?.id;
+}
+/** Success (✓) unless the loop marked the call is_error. */
+function outcomeCell(c) {
+    return c.is_error ? '✗' : '✓';
+}
+// ── Operator identity ─────────────────────────────────────────────────────
+//
+// SessionState carries NO SAP logon user (only the sap_system alias). The one
+// identity available is the local CSPeach operator, resolved the same way as
+// agent/loop.ts getAuthorIdentity (CSPEACH_AUTHOR_NAME → USER → USERNAME). It
+// is the person who RAN CSPeach, not the SAP account writes landed under — the
+// header labels it "Operator" and shows the SAP system separately so the two
+// are never conflated. (Inlined rather than importing agent/loop.js to keep
+// this a dependency-light pure builder.)
+function resolveOperator() {
+    return (process.env.CSPEACH_AUTHOR_NAME ||
+        process.env.USER ||
+        process.env.USERNAME ||
+        'unknown');
+}
+// ── Transports seen ───────────────────────────────────────────────────────
+function transportsSeen(toolCalls, sessionTransport) {
+    const set = new Set();
+    if (sessionTransport)
+        set.add(sessionTransport);
+    for (const c of toolCalls) {
+        if (!c.completed)
+            continue;
+        const args = asRecord(c.args);
+        const t = str(args.transport);
+        if (t && WRITE_TOOLS.has(c.tool))
+            set.add(t);
+        // Owning-transport override / created transport surfaced in the result.
+        try {
+            const r = asRecord(JSON.parse(c.result));
+            const used = str(r.transport_used);
+            if (used)
+                set.add(used);
+            const created = str(r.transport_number);
+            if (created && (c.tool === 'sap_transport_create' || c.tool === 'sap_transport_release'))
+                set.add(created);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return [...set].sort();
+}
+// ── Main builder ──────────────────────────────────────────────────────────
+export function buildAuditReport(input) {
+    const { session, costEntries, transport } = input;
+    const calls = session.toolCalls;
+    const completed = calls.filter((c) => c.completed === true);
+    const approvals = parseApprovals(calls);
+    const snapIndex = indexSnapshots(calls);
+    // ── Date range: first → last tool call (fallback to session turn stamps) ──
+    let firstTs;
+    let lastTs;
+    for (const c of calls) {
+        const t = tsOf(c);
+        if (!firstTs || t < firstTs)
+            firstTs = t;
+        if (!lastTs || t > lastTs)
+            lastTs = t;
+    }
+    const dateFrom = firstTs ?? session.started_at;
+    const dateTo = lastTs ?? session.last_turn_at;
+    const lines = [];
+    const L = (s = '') => void lines.push(s);
+    // ── Header ────────────────────────────────────────────────────────────────
+    L('# CSPeach Session Audit');
+    L();
+    L(`- **Session:** \`${session.id}\``);
+    L(`- **SAP system:** ${session.sap_system ?? '—'}`);
+    L(`- **Operator (local):** ${resolveOperator()}`);
+    L(`- **Period:** ${dateFrom} → ${dateTo}`);
+    const trs = transportsSeen(calls, transport);
+    L(`- **Transport(s):** ${trs.length ? trs.map((t) => `\`${t}\``).join(', ') : '—'}`);
+    L();
+    L('> Scope: this record covers SAP-system mutations only — local file and');
+    L('> shell operations are excluded by design. Operator is the local CSPeach');
+    L('> user (who ran the session); the SAP logon user is not recorded in');
+    L('> session state. Plan audit states, if any, live in the plan handover,');
+    L('> not this report.');
+    L();
+    // ── Writes table ────────────────────────────────────────────────────────────
+    L('## Writes');
+    L();
+    const writes = completed.filter((c) => WRITE_TOOLS.has(c.tool));
+    if (writes.length === 0) {
+        L('_No mutating operations in this session._');
+    }
+    else {
+        L('| Time (UTC) | Tool | Object | Outcome | Approval | Snapshot |');
+        L('| --- | --- | --- | :---: | --- | --- |');
+        for (const c of writes) {
+            const args = asRecord(c.args);
+            const approvalId = str(args.approval_id);
+            const rec = findApproval(approvalId, approvals);
+            const key = snapshotKey(c.tool, args);
+            const snap = key ? newestSnapshotBefore(snapIndex.get(key), Date.parse(tsOf(c))) : undefined;
+            L(`| ${timeCell(tsOf(c))} | ${c.tool} | ${writeObject(c.tool, args, c.result)} | ${outcomeCell(c)} | ${approvalCell(rec)} | ${snap ? `\`${snap}\`` : '—'} |`);
+        }
+    }
+    L();
+    // ── Declined approvals ──────────────────────────────────────────────────────
+    L('## Declined approvals');
+    L();
+    // Whole-batch decline reasons (tools/approval.ts result `reason` values)
+    // mapped to auditor-readable labels; unknown reasons pass through verbatim.
+    const DECLINE_LABELS = {
+        plan_rejected: 'plan rejected',
+        user_cancelled_turn: 'turn cancelled',
+        headless_no_approval: 'headless — no approval possible',
+    };
+    const declines = [];
+    let anyTruncated = false;
+    for (const r of approvals) {
+        if (r.parseFailed)
+            anyTruncated = true;
+        for (const s of r.skipped) {
+            declines.push(`- ✗ ${s.op} \`${s.object}\` — ${s.reason}`);
+        }
+        if (r.skipped.length === 0 && !r.approved && r.declineReason) {
+            const what = r.summary ? ` (${r.summary})` : '';
+            declines.push(`- ✗ ${DECLINE_LABELS[r.declineReason] ?? r.declineReason}${what}`);
+        }
+    }
+    if (declines.length === 0) {
+        L('_None._');
+    }
+    else {
+        for (const d of declines)
+            L(d);
+    }
+    if (anyTruncated) {
+        // The loop caps recorded results at 4 kB — a truncated approval record may
+        // have lost its skipped[] entries. Say so rather than staying silent.
+        L();
+        L('_(approval record truncated — declined entries may be incomplete)_');
+    }
+    L();
+    // ── Reads summary ───────────────────────────────────────────────────────────
+    L('## Reads');
+    L();
+    const readCounts = new Map();
+    for (const c of completed) {
+        if (WRITE_TOOLS.has(c.tool) || NON_READ_TOOLS.has(c.tool))
+            continue;
+        readCounts.set(c.tool, (readCounts.get(c.tool) ?? 0) + 1);
+    }
+    if (readCounts.size === 0) {
+        L('_No read operations._');
+    }
+    else {
+        L('| Tool | Count |');
+        L('| --- | ---: |');
+        for (const [tool, n] of [...readCounts.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+            L(`| ${tool} | ${n} |`);
+        }
+    }
+    L();
+    // ── Cost ────────────────────────────────────────────────────────────────────
+    L('## Cost');
+    L();
+    const cost = summarise(costEntries);
+    const auditEntries = costEntries.filter((e) => e.label);
+    const auditCost = Math.round(auditEntries.reduce((s, e) => s + e.cost, 0) * 10000) / 10000;
+    L(`- **Total:** $${cost.totalCost.toFixed(4)} over ${cost.turns} turn${cost.turns === 1 ? '' : 's'}`);
+    L(`- **Tokens:** ${cost.totalTokens.input.toLocaleString('en-US')} in · ${cost.totalTokens.output.toLocaleString('en-US')} out · ${cost.totalTokens.cacheRead.toLocaleString('en-US')} cache-read · ${cost.totalTokens.cacheCreate.toLocaleString('en-US')} cache-write`);
+    if (auditEntries.length > 0) {
+        L(`- **Includes** ${auditEntries.length} labelled audit turn${auditEntries.length === 1 ? '' : 's'}: $${auditCost.toFixed(4)}`);
+    }
+    if (cost.byModel.length > 1) {
+        L('- **By model:**');
+        for (const m of cost.byModel) {
+            L(`  - ${m.model}: ${m.turns} turn${m.turns === 1 ? '' : 's'} · $${m.cost.toFixed(4)}`);
+        }
+    }
+    else if (cost.byModel[0]) {
+        L(`- **Model:** ${cost.byModel[0].model}`);
+    }
+    L();
+    // ── Footer ──────────────────────────────────────────────────────────────────
+    L('---');
+    L(`generated by CSPeach ${CLI_VERSION} — session ${session.id}`);
+    return lines.join('\n') + '\n';
+}

package/dist/session/context-report.js

@@ -0,0 +1,163 @@
+// cspeach-cli/src/session/context-report.ts
+//
+// UX Wave 3 / Task 5 — `/context`: the composition grid.
+//
+// buildContextReport turns a SessionState + its cost log into a breakdown of
+// WHAT fills the model's context window right now — a summary block (if the
+// history was compacted), the recent verbatim turns, tool-result payloads,
+// the task list, and everything system-side (system prompt + skill + tool
+// definitions). It is a PURE builder: no clock, no fs, no network.
+//
+// ── Honesty contract (load-bearing) ──────────────────────────────────────
+// The ONLY exact token number available to the CLI is `lastTurnInput`: the
+// prompt-token count the provider actually billed on the newest turn
+// (input + cache_read + cache_creation, all three because a cached prompt is
+// still prompt content occupying the window). EVERYTHING ELSE is a chars/4
+// heuristic derived from the persisted message content — it can be wrong by a
+// wide margin (tokenisation is not chars/4, and system/skill/tool text isn't
+// even in `session.messages`). So every per-segment number is flagged `~`
+// (approx) by the renderer, and the system-side segment is *derived* as
+// `lastTurnInput − (heuristic message estimate)` — the residual that the
+// message heuristic can't see. That residual is clamped to ≥ 0: a heuristic
+// that over-counts the message side must never manufacture a negative
+// system-side. The clamp is pinned by a test.
+//
+// Cost entries are appended in turn order by appendCostLine, but the raw tail
+// is NOT always a real turn: `label` tags non-user-turn spend (cost-log.ts —
+// currently only 'audit', the plan-phase auditor sub-call, which plan-chain.ts
+// appends AFTER the phase turn's own line with turn: 0). So the "one exact
+// number" is read from the newest UNLABELLED entry — the newest line that
+// represents a real session turn — never an auditor sub-call's prompt.
+import { planCompaction } from '../commands/compact.js';
+/**
+ * The model context window, in tokens. SINGLE definition — nothing else in the
+ * codebase may hard-code 200_000. 200k is the standard Claude context window;
+ * this is the denominator for the fill percentage and the bar scale.
+ */
+export const CONTEXT_WINDOW_TOKENS = 200_000;
+/** Above this fraction of the window, offer /compact. */
+const COMPACT_HINT_PCT = 0.6;
+/** Tool results larger than this fraction of the window earn a "big reads" note. */
+const HUGE_TOOL_RESULT_PCT = 0.3;
+/** chars → tokens heuristic. Deliberately crude; every result of it is flagged ~. */
+const CHARS_PER_TOKEN = 4;
+/**
+ * Prefix stamped on the compact summary message (see compact.ts
+ * buildSummaryMessage). A user message whose string content starts with this
+ * IS the compacted-history block — not a real user prompt.
+ */
+const SUMMARY_PREFIX = '[Context summary auto-generated by /compact';
+function estTokens(chars) {
+    return Math.ceil(chars / CHARS_PER_TOKEN);
+}
+/** True when a message is the compact summary block, not a real user prompt. */
+function isSummaryBlock(content) {
+    return content.startsWith(SUMMARY_PREFIX);
+}
+function tallyMessage(content, out) {
+    if (typeof content === 'string') {
+        if (isSummaryBlock(content))
+            out.summaryChars += content.length;
+        else
+            out.recentChars += content.length; // a verbatim user prompt
+        return;
+    }
+    if (!Array.isArray(content))
+        return;
+    for (const b of content) {
+        if (b == null || typeof b !== 'object')
+            continue;
+        const block = b;
+        switch (block.type) {
+            case 'text':
+                out.recentChars += String(block.text ?? '').length;
+                break;
+            case 'thinking':
+                out.recentChars += String(block.thinking ?? '').length;
+                break;
+            case 'tool_use':
+                out.toolChars += JSON.stringify(block.input ?? {}).length + String(block.name ?? '').length;
+                break;
+            case 'tool_result': {
+                const c = block.content;
+                out.toolChars += (typeof c === 'string' ? c : JSON.stringify(c ?? '')).length;
+                break;
+            }
+            default:
+                break;
+        }
+    }
+}
+/** Approx tokens a todo list occupies (text + a little per-item structure). */
+function todoTokens(todos) {
+    if (!todos || todos.length === 0)
+        return 0;
+    const chars = todos.reduce((acc, t) => acc + t.text.length + 4, 0);
+    return estTokens(chars);
+}
+/**
+ * Estimate the tokens that /compact would reclaim: the chars/4 size of the
+ * exact message slice planCompaction would summarise away. Reusing the real
+ * planner means the "reclaim" number is genuinely the summary-eligible-turns
+ * estimate, not a made-up figure.
+ */
+function reclaimableTokens(session) {
+    const plan = planCompaction(session.messages);
+    if (plan.toSummarise.length === 0)
+        return 0;
+    const tally = { summaryChars: 0, recentChars: 0, toolChars: 0 };
+    for (const m of plan.toSummarise)
+        tallyMessage(m.content, tally);
+    return estTokens(tally.summaryChars + tally.recentChars + tally.toolChars);
+}
+export function buildContextReport(session, costEntries) {
+    const windowTokens = CONTEXT_WINDOW_TOKENS;
+    // ── the one exact number: newest REAL turn's prompt tokens ──
+    // Skip labelled entries (non-user-turn spend, e.g. the plan auditor's
+    // turn-0 'audit' line appended after the phase turn) — presenting an audit
+    // sub-call's prompt as the session figure would break the honesty contract.
+    let newest;
+    for (let i = costEntries.length - 1; i >= 0; i--) {
+        if (!costEntries[i].label) {
+            newest = costEntries[i];
+            break;
+        }
+    }
+    const lastTurnInput = newest
+        ? newest.tokens.input + newest.tokens.cacheRead + newest.tokens.cacheCreate
+        : 0;
+    // ── heuristic message-side breakdown ──
+    const tally = { summaryChars: 0, recentChars: 0, toolChars: 0 };
+    for (const m of session.messages ?? [])
+        tallyMessage(m.content, tally);
+    const summaryTokens = estTokens(tally.summaryChars);
+    const recentTokens = estTokens(tally.recentChars);
+    const toolTokens = estTokens(tally.toolChars);
+    const todos = todoTokens(session.todos);
+    const messageEstimate = summaryTokens + recentTokens + toolTokens + todos;
+    // System side is the residual the message heuristic can't see (system
+    // prompt + active skill + tool schemas). Clamp to ≥ 0 — an over-counting
+    // heuristic must never produce a negative segment.
+    const systemSide = Math.max(0, lastTurnInput - messageEstimate);
+    const segments = [];
+    if (summaryTokens > 0)
+        segments.push({ label: 'summary block', approxTokens: summaryTokens });
+    segments.push({ label: 'recent turns', approxTokens: recentTokens });
+    segments.push({ label: 'tool results', approxTokens: toolTokens });
+    if (todos > 0)
+        segments.push({ label: 'todos', approxTokens: todos });
+    segments.push({ label: 'system + skill + tools', approxTokens: systemSide });
+    const pct = windowTokens > 0 ? lastTurnInput / windowTokens : 0;
+    // ── hints ──
+    const hints = [];
+    if (pct > COMPACT_HINT_PCT) {
+        const reclaim = reclaimableTokens(session);
+        if (reclaim > 0) {
+            hints.push(`context is ${Math.round(pct * 100)}% full — /compact reclaims ~${Math.round(reclaim / 1000)}k from older turns`);
+        }
+    }
+    if (toolTokens > windowTokens * HUGE_TOOL_RESULT_PCT) {
+        hints.push(`tool results fill ~${Math.round(toolTokens / 1000)}k — large reads dominate context; narrower reads keep it small`);
+    }
+    return { windowTokens, lastTurnInput, pct, segments, hints };
+}