@volter/supercode-interchange 0.1.22 → 0.1.24

package/session-config-scan.mjs

@@ -0,0 +1,141 @@
+// Recorded configuration keeps only its folds and reference ids. Message bodies
+// are read from one verified snapshot and never retained by this cache.
+import { AppendScan } from './session-append-scan.mjs';
+import { withSessionRecordFile, sessionMetaFold } from './session-records.mjs';
+import { recordedConfigurationFold } from './session-recorded-config.mjs';
+import { claudeRuntimeFold } from './session-claude-runtime.mjs';
+import { sessionFileLines } from './session-file.mjs';
+import { sessionTextError } from './session-path.mjs';
+import { parseNativeJson } from './native-json.mjs';
+import { field, stringField } from './session-codec-utils.mjs';
+import { nativeTrim } from './text.mjs';
+
+const scans = new Map();
+const MAX_ENTRIES = 400_000, MAX_FILES = 32;
+const REBUILD = Symbol('a new runtime call refers to an earlier result');
+const runtimeCall = name => ['CronCreate', 'CronDelete', 'CronList', 'ScheduleWakeup', 'Agent'].includes(name);
+const content = value => field(field(value, 'message'), 'content');
+
+function record(line, index) {
+  const raw = line.text.endsWith('\n') ? line.text.slice(0, -1) : line.text;
+  if (nativeTrim(raw) === '') return null;
+  let value;
+  try { value = parseNativeJson(raw); } catch { /* the complete manifest is unknown */ }
+  return { raw, value, index };
+}
+
+class ConfigurationScan extends AppendScan {
+  lines = 0; calls = new Set(); results = new Set(); posture = true;
+  constructor(reader, source) {
+    super(reader); this.source = source;
+    this.fold = recordedConfigurationFold(); this.meta = sessionMetaFold(source, this.fold);
+    this.runtime = source === 'claude_code' ? claudeRuntimeFold() : null;
+  }
+  get entries() { return 1 + this.calls.size + this.results.size + this.meta.meta.codex_headers.length + (this.runtime?.retainedEntries ?? 0); }
+
+  first(item, { commit = true, calls = new Set() } = {}) {
+    if (!item) return;
+    this.meta.observe(item);
+    if (!this.runtime) return;
+    if (item.value === undefined) { this.posture = false; return; }
+    const blocks = content(item.value);
+    if (stringField(item.value, 'type') === 'assistant' && Array.isArray(blocks)) {
+      for (const block of blocks) {
+        if (stringField(block, 'type') !== 'tool_use' || !runtimeCall(stringField(block, 'name'))) continue;
+        const id = stringField(block, 'id');
+        if (id == null) continue; // The runtime fold supplies the same malformed-call refusal.
+        // The complete manifest collects all calls before replaying any result.
+        // A retroactive reference changes that old replay, rather than merely
+        // extending it. Rebuild just as for a rewritten prefix.
+        if (this.results.has(id)) throw REBUILD;
+        const key = `${stringField(block, 'name') === 'Agent' ? 'child' : 'call'}:${id}`;
+        if (this.calls.has(key) || calls.has(key)) this.posture = false;
+        calls.add(key);
+        if (commit) this.calls.add(key);
+      }
+    }
+    if (this.posture) try { this.runtime.call(item.value, item.index + 1, null); } catch { this.posture = false; }
+  }
+  second(item) {
+    if (item && this.runtime && this.posture) try { this.runtime.record(item.value, item.index + 1, null); } catch { this.posture = false; }
+  }
+
+  async extend(reader) {
+    const from = this.bytes, firstLine = this.lines, results = [];
+    // All new calls precede the new results in the runtime replay. Only the
+    // appended range is decoded; the retained prefix has already been folded.
+    for await (const line of sessionFileLines(reader, from)) {
+      if (!line.terminated) break;
+      const item = record(line, this.lines++);
+      this.first(item);
+      if (this.runtime && stringField(item?.value, 'type') === 'user' && Array.isArray(content(item.value)))
+        for (const block of content(item.value)) if (stringField(block, 'type') === 'tool_result') {
+          const id = stringField(block, 'tool_use_id'); if (id != null) results.push(id);
+        }
+      this.took(line.bytes, line.offset + line.length); this.bytes = line.offset + line.length;
+    }
+    if (this.runtime && this.posture) {
+      let index = firstLine;
+      for await (const line of sessionFileLines(reader, from)) {
+        if (!line.terminated) break;
+        this.second(record(line, index++));
+      }
+    }
+    for (const id of results) this.results.add(id);
+    await this.settle(reader, from);
+  }
+
+  async answer(reader, harness) {
+    let snapshot = this;
+    if (reader.size > this.bytes) {
+      // An unterminated last line participates in this answer, never in the
+      // committed prefix. Its later completion cannot count it twice.
+      snapshot = Object.create(ConfigurationScan.prototype);
+      Object.assign(snapshot, this, { fold: this.fold.clone(), runtime: this.runtime?.clone() ?? null });
+      snapshot.meta = this.meta.clone(snapshot.fold);
+      for await (const line of sessionFileLines(reader, this.bytes)) {
+        const item = record(line, this.lines);
+        snapshot.first(item, { commit: false }); snapshot.second(item);
+      }
+    }
+    let mode = null;
+    if (snapshot.runtime && snapshot.posture) try { mode = snapshot.runtime.permissionMode(); } catch { /* invalid complete manifest */ }
+    return snapshot.fold.finish(snapshot.meta.meta, harness, mode);
+  }
+}
+
+function retain(path, scan, metrics) {
+  scans.delete(path); scans.set(path, scan);
+  let entries = [...scans.values()].reduce((sum, item) => sum + item.entries, 0);
+  for (const [other, item] of scans) {
+    if (scans.size <= MAX_FILES && entries <= MAX_ENTRIES || item === scan) break;
+    scans.delete(other); entries -= item.entries;
+  }
+  if (metrics) metrics.configuration_retained_entries = entries;
+}
+
+/** Null retains the historical document/fallback reader for other formats. */
+export async function loadRecordedConfigurationRecords(locator, context = {}) {
+  const path = locator.storage.path;
+  try {
+    const read = await withSessionRecordFile(locator, async (source, reader) => {
+      let scan = scans.get(path); scans.delete(path);
+      if (!scan || scan.source !== source || !await scan.holds(reader)) scan = new ConfigurationScan(reader, source);
+      try { await scan.extend(reader); }
+      catch (error) {
+        if (error !== REBUILD) throw error;
+        scan = new ConfigurationScan(reader, source); await scan.extend(reader);
+      }
+      let result;
+      try { result = await scan.answer(reader, locator.harness); }
+      catch (error) { if (error !== REBUILD) throw error; return { scan, result: null }; }
+      return { scan, result };
+    }, context);
+    if (read == null) return null;
+    retain(path, read.result.scan, context.metrics);
+    return read.result.result;
+  } catch (error) {
+    scans.delete(path);
+    throw ['ERR_ENCODING_INVALID_ENCODED_DATA', 'ERR_STRING_TOO_LONG'].includes(error?.code) ? sessionTextError(path, error) : error;
+  }
+}

