@volter/supercode-interchange 0.1.7 → 0.1.9

package/README.md

@@ -123,6 +123,19 @@ record selected-home answers and null malformed metadata through npm and
 operator streams; concurrent path/record replacement and runtime writing remain
 unqualified.
 
+`sessions.resume_instructions` reads the complete selected transcript before
+returning a structured launch. An explicit cwd wins over the transcript's
+recorded cwd, then `.`; the locator supplies the harness and session id.
+Default and explicit `yolo` policy use the shared generated startup table.
+Grok receives its resolved default home only when that home is a symlink and
+no explicit `GROK_HOME` was supplied. This returns arguments and environment;
+it neither starts a harness nor writes a session or permission configuration.
+The separate `resume_instructions` capability marker refuses older services.
+The [private Mac/Windows record](../../docs/evidence/session-resume-instructions-2026-10-08.md)
+retains eight harnesses' specifications, cwd/environment cases and older-service
+refusal through npm and loopback operator streams. Installed sets, actual live
+resume and full-corpus qualification remain open.
+
 `sessions.usage` reads a complete lossless session in the load worker and groups
 recorded tokens by the native day prefix and model. Claude keeps the last usage
 record for each response id; Codex separates successive cumulative totals and
@@ -131,13 +144,31 @@ price. Costs use the pinned 2026-10-03 native rate snapshot, including cache TTL
 fast-mode and inference-geo factors; this is not a live pricing feed. Exact u64
 wire counts are retained independently of JavaScript number rounding. A separate
 `usage` marker refuses older read services without closing their catalog lane.
-Machine-wide spend and runtime budgets retain their separate native consumers.
+Runtime budgets retain their separate native consumers.
 [Private Mac/Windows conversations](../../docs/evidence/session-usage-port-2026-10-08.md)
 record small Claude/Codex usage and refusal examples through npm stdio and
 loopback operator streams. Other-format/runtime corpus, concurrent replacement,
 scale, remote revocation, all pricing/time branches and a new Windows native
 artifact remain unqualified; these records do not establish an installed set.
 
+`sessions.spend` reads recently modified Claude/Codex transcript tails in the
+caller-owned load worker and counts child use on each parent. Its tail stop is
+ten minutes before the requested window; Codex additionally keeps a preceding
+total and model. Machine spend filters Claude usage before the last-response-id
+fold, while per-session usage filters afterward, preserving their distinct
+contracts. Costs use the same pinned rate snapshot. Counts stay exact on raw
+wire frames; SDK JavaScript numbers can round. Totals count all sessions before
+the requested row limit. Live registry names and enrolled-machine addresses are
+display metadata, never proof of caller authority. A separate `spend` marker
+refuses an older service. The npm `sessions usage` command uses this reader
+without requiring a native accounting handler. Runtime budgets, shared native
+record readers and pricing retain their own consumers.
+[Private Mac/Windows spend records](../../docs/evidence/session-machine-spend-2026-10-08.md)
+cover small parent/child, tail-boundary, sort/limit and refusal cases through
+npm and loopback operator streams, plus the new Mac native CLI handoff.
+Large corpus, concurrent changes, every live-name/address branch, installed
+sets and new Windows native forwarding remain unqualified.
+
 `resolveHarnessHomes` follows native HOME-first defaults and preserves explicitly empty harness-specific
 home values. `projectMetadata` applies workspace scope, native lineage, repository-family, profile, time and
 metadata-search filters with stable newest-first ordering. It clones raw rows before descendant roll-up.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-interchange",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "type": "module",
   "description": "Read-only harness metadata, transcript codecs and session projections for Supercode",
   "license": "MIT OR Apache-2.0",

package/session-read.d.ts

@@ -3,10 +3,11 @@ import { SessionFollower } from './session-codecs.js';
 import type { ProjectedSessionResult, NormalizedSession, RecordedSessionProfile, RecordedSessionProfileChange } from './session-model.js';
 export const SESSION_READ_METHODS: readonly string[];
 export const SESSION_READ_EVENT: 'harness.v1.sessions.event';
-export const SESSION_READ_CAPABILITY: Readonly<{ version: 1; owner: 'caller'; language: 'typescript'; native_parser: false; recorded_config: true; launch_agent: true; usage: true }>;
+export const SESSION_READ_CAPABILITY: Readonly<{ version: 1; owner: 'caller'; language: 'typescript'; native_parser: false; recorded_config: true; launch_agent: true; usage: true; spend: true; resume_instructions: true }>;
 export interface SessionReadContext { cwd?: string; env?: Record<string, string | undefined> }
 export function parseSessionWire(text: string): unknown;
 export function stringifySessionWire(value: unknown): string;
+export function prettySessionWire(value: unknown): string;
 export function parseSessionReadParams(params: unknown, context?: SessionReadContext): { locator: ReadLocator; fidelity: string; view: (SessionFollowOptions & { fromByte: number | null }) | null; options: import('./session-model.js').SessionLoadOptions | null };
 export function loadSessionRead(params: unknown, context?: SessionReadContext): Promise<ProjectedSessionResult | { session: NormalizedSession & { resolved_profile: RecordedSessionProfile; resolved_profile_history: RecordedSessionProfileChange[] } }>;
 export function openSessionReadFollower(params: unknown, context?: SessionReadContext): Promise<SessionFollower>;
@@ -23,3 +24,13 @@ export interface SessionTokenUsage {
 }
 /** Recorded tokens and the pinned rate snapshot; exact native integers survive wire serialization. */
 export function loadSessionUsage(params: unknown, context?: SessionReadContext): Promise<{ harness: string; session_id: string | null; since?: string; usage: SessionTokenUsage[] }>;
+export type RecordedTokenSpend = Omit<SessionTokenUsage, 'at' | 'model'>;
+export interface MachineTokenSpend extends RecordedTokenSpend {
+  harness: string; session_id: string; address: string | null; name: string | null;
+  cwd: string | null; subagents: number; last_at: string | null;
+  models: Array<RecordedTokenSpend & { model: string }>;
+}
+/** Recently modified Claude/Codex tails, including child use on the parent. */
+export function loadSessionSpend(params: unknown, context?: SessionReadContext): Promise<{ since: string; until: string; session_count: number; sessions: MachineTokenSpend[]; total: RecordedTokenSpend }>;
+/** Reads the complete source and returns a specification; starts no process. */
+export function loadSessionResumeInstructions(params: unknown, context?: SessionReadContext): Promise<{ launch: { cwd: string; program: string; arguments: string[]; env: Record<string, string> } }>;

package/session-read.mjs

@@ -1,7 +1,7 @@
 // Caller-owned public read operations. Parsing never goes to a native service
 // or to a machine daemon carrying another caller's home/environment.
 import { resolve } from 'node:path';
-import { nativeInteger, nativeNumberKind, parseNativeJson, stringifyNativeJson } from './native-json.mjs';
+import { nativeInteger, nativeNumberKind, parseNativeJson, stringifyNativeJson, stringifyNativeJsonPretty } from './native-json.mjs';
 import { loadSessionLocator } from './session-path.mjs';
 import { loadSessionDisplayLocator, loadSessionDisplayFrom } from './session-display.mjs';
 import { withClaudeReadIndex, supportsClaudeReadIndex } from './session-claude-index.mjs';