package/session-convert.d.ts

@@ -0,0 +1,33 @@
+export const CONVERSION_FORMATS: readonly ['claude-code', 'codex', 'opencode', 'pi', 'grok', 'gemini', 'goose', 'hermes'];
+export interface ConversionOptions {
+  file: string;
+  to: typeof CONVERSION_FORMATS[number];
+  out?: string | null;
+  sessionId?: string | null;
+  selector?: string | null;
+  cwd?: string | null;
+}
+export interface ConversionSummary {
+  out?: string;
+  source: string;
+  target: string;
+  messages: number;
+  parity: 'verbatim' | 'cross' | 'id' | 'metadata' | 'nonverbatim' | 'view';
+  complete: boolean;
+  reduced: { stubCount: number; viewTokens: bigint; fullTokens: bigint } | null;
+}
+export interface ConversionContext {
+  env?: NodeJS.ProcessEnv;
+  cwd?: string;
+  signal?: AbortSignal;
+  storeRoot?: string;
+  output?: (text: string) => void | Promise<void>;
+  diagnostic?: (text: string, role?: 'ERR' | 'WARN') => void;
+  summary?: (result: ConversionSummary) => void | Promise<void>;
+}
+/** Complete CLI conversion. Writes an explicitly requested output or hands
+ * text to output; Hermes import executes its own vendor command only for a
+ * literal-path input, preserving the existing native command's distinction. */
+export function convertSession(options: ConversionOptions, context?: ConversionContext): Promise<ConversionSummary | {
+  imported: { session_id: string; home: string; rollout: string; via: string };
+}>;

package/session-convert.mjs

@@ -0,0 +1,179 @@
+// Complete convert behavior. Literal sources and saved working transcripts
+// are different inputs; a reduced saved session always exports its full sidecar.
+import { mkdir, readdir, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, extname, join } from 'node:path';
+import { loadSessionPath, looksLikeSessionSqlite } from './session-path.mjs';
+import { readOpenCodeSqlite } from './session-opencode-store.mjs';
+import { readStore, statement, text as sqliteText } from './sqlite-reader.mjs';
+import { fromSidecarStr } from './session-native.mjs';
+import { rawVerbatim } from './session-model.mjs';
+import { toSessionJsonl, toSessionJsonlSpliced } from './session-write.mjs';
+import { importIntoHermes } from './session-hermes-import.mjs';
+import { SavedSessionReader, parseSavedMessages, savedPathExists, savedSessionRoot } from './session-saved-read.mjs';
+import { estimateViewTokens, rejectReducedSidecar, verifyReductionLog } from './reduction-log.mjs';
+import { reapplyReductionLog } from './reduction-view.mjs';
+import { nativeTrim } from './text.mjs';
+import { cloneNativeJson } from './native-json.mjs';
+
+export const CONVERSION_FORMATS = Object.freeze(['claude-code', 'codex', 'opencode', 'pi', 'grok', 'gemini', 'goose', 'hermes']);
+const formatName = name => name === 'claude-code' ? 'claude_code' : name === 'hermes' ? 'codex' : name;
+export function conversionParseLoss(session) {
+  const sessions = [session, ...session.subagents];
+  return { errors: sessions.reduce((sum, value) => sum + value.parse_error_lines, 0),
+    lines: sessions.reduce((sum, value) => sum + value.raw.filter(line => nativeTrim(line) !== '').length, 0),
+    children: session.subagents.filter(value => value.parse_error_lines > 0).length,
+    childErrors: session.subagents.reduce((sum, value) => sum + value.parse_error_lines, 0) };
+}
+function childDirectory(path) { return join(dirname(path), basename(path, extname(path)), 'subagents'); }
+function lossError(session, path, written, diagnostic) {
+  const { errors, lines, children, childErrors } = conversionParseLoss(session);
+  if (!errors) return;
+  const note = childErrors ? ` (${childErrors} of which came from ${children} subagent transcript(s) under ${childDirectory(path)}/)` : '';
+  const outputNote = written ? `everything above reflects only the ${Math.max(0, lines - errors)} line(s) that DID parse, not the complete session`
+    : errors < lines ? 'no provider call was made because the session was only partially loaded' : 'no output was written because no input line parsed successfully';
+  diagnostic(`error: ${path} — ${errors} of ${lines} line(s) failed to parse and were DROPPED${note} (the file may be truncated or corrupted); ${outputNote}`, 'ERR');
+  throw new Error(written
+    ? `${path}: ${errors} of ${lines} line(s) failed to parse — refusing to report success on a partially-loaded session (PARITY-15)${note}`
+    : errors < lines ? `${path}: ${errors} of ${lines} line(s) failed to parse — refusing to continue a partially-loaded session; no provider call was made (PARITY-15)${note}`
+      : `${path}: all ${lines} line(s) failed to parse — no session data loaded and no output written (PARITY-15)${note}`);
+}
+async function alias(source, out) {
+  try {
+    const [left, right] = await Promise.all([stat(source, { bigint: true }), stat(out, { bigint: true })]);
+    return left.dev === right.dev && left.ino === right.ino;
+  } catch { return source === out; }
+}
+async function refusePartialOverwrite(session, input, out, diagnostic) {
+  const { errors, lines } = conversionParseLoss(session);
+  if (!errors || out == null) return;
+  let source = await alias(input, out) ? input : null;
+  if (source == null && session.meta.source === 'claude_code') {
+    let files; try { files = await readdir(childDirectory(input)); } catch { files = []; }
+    for (const file of files) if (extname(file) === '.jsonl') {
+      const child = join(childDirectory(input), file); if (await alias(child, out)) { source = child; break; }
+    }
+  }
+  if (source == null) return;
+  const primary = source === input;
+  diagnostic(`error: ${input} — ${errors} of ${lines} line(s) failed to parse; \`--out ${out}\` identifies ${primary ? 'the input file' : `source transcript \`${source}\``}, so no output was written (use a distinct path or stdout to keep the recoverable partial conversion)`, 'ERR');
+  throw new Error(`${input}: refusing to overwrite a parse-damaged source transcript with partial output (PARITY-15/${primary ? 'D41' : 'D42'})`);
+}
+async function warnOpenCode(path, selector, diagnostic) {
+  if (selector != null) return;
+  let ids;
+  try {
+    ids = (await readStore(path, db => statement(db, 'SELECT id FROM session ORDER BY time_created, id').all().map(row => sqliteText(row.id)))).result;
+  } catch { return; }
+  if (ids.length <= 1) return;
+  let chosen = '<unknown>';
+  try { chosen = (await readStore(path, db => sqliteText(statement(db, 'SELECT id FROM session ORDER BY (parent_id IS NULL) DESC,time_updated DESC LIMIT 1').get()?.id))).result; } catch { /* warning names unknown selection */ }
+  diagnostic(`warning: ${path} holds ${ids.length} sessions; converting ${chosen} (most-recently-updated) — pass --opencode-session <id> to pick another. All session ids: ${ids.join(', ')}`);
+}
+
+function childOutput(child, sessionId) {
+  if (conversionParseLoss(child).errors) throw new Error('refusing stored Claude subagent export because the loaded session contains parse loss');
+  return sessionId == null && !(child.imported_message_count != null && child.imported_message_count < child.messages.length)
+    ? rawVerbatim(child) : toSessionJsonlSpliced(child, 'claude_code', sessionId);
+}
+async function prepareChildren(store, name, out, source, target, sessionId) {
+  if (source !== 'claude_code' || target !== 'claude_code') return [];
+  const ids = [];
+  for (const id of await store.childIds(name)) {
+    const source = await store.child(name, id);
+    if (source == null) throw new Error(`subagent \`${id}\` disappeared while exporting \`${name}\``);
+    let child;
+    try { child = fromSidecarStr(source); }
+    catch (error) { throw new Error(`parsing stored subagent \`${id}\` for \`${name}\`: ${error.message}`); }
+    if (child.meta.source !== 'claude_code') continue;
+    if (!child.raw_is_verbatim) throw new Error(`stored Claude subagent \`${id}\` for \`${name}\` has no verbatim source bytes`);
+    childOutput(child, sessionId); ids.push(id);
+  }
+  if (!ids.length) return [];
+  if (out == null) throw new Error(`Claude bundle export for \`${name}\` has ${ids.length} subagent transcript(s); use \`--out <file>\` so Volter Harness can recreate \`<file-stem>/subagents/\``);
+  if (!basename(out) || ['.', '..'].includes(basename(out))) throw new Error(`cannot derive a Claude subagent directory from output path ${out}`);
+  const names = new Set();
+  return ids.map(id => {
+    const bare = id.startsWith('agent-') ? id.slice(6) : id;
+    if (!bare) throw new Error(`stored Claude subagent id \`${id}\` has no filename-safe id body`);
+    const filename = `agent-${bare}.jsonl`;
+    if (names.has(filename)) throw new Error(`stored Claude subagent ids collide at output filename \`${filename}\` for \`${name}\``);
+    names.add(filename); return { id, path: join(childDirectory(out), filename) };
+  });
+}
+async function writeChildren(store, name, children, sessionId) {
+  for (const { id, path } of children) {
+    const source = await store.child(name, id);
+    if (source == null) throw new Error(`subagent \`${id}\` disappeared while writing \`${name}\``);
+    const child = fromSidecarStr(source), text = childOutput(child, sessionId);
+    await mkdir(dirname(path), { recursive: true }); await writeFile(path, text);
+  }
+}
+
+/** Write only after loading/validating the selected complete input. Partial
+ * literal output remains useful but ends in a failure; corrupt saved pointers
+ * fail before any primary or child output. Callbacks own CLI presentation. */
+export async function convertSession({ file, to, out = null, sessionId = null, selector = null, cwd = null }, context = {}) {
+  if (!CONVERSION_FORMATS.includes(to)) throw new TypeError(`unknown conversion target: ${to}`);
+  const target = formatName(to), diagnostic = context.diagnostic ?? (() => {}), output = context.output ?? (() => {}), summary = context.summary ?? (() => {});
+  let session, jsonl, parity, reduced = null, store, name, children = [], complete = true, literal = false;
+  if (await savedPathExists(file)) {
+    literal = true;
+    try {
+      const sqlite = await looksLikeSessionSqlite(file);
+      if (sqlite) await warnOpenCode(file, selector, diagnostic);
+      session = sqlite && selector != null ? (await readOpenCodeSqlite(file, selector)).result
+        : await loadSessionPath(file, { env: context.env ?? process.env });
+    } catch (error) { throw new Error(`loading session ${file}: ${error.message}`, { cause: error }); }
+    const counts = conversionParseLoss(session);
+    if (counts.errors > 0 && counts.errors === counts.lines) lossError(session, file, false, diagnostic);
+    await refusePartialOverwrite(session, file, out, diagnostic);
+    if (session.raw.length && !session.messages.length) diagnostic(`warning: ${file} parsed to zero messages from a non-empty file — it may be corrupt or truncated; the output will be empty`, 'WARN');
+    if (cwd != null) session.meta.cwd = cwd;
+    const verbatim = sessionId == null && cwd == null && target === session.meta.source && session.raw_is_verbatim;
+    if (sessionId != null) session.meta.session_id = sessionId;
+    if (to === 'hermes') {
+      const imported = await importIntoHermes(session, context);
+      await output(`imported into hermes as ${imported.session_id} (${imported.home}): continue with \`hermes --resume ${imported.session_id}\`\n`);
+      return { imported };
+    }
+    jsonl = verbatim ? rawVerbatim(session) : toSessionJsonl(session, target);
+    parity = verbatim ? 'verbatim' : target !== session.meta.source ? 'cross' : sessionId != null ? 'id' : cwd != null ? 'metadata' : 'nonverbatim';
+    complete = counts.errors === 0;
+  } else {
+    store = new SavedSessionReader(context.storeRoot ?? savedSessionRoot(context.env)); name = await store.resolve(file);
+    const sidecar = await store.read(name, '.sidecar.jsonl', true);
+    if (sidecar != null) {
+      try { session = fromSidecarStr(sidecar); } catch (error) { throw new Error(`parsing sidecar for \`${name}\`: ${error.message}`); }
+      const log = await store.reductionLog(name);
+      try { verifyReductionLog(log, session.messages); }
+      catch (error) { throw new Error(`${error.message} — repair pointer: \`sessions show-reductions ${name}\``, { cause: error }); }
+      const view = reapplyReductionLog(session.messages, log);
+      reduced = { stubCount: log.reductions.length, viewTokens: estimateViewTokens(view), fullTokens: estimateViewTokens(session.messages) };
+      rejectReducedSidecar(session);
+      const original = session;
+      session = cloneNativeJson(original);
+      if (cwd != null) session.meta.cwd = cwd;
+      try { jsonl = toSessionJsonlSpliced(session, target, sessionId); }
+      catch (error) { throw new Error(`exporting reduced session: ${error.message}`, { cause: error }); }
+      if (target !== session.meta.source) parity = 'cross';
+      else if (jsonl === rawVerbatim(session)) parity = 'verbatim';
+      else {
+        let baseline; if (sessionId != null) try { baseline = toSessionJsonlSpliced(original, target); } catch { /* non-authoritative diagnostic baseline */ }
+        parity = baseline != null && baseline !== jsonl ? 'id' : 'view';
+      }
+      children = await prepareChildren(store, name, out, session.meta.source, target, sessionId);
+    } else {
+      session = parseSavedMessages(name, await store.read(name, '.jsonl'));
+      if (cwd != null) session.meta.cwd = cwd;
+      if (sessionId != null) session.meta.session_id = sessionId;
+      jsonl = toSessionJsonl(session, target); parity = 'view';
+    }
+  }
+  if (out != null) {
+    try { await writeFile(out, jsonl); } catch (error) { throw new Error(`writing ${out}: ${error.message}`, { cause: error }); }
+    await summary({ out, source: session.meta.source, target, messages: session.messages.length, parity, complete, reduced });
+  } else await output(jsonl);
+  if (literal) lossError(session, file, true, diagnostic);
+  else await writeChildren(store, name, children, sessionId);
+  return { source: session.meta.source, target, messages: session.messages.length, parity, complete, reduced };
+}