@@ -11,12 +11,16 @@ import { boundSessionView, projectedMessageWindow, projectedSessionJson, project
 import { recordedSessionConfiguration } from './session-recorded-config.mjs';
 import { recordedLaunchAgent } from './session-launch-agent.mjs';
 import { recordedSessionUsage } from './session-usage.mjs';
+import { loadMachineSpend } from './session-spend.mjs';
+import { sessionResumeLaunch } from './session-resume-instructions.mjs';
 import { parseUsageSince, usageMoment } from './session-usage-time.mjs';
 
-export const SESSION_READ_METHODS = Object.freeze(['harness.v1.sessions.load', 'harness.v1.sessions.follow', 'harness.v1.sessions.unfollow', 'harness.v1.sessions.recorded_config', 'harness.v1.sessions.launch_agent', 'harness.v1.sessions.usage']);
+export const SESSION_READ_METHODS = Object.freeze(['harness.v1.sessions.load', 'harness.v1.sessions.follow', 'harness.v1.sessions.unfollow', 'harness.v1.sessions.recorded_config', 'harness.v1.sessions.launch_agent', 'harness.v1.sessions.usage', 'harness.v1.sessions.spend', 'harness.v1.sessions.resume_instructions']);
 export const SESSION_READ_EVENT = 'harness.v1.sessions.event';
-export const SESSION_READ_CAPABILITY = Object.freeze({ version: 1, owner: 'caller', language: 'typescript', native_parser: false, recorded_config: true, launch_agent: true, usage: true });
+export const SESSION_READ_CAPABILITY = Object.freeze({ version: 1, owner: 'caller', language: 'typescript', native_parser: false, recorded_config: true, launch_agent: true, usage: true, spend: true, resume_instructions: true });
+export { loadMachineSpend as loadSessionSpend };
 export { parseNativeJson as parseSessionWire, stringifyNativeJson as stringifySessionWire };
+export { stringifyNativeJsonPretty as prettySessionWire };
 const invalid = (message) => { throw Object.assign(new Error(message), { rpcCode: -32602 }); };
 const object = (value, name) => {
   if (value == null || typeof value !== 'object' || Array.isArray(value)) invalid(`${name} must be an object`);
@@ -135,3 +139,15 @@ export async function loadSessionUsage(params, context = {}) {
   if (since != null) answer.since = usageMoment(since);
   return answer;
 }
+
+export async function loadSessionResumeInstructions(params, context = {}) {
+  object(params, 'resume instructions params');
+  const { locator } = parseSessionReadParams({ locator: params.locator }, context);
+  const cwd = params.cwd == null ? null : string(params.cwd, 'cwd');
+  const policy = Object.hasOwn(params, 'policy') ? params.policy : 'default';
+  if (!['default', 'yolo'].includes(policy)) invalid(`unknown resume policy: ${String(policy)}`);
+  // Native admission loads the source even when cwd is explicit, and its
+  // launch identity comes from the locator rather than a transcript header.
+  const session = await loadSessionLocator(locator, { ...context, fidelity: 'byte_lossless', includeSubagents: true });
+  return { launch: sessionResumeLaunch(locator.harness, locator.session_id, cwd ?? session.meta.cwd ?? '.', policy, context) };
+}

package/session-resume-instructions.mjs

@@ -0,0 +1,54 @@
+// A launch specification only. The caller decides whether to run the harness.
+import { lstatSync, realpathSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { isAbsolute } from 'node:path';
+import { STARTUP_PROMPTS } from './startup-prompts.mjs';
+import { childPath } from './session-spend-files.mjs';
+
+function startupArguments(harness, cwd, unattended) {
+  const prompts = STARTUP_PROMPTS[harness];
+  if (!prompts) return [];
+  const where = JSON.stringify(cwd);
+  const arguments_ = prompts.startup.flatMap(pair => pair.map(flag => flag.replaceAll('{cwd}', where)));
+  if (unattended) arguments_.push(...prompts.unattended);
+  return arguments_;
+}
+
+function grokHomeEnvironment(env, cwd) {
+  if (env.GROK_HOME !== undefined) return {};
+  let home = env.HOME || (process.platform === 'win32' ? env.USERPROFILE : null);
+  if (!home) { try { home = userInfo().homedir; } catch { return {}; } }
+  if (!isAbsolute(home) && !(process.platform === 'win32' && /^[A-Za-z]:/.test(home))) home = childPath(cwd, home);
+  const path = childPath(home, '.grok');
+  try { if (lstatSync(path).isSymbolicLink()) return { GROK_HOME: realpathSync(path) }; }
+  catch { /* no recorded filesystem resolution to supply */ }
+  return {};
+}
+
+export function sessionResumeLaunch(harness, sessionId, cwd, policy, { env = process.env, cwd: readCwd = process.cwd() } = {}) {
+  const unattended = policy === 'yolo';
+  let program, arguments_;
+  switch (harness) {
+    case 'grok':
+      program = 'grok';
+      arguments_ = [...(unattended ? ['--sandbox', 'workspace', '--always-approve'] : []), '--resume', sessionId];
+      break;
+    case 'codex':
+      program = 'codex'; arguments_ = [...startupArguments(harness, cwd, unattended), 'resume', sessionId]; break;
+    case 'claude-code':
+      program = 'claude'; arguments_ = [...startupArguments(harness, cwd, unattended), '--resume', sessionId]; break;
+    case 'gemini':
+      program = 'gemini'; arguments_ = [...startupArguments(harness, cwd, unattended), '--resume', sessionId]; break;
+    case 'goose':
+      program = 'goose'; arguments_ = ['session', '--resume', '--session-id', sessionId]; break;
+    case 'pi':
+      program = 'pi'; arguments_ = [...startupArguments(harness, cwd, unattended), '--session', sessionId]; break;
+    case 'opencode':
+      program = 'opencode'; arguments_ = ['--session', sessionId]; break;
+    case 'supercode':
+      program = 'supercode'; arguments_ = [...(unattended ? ['--dangerous'] : []), 'resume', sessionId]; break;
+    default:
+      throw Object.assign(new Error(`no structured resume launch is registered for harness \`${harness}\``), { rpcCode: -32602 });
+  }
+  return { cwd, program, arguments: arguments_, env: program === 'grok' ? grokHomeEnvironment(env, readCwd) : {} };
+}

package/session-spend-files.mjs

@@ -0,0 +1,97 @@
+// The machine reading uses the retained native tail boundary, independently
+// of the complete-session loader. Unread/malformed records contribute no use.
+import { openSync, closeSync, fstatSync, readSync, opendirSync, statSync } from 'node:fs';
+import { sep } from 'node:path';
+import { parseNativeJson } from './native-json.mjs';
+import { field, stringField } from './session-codec-utils.mjs';
+
+const blockSize = 256 * 1024;
+const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+export function textName(bytes) { try { return utf8.decode(bytes); } catch { return null; } }
+export function childPath(directory, name) {
+  const root = Buffer.isBuffer(directory) ? directory : Buffer.from(directory);
+  const driveOnly = process.platform === 'win32' && root.length === 2 && /^[A-Za-z]:$/.test(root.toString('utf8'));
+  return Buffer.concat([root, root.length && !driveOnly && root.at(-1) !== 47 && (process.platform !== 'win32' || root.at(-1) !== 92) ? Buffer.from(sep) : Buffer.alloc(0), Buffer.isBuffer(name) ? name : Buffer.from(name)]);
+}
+export function* directoryEntries(path) {
+  let directory;
+  try { directory = opendirSync(path, { encoding: 'buffer' }); } catch { return; }
+  try {
+    for (;;) {
+      let entry; try { entry = directory.readSync(); } catch { return; }
+      if (entry == null) return;
+      yield { name: entry.name, path: childPath(path, entry.name) };
+    }
+  } finally { try { directory.closeSync(); } catch { /* already closed */ } }
+}
+export function isDirectory(path) { try { return statSync(path).isDirectory(); } catch { return false; } }
+export function modifiedSince(path, since) {
+  try { const at = statSync(path, { bigint: true }).mtimeNs; return at >= 0n && BigInt.asIntN(64, at / 1000000n) >= since; }
+  catch { return false; }
+}
+export const jsonl = (name) => name.lastIndexOf(46) > 0 && name.subarray(name.lastIndexOf(46)).equals(Buffer.from('.jsonl'));
+export const stem = (name) => name.subarray(0, name.lastIndexOf(46));
+
+function readExact(fd, bytes, position) {
+  let done = 0;
+  while (done < bytes.length) {
+    const read = readSync(fd, bytes, done, bytes.length - done, position + done);
+    if (!read) return false;
+    done += read;
+  }
+  return true;
+}
+function parsed(bytes) { const text = textName(bytes); if (text == null) return undefined; try { return parseNativeJson(text); } catch { return undefined; } }
+
+/** Newest-first boundary callbacks include the stopping record; results are oldest first. */
+export function tailRecords(path, start) {
+  let fd;
+  try { fd = openSync(path, 'r'); } catch { return []; }
+  const newest = [];
+  try {
+    let end; try { end = fstatSync(fd).size; } catch { return []; }
+    if (!Number.isSafeInteger(end)) throw new Error('transcript size exceeds the filesystem reader position range');
+    let carry = Buffer.alloc(0);
+    while (end > 0) {
+      const begin = Math.max(0, end - blockSize), bytes = Buffer.alloc(end - begin);
+      try { if (!readExact(fd, bytes, begin)) break; } catch { break; }
+      const block = Buffer.concat([bytes, carry]);
+      const first = begin === 0 ? -1 : block.indexOf(10);
+      if (begin !== 0 && first < 0) { carry = block; end = begin; continue; }
+      const from = first + 1;
+      let lineEnd = block.length, reached = false;
+      for (let at = block.length - 1; at >= from - 1; at--) {
+        if (at >= from && block[at] !== 10) continue;
+        const record = parsed(block.subarray(at + 1, lineEnd)); lineEnd = at;
+        if (record === undefined) continue;
+        reached = start(record); newest.push(record);
+        if (reached) break;
+      }
+      if (reached) break;
+      carry = first < 0 ? Buffer.alloc(0) : block.subarray(0, first); end = begin;
+    }
+    return newest.reverse();
+  } finally { closeSync(fd); }
+}
+
+/** Codex's first session_meta line, bounded to the native 256 KiB header read. */
+export function rolloutSession(path) {
+  let fd;
+  try {
+    fd = openSync(path, 'r'); const bytes = Buffer.alloc(blockSize);
+    let length = 0;
+    while (length < bytes.length) {
+      const count = readSync(fd, bytes, length, bytes.length - length, length);
+      if (!count) break;
+      const newline = bytes.indexOf(10, length); length += count;
+      if (newline >= 0 && newline < length) { length = newline + 1; break; }
+    }
+    const record = parsed(bytes.subarray(0, length));
+    if (stringField(record, 'type') !== 'session_meta') return null;
+    const payload = field(record, 'payload'), thread = stringField(payload, 'id'); if (thread == null) return null;
+    const nested = field(field(field(field(payload, 'source'), 'subagent'), 'thread_spawn'), 'parent_thread_id');
+    const parent = nested === undefined ? field(payload, 'parent_thread_id') : nested;
+    return { thread, parent: typeof parent === 'string' ? parent : null, cwd: stringField(payload, 'cwd') };
+  } catch { return null; }
+  finally { if (fd != null) closeSync(fd); }
+}

package/session-spend-metadata.mjs

@@ -0,0 +1,74 @@
+// Display metadata only: these names and addresses establish no caller grant.
+import { readFileSync } from 'node:fs';
+import { dirname, isAbsolute, parse, sep } from 'node:path';
+import { hostname, userInfo } from 'node:os';
+import { execFile } from 'node:child_process';
+import { nativeInteger, parseNativeJson } from './native-json.mjs';
+import { field, stringField } from './session-codec-utils.mjs';
+import { childPath, directoryEntries } from './session-spend-files.mjs';
+import { nativeTrim } from './text.mjs';
+
+function json(path) { try { return parseNativeJson(new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(readFileSync(path))); } catch { return null; } }
+function live(pid) {
+  try { process.kill(process.platform === 'win32' ? pid : Number(BigInt.asIntN(32, BigInt(pid))), 0); return true; }
+  catch (error) { return process.platform !== 'win32' && error.code === 'EPERM'; }
+}
+const optionalText = (row, key) => row[key] == null || typeof row[key] === 'string';
+const words = (text) => nativeTrim(text).split(/[\u0009-\u000d\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]+/u).join(' ');
+function path(...parts) {
+  let result = '';
+  for (const part of parts) result = isAbsolute(part) || process.platform === 'win32' && /^[A-Za-z]:/.test(part) ? part : childPath(result, part).toString('utf8');
+  return result;
+}
+const selected = (path, cwd) => !path || isAbsolute(path) || process.platform === 'win32' && /^[A-Za-z]:/.test(path) ? path : `${cwd}${sep}${path}`;
+
+export async function claudeSpendNames(homes, env, cwd) {
+  const entries = [];
+  const root = homes.claude_code, parent = root && root !== parse(root).root ? dirname(root) : '.';
+  for (const file of directoryEntries(selected(path(parent, 'sessions'), cwd))) {
+    const dot = file.name.lastIndexOf(46);
+    if (dot < 1 || !file.name.subarray(dot).equals(Buffer.from('.json'))) continue;
+    const row = json(file.path); if (row == null || typeof row !== 'object' || Array.isArray(row)) continue;
+    const pid = nativeInteger(row, 'pid');
+    if (pid == null || pid > 0xffffffffn || typeof row.sessionId !== 'string' || !row.sessionId || !row.name
+      || typeof row.messagingSocketPath !== 'string' || row.parkedJobId != null
+      || !['cwd', 'name', 'messagingSocketPath', 'status', 'version', 'tmux', 'parkedJobId', 'procStart'].every(key => optionalText(row, key))
+      || row.updatedAt != null && nativeInteger(row, 'updatedAt') == null || !live(Number(pid))) continue;
+    entries.push({ pid: Number(pid), id: row.sessionId, name: row.name, start: row.procStart ?? null });
+  }
+  const starts = new Map();
+  if (process.platform === 'darwin' && entries.some(entry => entry.start != null)) {
+    // One process-table read for this display query; an unread start is not a mismatch.
+    await new Promise(resolve => execFile('ps', ['-o', 'pid=,lstart=', '-p', entries.map(entry => entry.pid).join(',')],
+      { env: { ...env, TZ: 'UTC', LC_ALL: 'C' }, timeout: 2000, maxBuffer: 1024 * 1024 }, (error, stdout) => {
+        if (!error) for (const line of stdout.split('\n')) { const match = /^\s*(\d+)\s+(.+)$/.exec(line); if (match) starts.set(Number(match[1]), words(match[2])); }
+        resolve();
+      }));
+  }
+  const names = new Map();
+  for (const entry of entries.sort((a, b) => a.pid - b.pid)) {
+    let actual = starts.get(entry.pid);
+    if (process.platform === 'linux' && entry.start != null) {
+      try { const stat = readFileSync(`/proc/${entry.pid}/stat`, 'utf8'); actual = stat.slice(stat.lastIndexOf(')') + 1).trim().split(/\s+/)[19]; } catch { /* unread establishes no mismatch */ }
+    }
+    if (entry.start != null && actual != null && actual !== (process.platform === 'darwin' ? words(entry.start) : nativeTrim(entry.start))) continue;
+    names.set(entry.id, entry.name);
+  }
+  return names;
+}
+
+export function spendMachineName(env, cwd) {
+  let home; try { home = env.HOME || (process.platform === 'win32' && env.USERPROFILE) || userInfo().homedir || '.'; } catch { home = '.'; }
+  const supercodeHome = env.SUPERCODE_HOME || (env.XDG_CONFIG_HOME ? path(env.XDG_CONFIG_HOME, 'supercode') : path(home, '.config', 'supercode'));
+  const workspaces = selected(path(env.SUPERCODE_TEAMS_HOME || path(supercodeHome, 'teams'), 'workspaces'), cwd);
+  const contexts = json(path(workspaces, 'contexts.json')), current = stringField(contexts, 'current');
+  const context = current == null ? null : field(field(contexts, 'contexts'), current), server = stringField(context, 'server_id'), team = stringField(context, 'team_id');
+  const enrolled = server != null && team != null ? stringField(field(json(path(workspaces, 'connectors', server, team, 'enrollment.json')), 'machine'), 'name') : null;
+  let host; try { host = process.platform === 'win32' ? env.COMPUTERNAME : nativeTrim(hostname()) || null; } catch { host = null; }
+  const name = (enrolled ?? host ?? 'localhost').split('.')[0];
+  return [...name].map(c => /^[A-Z]$/.test(c) ? c.toLowerCase() : /^[a-z0-9_-]$/.test(c) ? c : '-').join('') || 'localhost';
+}
+
+export function spendAddress(machine, harness, id) {
+  return id && !/[\u0009-\u000d\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]/u.test(id) ? `sc:${machine}:${harness}:${id}` : null;
+}

package/session-spend.mjs

@@ -0,0 +1,169 @@
+// Machine-wide recorded spend, preserving token_spend's bounded tail and
+// parent/child fold. Runtime-budget readers remain with their native owners.
+import { isAbsolute, sep } from 'node:path';
+import { nativeInteger, nativeNumberKind, setNativeFloat, setNativeInteger } from './native-json.mjs';
+import { field, stringField } from './session-codec-utils.mjs';
+import { resolveHarnessHomes } from './homes.mjs';
+import { usageTimestamp, parseUsageSince, usageMoment } from './session-usage-time.mjs';
+import { claudeUse, price, recorded, sorted, sub, wrap } from './session-usage.mjs';
+import { directoryEntries, childPath, isDirectory, modifiedSince, jsonl, stem, textName, tailRecords, rolloutSession } from './session-spend-files.mjs';
+import { claudeSpendNames, spendMachineName, spendAddress } from './session-spend-metadata.mjs';
+
+const invalid = message => { throw Object.assign(new Error(message), { rpcCode: -32602 }); };
+const outOfOrder = 600000n, signed = n => BigInt.asIntN(64, n);
+const atMs = record => usageTimestamp(stringField(record, 'timestamp'));
+function sum() { return { counts: [0n, 0n, 0n, 0n, 0n], cost: 0, priced: false, unpriced: false }; }
+function add(target, source) {
+  for (let i = 0; i < 5; i++) target.counts[i] = wrap(target.counts[i] + source.counts[i]);
+  target.cost += source.cost; target.priced ||= source.priced; target.unpriced ||= source.unpriced;
+}
+function count(target, record) {
+  for (let i = 0; i < 5; i++) target.counts[i] = wrap(target.counts[i] + record.counts[i]);
+  const rate = price(record.model);
+  if (rate == null) { target.unpriced = true; return; }
+  let cost = Number(record.counts[0]) / 1e6 * rate[0];
+  for (let i = 1; i < 5; i++) cost += Number(record.counts[i]) / 1e6 * rate[i];
+  target.cost += cost * (record.fast ? rate[5] : 1) * (record.usOnly ? rate[6] : 1); target.priced = true;
+}
+function fields(sum, row = {}) {
+  for (const [key, n] of [['input_tokens', sum.counts[0]], ['output_tokens', sum.counts[1]], ['cache_read_tokens', sum.counts[2]],
+    ['cache_write_tokens', wrap(sum.counts[3] + sum.counts[4])], ['cache_write_5m_tokens', sum.counts[3]], ['cache_write_1h_tokens', sum.counts[4]]]) setNativeInteger(row, key, n);
+  if (sum.priced) { row.cost = { currency: 'USD', source: 'rate_table' }; setNativeFloat(row.cost, 'amount', Math.round(sum.cost * 1e6) / 1e6); }
+  if (sum.unpriced) row.cost_unrecorded = true;
+  return row;
+}
+function sessionOf(sessions, harness, id) {
+  const key = JSON.stringify([harness, id]); let session = sessions.get(key);
+  if (!session) { session = { harness, id, models: new Map(), cwd: null, children: new Set(), last: 0n }; sessions.set(key, session); }
+  return session;
+}
+function recordUse(session, record) {
+  let model = session.models.get(record.model); if (!model) { model = sum(); session.models.set(record.model, model); }
+  count(model, record); if (record.atMs != null && record.atMs > session.last) session.last = record.atMs;
+}
+function claudeFile(path, since, id, child, sessions) {
+  const records = tailRecords(path, record => { const at = atMs(record); return at != null && at < signed(since - outOfOrder); });
+  const responses = new Map(); let cwd = null;
+  for (const record of records) {
+    cwd = stringField(record, 'cwd') ?? cwd;
+    const response = claudeUse(record);
+    // Machine spend filters before the last-record fold; per-session usage
+    // filters after that fold. They are distinct retained native contracts.
+    if (response && response[1].atMs != null && response[1].atMs >= since) responses.set(...response);
+  }
+  if (!responses.size) return;
+  const session = sessionOf(sessions, 'claude-code', id);
+  for (const id of [...responses.keys()].sort(sorted)) recordUse(session, responses.get(id));
+  if (child == null || session.cwd == null) session.cwd = cwd ?? session.cwd;
+  if (child != null) session.children.add(child);
+}
+function claudeSpend(root, since, sessions) {
+  for (const project of directoryEntries(root)) for (const entry of directoryEntries(project.path)) {
+    if (isDirectory(entry.path)) {
+      const parent = textName(entry.name); if (parent == null) continue;
+      for (const child of directoryEntries(childPath(entry.path, 'subagents'))) if (jsonl(child.name) && modifiedSince(child.path, since)) {
+        claudeFile(child.path, since, parent, stem(child.name).toString('utf8'), sessions);
+      }
+    } else if (jsonl(entry.name) && modifiedSince(entry.path, since)) {
+      const id = textName(stem(entry.name)); if (id != null) claudeFile(entry.path, since, id, null, sessions);
+    }
+  }
+}
+function codexFile(path, since, sessions) {
+  const meta = rolloutSession(path); if (!meta) return;
+  let totalBefore = false, modelBefore = false;
+  const records = tailRecords(path, record => {
+    const at = atMs(record);
+    if (at != null && at < signed(since - outOfOrder)) {
+      totalBefore ||= stringField(field(record, 'payload'), 'type') === 'token_count';
+      modelBefore ||= stringField(record, 'type') === 'turn_context';
+    }
+    return totalBefore && modelBefore;
+  });
+  let model = 'unknown', previous = [0n, 0n, 0n], session = null;
+  for (const record of records) {
+    const payload = field(record, 'payload');
+    if (stringField(record, 'type') === 'turn_context') { model = stringField(payload, 'model') ?? model; continue; }
+    if (stringField(payload, 'type') !== 'token_count') continue;
+    const total = field(field(payload, 'info'), 'total_token_usage'); if (total === undefined) continue;
+    const now = ['input_tokens', 'output_tokens', 'cached_input_tokens'].map(key => nativeInteger(total, key) ?? 0n);
+    if (now.every((n, i) => n === previous[i])) continue;
+    const [input, output, cached] = now.map((n, i) => sub(n, previous[i])); previous = now;
+    const used = recorded(record, model, [sub(input, cached), output, cached, 0n, 0n]);
+    if (used.atMs == null || used.atMs < since) continue;
+    session ??= sessionOf(sessions, 'codex', meta.parent ?? meta.thread); recordUse(session, used);
+  }
+  if (!session) return;
+  if (meta.parent != null) session.children.add(meta.thread);
+  if ((session.cwd == null || meta.parent == null) && meta.cwd != null) session.cwd = meta.cwd;
+}
+function codexSpend(root, since, sessions) {
+  const stack = [[root, 0]];
+  while (stack.length) {
+    const [path, depth] = stack.pop();
+    for (const entry of directoryEntries(path)) {
+      if (isDirectory(entry.path)) { if (depth < 4) stack.push([entry.path, depth + 1]); continue; }
+      const name = textName(entry.name);
+      if (name?.startsWith('rollout-') && name.endsWith('.jsonl') && modifiedSince(entry.path, since)) codexFile(entry.path, since, sessions);
+    }
+  }
+}
+
+function query(params, context) {
+  if (params == null || typeof params !== 'object' || Array.isArray(params)) invalid('spend params must be an object');
+  for (const key of Object.keys(params)) if (!['since', 'harnesses', 'sort', 'limit', 'homes'].includes(key)) invalid(`unknown field ${key}`);
+  if (typeof params.since !== 'string') invalid('since must be a string');
+  const harnesses = Object.hasOwn(params, 'harnesses') ? params.harnesses : [];
+  if (!Array.isArray(harnesses) || !harnesses.every(h => typeof h === 'string')) invalid('harnesses must be a string array');
+  const sort = params.sort ?? 'cost'; if (typeof sort !== 'string') invalid('sort must be a string');
+  if (!['cost', 'tokens'].includes(sort)) invalid(`sort \`${sort}\`: the spend reading sorts by \`cost\` or \`tokens\``);
+  const bad = harnesses.find(h => !['claude-code', 'codex'].includes(h));
+  if (bad != null) invalid(`harness \`${bad}\`: the spend reading reads \`claude-code\` and \`codex\``);
+  let limit = null;
+  if (params.limit != null) {
+    let n = nativeInteger(params, 'limit');
+    if (n == null && nativeNumberKind(params, 'limit') == null && Number.isSafeInteger(params.limit) && params.limit >= 0) n = BigInt(params.limit);
+    if (n == null) invalid('limit must be an unsigned 64-bit integer');
+    limit = Number(n > BigInt(Number.MAX_SAFE_INTEGER) ? BigInt(Number.MAX_SAFE_INTEGER) : n);
+  }
+  const homes = resolveHarnessHomes(context.env);
+  if (Object.hasOwn(params, 'homes')) {
+    if (params.homes == null || typeof params.homes !== 'object' || Array.isArray(params.homes)) invalid('homes must be an object');
+    // HarnessHomes ignores unknown fields but rejects a supplied known field
+    // that is not a path string, including null.
+    for (const key of Object.keys(homes)) if (Object.hasOwn(params.homes, key)) {
+      if (typeof params.homes[key] !== 'string') invalid(`homes.${key} must be a string`);
+      homes[key] = params.homes[key];
+    }
+  }
+  for (const key of Object.keys(homes)) {
+    const home = homes[key];
+    if (home && !isAbsolute(home) && !(process.platform === 'win32' && /^[A-Za-z]:/.test(home))) homes[key] = `${context.cwd}${sep}${home}`;
+  }
+  return { since: params.since, harnesses, sort, limit, homes };
+}
+
+export async function loadMachineSpend(params, { env = process.env, cwd = process.cwd() } = {}) {
+  const selected = query(params, { env, cwd }), now = BigInt(Date.now()), since = parseUsageSince(selected.since, now), sessions = new Map();
+  if (!selected.harnesses.length || selected.harnesses.includes('claude-code')) claudeSpend(selected.homes.claude_code, since, sessions);
+  if (!selected.harnesses.length || selected.harnesses.includes('codex')) codexSpend(selected.homes.codex, since, sessions);
+  const names = await claudeSpendNames(selected.homes, env, cwd), machine = spendMachineName(env, cwd), rows = [];
+  const ordered = [...sessions.values()].sort((a, b) => sorted(a.harness, b.harness) || sorted(a.id, b.id));
+  for (const session of ordered) {
+    const total = sum(), models = [];
+    for (const model of [...session.models.keys()].sort(sorted)) { const value = session.models.get(model); add(total, value); models.push(fields(value, { model })); }
+    const row = fields(total, { harness: session.harness, session_id: session.id, address: spendAddress(machine, session.harness, session.id),
+      name: session.harness === 'codex' ? `codex-${[...session.id].slice(0, 8).join('')}` : names.get(session.id) ?? null,
+      cwd: session.cwd, subagents: session.children.size, last_at: session.last > 0n ? usageMoment(session.last) : null, models });
+    rows.push({ total, row });
+  }
+  const tokens = value => value.counts.reduce((total, n) => wrap(total + n), 0n);
+  rows.sort((a, b) => {
+    if (selected.sort !== 'tokens' && a.total.priced !== b.total.priced) return a.total.priced ? -1 : 1;
+    if (selected.sort === 'tokens' || !a.total.priced) { const x = tokens(a.total), y = tokens(b.total); return x === y ? 0 : x > y ? -1 : 1; }
+    return a.total.cost === b.total.cost ? 0 : a.total.cost > b.total.cost ? -1 : 1;
+  });
+  const total = sum(); for (const value of rows) add(total, value.total);
+  return { since: usageMoment(since), until: usageMoment(now), session_count: rows.length,
+    sessions: rows.slice(0, selected.limit ?? rows.length).map(value => value.row), total: fields(total) };
+}

package/session-usage.mjs

@@ -1,6 +1,6 @@
 // The public session reader's accounting, ported from token_spend.rs and the
 // 2026-10-03 pricing.rs snapshot. These are parity rates, not a live price feed.
-// Machine-wide accounting and native runtime budgets retain their consumers.
+// Native runtime budgets retain their independent consumers.
 import { nativeInteger, parseNativeJson, setNativeFloat, setNativeInteger } from './native-json.mjs';
 import { field, stringField } from './session-codec-utils.mjs';
 import { usageTimestamp } from './session-usage-time.mjs';
@@ -56,6 +56,9 @@ function claudeUse(record) {
     split === undefined ? written : wrap(write5m + sub(written, wrap(write5m + write1h))), write1h],
   stringField(usage, 'speed') === 'fast', stringField(usage, 'inference_geo') === 'us')];
 }