package/session-emission-version.json

@@ -0,0 +1 @@
+"0.5.450"

package/session-file.mjs

@@ -2,11 +2,16 @@ import { constants } from 'node:buffer';
 import { withSessionFile } from './file-io.mjs';
 
 const MAX_TEXT = constants.MAX_STRING_LENGTH;
+// A document whose text fits the runtime string limit needs no more than
+// four encoded bytes per UTF-16 unit. Compressed input gets the same finite
+// byte admission; compressed framing is not evidence of decoded text size.
+export const MAX_SESSION_DOCUMENT_BYTES = Math.min(constants.MAX_LENGTH, MAX_TEXT * 4);
 /** The session-read doors' answer for a file this reader cannot read for what is in it (text that is not UTF-8,
  * or too long to hold): the same bytes get the same answer from the same reader. Any other failure of a read (the
  * disk, a file changed under it, a fault in the reader) answers the generic code and says nothing of the file. */
 export const SESSION_UNREADABLE = -32050;
 export const textTooLong = (path, cause) => Object.assign(new Error(`${path} holds more text than this runtime keeps in one string (${MAX_TEXT} UTF-16 units); it can be read record by record, never as one document`, { cause }), { code: 'EFBIG', rpcCode: SESSION_UNREADABLE });
+export const sessionByteLimit = (path, part, cause) => Object.assign(new Error(`${path} exceeds the session document byte budget (${MAX_SESSION_DOCUMENT_BYTES} bytes) for ${part}; this reader leaves the source unchanged`, { cause }), { code: 'EFBIG', rpcCode: SESSION_UNREADABLE });
 export const decodeSessionUtf8 = (bytes) => new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
 
 /** The file from `from` to its end, for a reader that needs it as one text.
@@ -14,6 +19,7 @@ export const decodeSessionUtf8 = (bytes) => new TextDecoder('utf-8', { fatal: tr
  * held: their UTF-16 length is counted a bounded block at a time. A compressed
  * file's bytes are not its text, which is measured where it is decoded. */
 export async function sessionFileBytes(reader, from = 0) {
+  if (reader.path.endsWith('.zst') && reader.size - from > MAX_SESSION_DOCUMENT_BYTES) throw sessionByteLimit(reader.path, 'compressed input');
   if (reader.size - from > MAX_TEXT && !reader.path.endsWith('.zst')) {
     let units = 0;
     for (let offset = from; offset < reader.size && units <= MAX_TEXT;) {
@@ -43,11 +49,15 @@ export async function* sessionFileLines(reader, from = 0) {
     const chunkStart = offset; offset += chunk.length;
     let at = 0, end;
     while ((end = chunk.indexOf(10, at)) !== -1) {
+      if (pending + end + 1 - at > MAX_SESSION_DOCUMENT_BYTES) throw sessionByteLimit(reader.path, 'one physical record');
       pieces.push(chunk.subarray(at, end + 1)); pending += end + 1 - at;
       yield fileLine(start, pieces.length === 1 ? pieces[0] : Buffer.concat(pieces, pending), true);
       start = chunkStart + end + 1; at = end + 1; pieces = []; pending = 0;
     }
-    if (at < chunk.length) { pieces.push(chunk.subarray(at)); pending += chunk.length - at; }
+    if (at < chunk.length) {
+      if (pending + chunk.length - at > MAX_SESSION_DOCUMENT_BYTES) throw sessionByteLimit(reader.path, 'one physical record');
+      pieces.push(chunk.subarray(at)); pending += chunk.length - at;
+    }
   }
   if (pending) yield fileLine(start, Buffer.concat(pieces, pending), false);
 }

package/session-follower.mjs

@@ -12,6 +12,7 @@ import { readGooseSqlite } from './session-goose.mjs';
 import { readHermesSqlite } from './session-hermes.mjs';
 import { readOpenCodeSqlite } from './session-opencode-store.mjs';
 import { ClaudeAppendState } from './session-claude-append.mjs';
+import { loadClaudeBackgroundAgents } from './session-claude-index.mjs';
 
 const pathOrder = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
 const identityKeys = ['source', 'session_id', 'model', 'cwd', 'system_prompt', 'agent_id', 'parent_tool_use_id', 'lineage'];
@@ -135,12 +136,20 @@ export class SessionFollower {
     if (this.options.displayHistory) return null;
     try { return ClaudeAppendState.fromSession(session, this.options.fidelity); } catch { return null; }
   }
-  #snapshot(reason) { return this.#sequence({ type: 'session_snapshot', reason, session: normalizedSessionJson(this.current) }); }
+  #snapshot(reason) { return this.#sequence({ type: 'session_snapshot', reason, session: { ...normalizedSessionJson(this.current), ...(this.agents ? { background_agents: this.agents } : {}) } }); }
+  /** A Claude Code transcript's background agents now, of the whole file (null for any other source): whether they
+   * changed since the last event said them. */
+  async #readAgents(source) {
+    if (source !== 'claude_code') { const changed = this.agents != null; this.agents = null; return changed; }
+    const agents = await loadClaudeBackgroundAgents({ harness: 'claude-code', storage: { kind: 'file', path: this.path } }, this.options).catch(() => this.agents);
+    const changed = !nativeJsonEqual(agents ?? null, this.agents ?? null);
+    this.agents = agents; return changed;
+  }
   #error(message) { return this.#sequence({ type: 'watch_error', recoverable: true, message }); }
   /** Serial polls only; a service serializes them per follower. */
   async poll() {
     if (this.closed) throw new Error('the session follower is closed');
-    if (this.initialPending) { this.initialPending = false; return this.#snapshot('initial'); }
+    if (this.initialPending) { this.initialPending = false; await this.#readAgents(this.current.meta.source); return this.#snapshot('initial'); }
     const observed = await sourceFingerprint(this.path, this.current, this.selected, this.options.includeSubagents);
     if (nativeJsonEqual(observed, this.fingerprint)) return null;
     const companionsSame = nativeJsonEqual(observed.filter((stamp) => stamp.path !== this.path), this.fingerprint.filter((stamp) => stamp.path !== this.path));
@@ -169,13 +178,16 @@ export class SessionFollower {
       if (error.code === 'ESTALE') this.fingerprint = []; // retry a raced read even if the last writer then stopped
       return this.#error(`could not reload ${this.path}: ${error.message}; retaining the last good snapshot`);
     }
-    if (normalizedEqual(this.current, next)) { this.current = next; return null; }
+    // A notification can end an agent before any message shows it (queued while the session works).
+    const agentsChanged = await this.#readAgents(next.meta.source);
+    if (normalizedEqual(this.current, next)) { this.current = next; return agentsChanged ? this.#snapshot('background_agents') : null; }
     const identitySame = sameIdentity(this.current, next);
     const prefix = identitySame && sameChildren(this.current, next) ? appendPrefix(this.current.messages, next.messages) : 0;
     this.current = next;
     if (prefix > 0 && next.messages.length > prefix) return this.#sequence({ type: 'messages_appended', session_id: next.meta.session_id,
-      messages: next.messages.slice(prefix).map(messageJson), total_message_count: Math.max(next.imported_message_count ?? next.messages.length, next.messages.length) });
+      messages: next.messages.slice(prefix).map(messageJson), total_message_count: Math.max(next.imported_message_count ?? next.messages.length, next.messages.length),
+      ...(this.agents ? { background_agents: this.agents } : {}) });
     return this.#snapshot(identitySame ? 'history_rewritten' : 'source_changed');
   }