+
+// Internal accounting primitives shared by the bounded machine-tail reader.
+export { claudeUse, price, recorded, sorted, sub, wrap };
 function dayPrefix(at) {
   if (at == null) return 'unknown';
   let bytes = 0, result = '';

package/startup-prompts.mjs

@@ -0,0 +1,64 @@
+// Generated from crates/harness/src/startup_prompts.json by scripts/startup-prompts.mjs (the pre-commit hook runs it):
+// edit that table, not this file.
+export const STARTUP_PROMPTS = Object.freeze({
+  "claude-code": {
+    "startup": [],
+    "unattended": [
+      "--dangerously-skip-permissions"
+    ],
+    "unattended_chosen_by": [
+      "--permission-mode",
+      "--permission-prompts",
+      "--dangerously-skip-permissions",
+      "--allow-dangerously-skip-permissions"
+    ]
+  },
+  "codex": {
+    "startup": [
+      [
+        "-c",
+        "check_for_update_on_startup=false"
+      ],
+      [
+        "-c",
+        "projects={{cwd}={trust_level=\"trusted\"}}"
+      ],
+      [
+        "--no-alt-screen"
+      ],
+      [
+        "--dangerously-bypass-hook-trust"
+      ]
+    ],
+    "unattended": [
+      "--dangerously-bypass-approvals-and-sandbox"
+    ],
+    "unattended_chosen_by": [
+      "-a",
+      "--ask-for-approval",
+      "-s",
+      "--sandbox",
+      "--approve-for-me",
+      "--dangerously-bypass-approvals-and-sandbox"
+    ]
+  },
+  "gemini": {
+    "startup": [],
+    "unattended": [
+      "--yolo"
+    ],
+    "unattended_chosen_by": [
+      "--yolo",
+      "--approval-mode"
+    ]
+  },
+  "pi": {
+    "startup": [],
+    "unattended": [
+      "--approve"
+    ],
+    "unattended_chosen_by": [
+      "--approve"
+    ]
+  }
+});