-  close() { this.closed = true; this.current = null; this.fingerprint = []; this.appendState = null; }
+  close() { this.closed = true; this.current = null; this.fingerprint = []; this.appendState = null; this.agents = null; }
 }

package/session-fresh-id.mjs

@@ -0,0 +1,15 @@
+import { randomBytes } from 'node:crypto';
+
+/** Rust uses random UUID bytes with a clock fallback if entropy is unavailable. */
+export function freshSessionId() {
+  let bytes;
+  try { bytes = randomBytes(16); }
+  catch {
+    let nanos = BigInt(Math.max(0, Date.now())) * 1_000_000n;
+    bytes = Buffer.alloc(16);
+    for (let at = 0; at < bytes.length; at++) { bytes[at] = Number(nanos & 255n); nanos >>= 8n; }
+  }
+  bytes[6] = (bytes[6] & 15) | 64; bytes[8] = (bytes[8] & 63) | 128;
+  const hex = bytes.toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/session-hermes-import.mjs

@@ -0,0 +1,61 @@
+// Hermes owns its session database and writes it through this CLI door.
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve, sep } from 'node:path';
+import { userInfo } from 'node:os';
+import { spawn } from 'node:child_process';
+import { toSessionJsonl } from './session-write.mjs';
+
+function hermesHome(env) {
+  if (env.HERMES_HOME != null) return env.HERMES_HOME;
+  let home = env.HOME || (process.platform === 'win32' && env.USERPROFILE);
+  if (!home) try { home = userInfo().homedir; } catch { home = ''; }
+  return home ? nativeJoin(home, '.hermes') : '.hermes';
+}
+function nativeJoin(root, ...parts) {
+  return process.platform === 'win32' && /^[A-Za-z]:$/u.test(root) ? root + parts.join(sep) : join(root, ...parts);
+}
+async function importCommand(rollout, home, { env, cwd, signal }) {
+  signal?.throwIfAborted();
+  return await new Promise((resolveResult, reject) => {
+    const stdout = [], stderr = [];
+    const child = spawn('hermes', ['sessions', 'import', '--from', 'codex', rollout], { cwd,
+      env: { ...env, HERMES_HOME: home, HERMES_NO_ONBOARDING: '1', HERMES_NONINTERACTIVE: '1' }, windowsHide: true });
+    // This handle and PID belong to this command only; never select a process
+    // by name. Client closure stops the import without claiming a rollback.
+    let forceStop;
+    const abort = () => {
+      child.kill('SIGTERM');
+      forceStop = setTimeout(() => child.kill('SIGKILL'), 250); forceStop.unref();
+    };
+    signal?.addEventListener('abort', abort, { once: true });
+    if (signal?.aborted) abort();
+    child.stdout.on('data', chunk => stdout.push(chunk)); child.stderr.on('data', chunk => stderr.push(chunk));
+    let startError;
+    child.once('error', error => { startError = error; });
+    child.once('close', (code, stoppedBy) => {
+      clearTimeout(forceStop);
+      signal?.removeEventListener('abort', abort);
+      if (startError) reject(new Error(`\`hermes sessions import\` could not start: ${startError.message}`, { cause: startError }));
+      else if (signal?.aborted) reject(signal.reason ?? new Error('Hermes import cancelled'));
+      else resolveResult({ code, stoppedBy, stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8') });
+    });
+  });
+}
+
+export async function importIntoHermes(session, { env = process.env, cwd = process.cwd(), signal } = {}) {
+  signal?.throwIfAborted();
+  const home = hermesHome(env), rolloutDirectory = nativeJoin(home, 'imports', 'supercode');
+  await mkdir(resolve(cwd, rolloutDirectory), { recursive: true });
+  const rollout = nativeJoin(rolloutDirectory, `rollout-${Math.max(0, Date.now())}-${session.meta.session_id ?? 'session'}.jsonl`);
+  await writeFile(resolve(cwd, rollout), toSessionJsonl(session, 'codex'));
+  const output = await importCommand(rollout, home, { env, cwd, signal });
+  let sessionId;
+  for (const line of output.stdout.split(/\r?\n/u)) {
+    if (line.includes(' session as ')) { sessionId = line.split(' session as ')[1].trim(); break; }
+  }
+  if (output.code === 0 && sessionId) return { session_id: sessionId, home, rollout, via: 'hermes sessions import --from codex' };
+  if (output.code !== 0 && output.stderr.includes('database is locked')) throw new Error(
+    `Hermes's session database is locked by another Hermes process; Hermes waited, gave up, and imported nothing. The converted rollout is kept at ${rollout}: run \`hermes sessions import --from codex ${rollout}\` once Hermes is idle.`);
+  const status = output.stoppedBy ? `signal: ${output.stoppedBy}` : `exit status: ${output.code}`;
+  throw new Error(`\`hermes sessions import --from codex ${rollout}\` did not report a session id (exit ${status}): ${output.stdout.trim()}${output.stderr.trim()}`);
+}

package/session-hermes.mjs

@@ -44,7 +44,7 @@ export async function readHermesSqlite(path, sessionId = null, { metrics = {} }
   const info = await sourceStat(path);
   if (!info?.isFile()) throw new Error(`Hermes SQLite store not found at ${path} — expected a \`state.db\` file`);
   return readStore(path, (db) => {
-    const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map((row) => row.name));
+    const tables = new Set(statement(db, "SELECT name FROM sqlite_master WHERE type='table'").all().map((row) => row.name));
     if (!['sessions', 'messages', 'schema_version'].every((table) => tables.has(table)) || tables.has('schema_meta')) {
       throw new Error(`${path} is SQLite but not a Hermes state.db (missing sessions/messages/schema_version, or it carries OpenClaw's schema_meta)`);
     }

package/session-import.mjs

@@ -0,0 +1,37 @@
+// The public import door reads the supplied document only. Format selection is
+// explicit; it does not discover a home, write a store, or invoke a vendor.
+import { readSessionDocument } from './session-document.mjs';
+import { normalizedSessionJson } from './session-model.mjs';
+
+const formats = new Map([
+  ['claude-code', 'claude_code'], ['codex', 'codex'], ['opencode', 'opencode'],
+  ['open-code', 'opencode'], ['pi', 'pi'], ['grok', 'grok'],
+  ['gemini', 'gemini'], ['goose', 'goose'], ['hermes', 'codex'],
+]);
+const invalid = message => { throw Object.assign(new Error(message), { rpcCode: -32602 }); };
+
+function transferFormat(value) {
+  // Serde's externally tagged unit variants admit both a string and a
+  // single-key object whose value is null. No format auto-detection occurs.
+  if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    const keys = Object.keys(value);
+    if (keys.length !== 1 || value[keys[0]] !== null) invalid('source_harness must be a transfer format');
+    value = keys[0];
+  }
+  if (typeof value !== 'string' || !formats.has(value)) invalid(`unknown source_harness: ${String(value)}`);
+  return formats.get(value);
+}
+
+export function importSessionDocument(params) {
+  let source, content;
+  if (Array.isArray(params)) {
+    if (params.length !== 2) invalid('session import positional params require source_harness and content');
+    [source, content] = params;
+  } else {
+    if (params === null || typeof params !== 'object') invalid('session import params must be an object or positional array');
+    source = params.source_harness; content = params.content;
+  }
+  source = transferFormat(source);
+  if (typeof content !== 'string') invalid('content must be a string');
+  return { session: normalizedSessionJson(readSessionDocument(content, { source, fidelity: 'byte_lossless' })) };
+}

package/session-inspect.d.ts

@@ -0,0 +1,18 @@
+import type { Session } from './session-model.js';
+export interface ReducedInspection {
+  stubCount: number; fullTokens: bigint; viewTokens: bigint; pct: bigint; sidecarPath: string; attribution: object;
+}
+export interface InspectionContext {
+  env?: Record<string, string | undefined>; storeRoot?: string;
+  output?: (text: string) => void | Promise<void>;
+  diagnostic?: (text: string, role?: string) => void;
+  render?: (value: { session: Session; reduced: ReducedInspection | null; opencodeStore: object | null }) => void | Promise<void>;
+  schemas?: () => void | Promise<void>;
+}
+/** Complete source reading, strict saved pointers and persisted working-view
+ * precedence. Prints partial reports before refusing literal parse loss. */
+export function inspectSession(options: { file: string; json?: boolean }, context?: InspectionContext): Promise<{ session: object; opencode_store?: object }>;
+export function inspectionSessionSummary(session: Session, reduced?: ReducedInspection | null): object;
+export function inspectionStoredRecords(session: Session): number | null;
+export function inspectionFirstLine(text: string, maximum: number): string;
+export function inspectionPercentage(view: bigint, full: bigint): bigint;