@volter/supercode-interchange 0.1.22 → 0.1.24

package/session-read.mjs

@@ -1,10 +1,12 @@
-// Caller-owned public read operations. Parsing never goes to a native service
+// Caller-owned public session 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, stringifyNativeJsonPretty } from './native-json.mjs';
+import { nativeInteger, nativeNumberKind, parseNativeJson, stringifyNativeJson, stringifyNativeJsonMember, stringifyNativeJsonPretty } from './native-json.mjs';
 import { loadSessionLocator } from './session-path.mjs';
 import { loadSessionDisplayLocator, loadSessionDisplayFrom } from './session-display.mjs';
-import { withClaudeReadIndex, supportsClaudeReadIndex, loadClaudeRecordWindow } from './session-claude-index.mjs';
+import { withClaudeReadIndex, supportsClaudeReadIndex, loadClaudeRecordWindow, loadClaudeHistoryWindow, loadClaudeBackgroundAgents, MARK_CHECKPOINT } from './session-claude-index.mjs';
+export { MARK_CHECKPOINT, chainMark } from './session-claude-index.mjs';
+export { sweepScanDirectories } from './session-claude-scan-store.mjs';
 import { loadCodexRecordWindow } from './session-codex-window.mjs';
 import { SessionFollower } from './session-follower.mjs';
 import { normalizedSessionJson } from './session-model.mjs';
@@ -12,17 +14,48 @@ import { boundSessionView, projectedMessageWindow, projectedSessionJson, project
 import { recordedConfigurationFold, recordedSessionConfiguration } from './session-recorded-config.mjs';
 import { claudeRuntimeFold } from './session-claude-runtime.mjs';
 import { withSessionRecords, sessionMetaFold } from './session-records.mjs';
+import { loadRecordedConfigurationRecords } from './session-config-scan.mjs';
 import { recordedLaunchAgent } from './session-launch-agent.mjs';
 import { recordedSessionUsage, sessionUsageFold } from './session-usage.mjs';
 import { loadMachineSpend } from './session-spend.mjs';
 import { sessionResumeLaunch } from './session-resume-instructions.mjs';
+export { importSessionDocument } from './session-import.mjs';
+export { branchSession, handoffSession } from './session-branch-handoff.mjs';
+export { materializeSession } from './session-materialize.mjs';
+export { transferSession } from './session-transfer.mjs';
+export { supportRegistryReport } from './support-report.mjs';
+export { loadHarnessSettings } from './harness-settings.mjs';
+export { listInstalledSkills } from './skills-list.mjs';
+export { mutateInstalledSkill } from './skills-control.mjs';
+export { showMemory } from './memory-show.mjs';
+export { listRuns, getRun } from './runs-read.mjs';
+export { listJobs, getJob } from './jobs-read.mjs';
+export { mutateJob, mutateJobNotepad, CONTROLLED_JOB_HARNESSES } from './jobs-control.mjs';
+export { listTriggers } from './triggers-read.mjs';
+export { listChannels, channelStatus } from './channels-read.mjs';
+export { loadWorkflow } from './workflow-read.mjs';
+export { listRoutes } from './routes-read.mjs';
+export { readJobNotepad } from './job-notepad-read.mjs';
+export { listProfiles, getProfile } from './profiles-read.mjs';
+export { mutateProfile } from './profiles-control.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', 'harness.v1.sessions.spend', 'harness.v1.sessions.resume_instructions']);
+export const SESSION_READ_METHODS = Object.freeze(['harness.v1.workflow.load', 'harness.v1.channels.list', 'harness.v1.channels.status', 'harness.v1.triggers.list', 'harness.v1.routes.list', 'harness.v1.jobs.list', 'harness.v1.jobs.get', 'harness.v1.jobs.create', 'harness.v1.jobs.update', 'harness.v1.jobs.pause', 'harness.v1.jobs.resume', 'harness.v1.jobs.run', 'harness.v1.jobs.delete', 'harness.v1.jobs.notepad_set', 'harness.v1.jobs.notepad_delete', 'harness.v1.runs.list', 'harness.v1.runs.get', 'harness.v1.jobs.notepad', 'harness.v1.memory.show', 'harness.v1.profiles.list', 'harness.v1.profiles.get', 'harness.v1.profiles.create', 'harness.v1.profiles.delete', 'harness.v1.skills.list', 'harness.v1.skills.install', 'harness.v1.skills.remove', 'harness.v1.harnesses.settings', 'harness.v1.support.report', 'harness.v1.sessions.import', 'harness.v1.sessions.export', 'harness.v1.sessions.translate', 'harness.v1.sessions.branch', 'harness.v1.sessions.handoff', 'harness.v1.sessions.materialize', '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', 'harness.v1.sessions.tree', 'harness.v1.sessions.activity_under', 'harness.v1.sessions.history', 'harness.v1.sessions.activity.subscribe', 'harness.v1.sessions.activity.unsubscribe', 'harness.v1.sessions.inbox', 'harness.v1.sessions.message']);
 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, spend: true, resume_instructions: 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, tree: true, activity_under: true, history: true, activity: true, inbox: true, message: true, import: true, export: true, translate: true, branch: true, handoff: true, materialize: true, support: true, settings: true, skills: true, skills_control: true, profiles: true, profiles_control: true, memory_show: true, job_notepad: true, runs: true, jobs: true, jobs_control: true, routes: true, triggers: true, channels: true, workflow: true });
+export const SESSION_READ_OPERATIONS = Object.freeze(['export', 'skills_list', 'skills_install', 'skills_remove', 'profiles_list', 'profiles_get', 'profiles_create', 'profiles_delete', 'jobs_notepad', 'runs_list', 'runs_get', 'jobs_list', 'jobs_get', 'jobs_create', 'jobs_update', 'jobs_pause', 'jobs_resume', 'jobs_run', 'jobs_delete', 'jobs_notepad_set', 'jobs_notepad_delete', 'routes_list', 'triggers_list', 'channels_list', 'channels_status', 'workflow_load']);
 export { loadMachineSpend as loadSessionSpend };
+export { parseSessionMessageParams, sessionMessageInboundControls } from './session-message.mjs';
+export { nativeInteger as sessionWireInteger };
 export { parseNativeJson as parseSessionWire, stringifyNativeJson as stringifySessionWire };
+/** Rebuild a reply without rounding the caller's native numeric ID. */
+export function sessionWireReply(request, answer) {
+  const id = request != null && typeof request === 'object'
+    ? stringifyNativeJsonMember(request, 'id') : undefined;
+  const reply = parseNativeJson(`{"jsonrpc":"2.0","id":${id ?? 'null'}}`);
+  for (const key of Object.keys(answer)) if (key !== 'id' && key !== 'jsonrpc') reply[key] = answer[key];
+  return reply;
+}
 export { SESSION_UNREADABLE } from './session-file.mjs';
 export { stringifyNativeJsonPretty as prettySessionWire };
 const invalid = (message) => { throw Object.assign(new Error(message), { rpcCode: -32602 }); };
@@ -45,6 +78,18 @@ function unsigned(parent, key, maximum = Number.MAX_SAFE_INTEGER) {
   return Math.min(parent[key], maximum);
 }
 
+/** The marks a windowed read's caller holds, named as their chain (loadClaudeRecordWindow, loadCodexRecordWindow):
+ * their count, the digest of the chain through them and the digest at each MARK_CHECKPOINT-th of them. */
+function knownMarks(value) {
+  if (value == null) return null;
+  object(value, 'view.known_marks');
+  const count = unsigned(value, 'count'), digest = value.digest, checkpoints = value.checkpoints;
+  if (count == null) invalid('known_marks.count must be an unsigned 64-bit integer');
+  string(digest, 'known_marks.digest');
+  if (!Array.isArray(checkpoints) || checkpoints.length !== Math.floor(count / MARK_CHECKPOINT) || checkpoints.some((each) => typeof each !== 'string')) invalid('known_marks.checkpoints must be the chain digest at each MARK_CHECKPOINT-th mark');
+  return { count, digest, checkpoints };
+}
+
 export function parseSessionReadParams(params, { cwd = process.cwd() } = {}) {
   object(params, 'session read params'); const supplied = object(params.locator, 'locator'), storage = object(supplied.storage, 'locator.storage');
   string(supplied.harness, 'locator.harness'); // HarnessId is extensible, including third-party names.
@@ -60,7 +105,8 @@ export function parseSessionReadParams(params, { cwd = process.cwd() } = {}) {
     view = { includeSubagents: boolean(suppliedView, 'include_subagents', false), displayHistory: boolean(suppliedView, 'display_history', false),
       messageLimit: unsigned(suppliedView, 'tail_messages', 5000), maxMessageChars: unsigned(suppliedView, 'max_message_chars', 64000),
       fromByte: unsigned(suppliedView, 'from_byte'), fromMessage: unsigned(suppliedView, 'from_message'),
-      windowBytes: unsigned(suppliedView, 'window_bytes'), windowMessages: unsigned(suppliedView, 'window_messages'), marks: boolean(suppliedView, 'marks', false) };
+      windowBytes: unsigned(suppliedView, 'window_bytes'), windowMessages: unsigned(suppliedView, 'window_messages'), marks: boolean(suppliedView, 'marks', false),
+      knownMarks: knownMarks(suppliedView.known_marks) };
     if (view.messageLimit != null) view.messageLimit = Math.max(1, view.messageLimit);
     if (view.maxMessageChars != null) view.maxMessageChars = Math.max(256, view.maxMessageChars);
   }
@@ -101,12 +147,12 @@ export async function loadSessionRead(params, context = {}) {
   const readOptions = { ...context, fidelity, includeSubagents: view?.includeSubagents ?? true };
   // A view from a message on is a window of the session read record by record, where its reader has one.
   if (view?.fromMessage != null && !view.includeSubagents && !view.displayHistory) {
-    const windowed = await loadClaudeRecordWindow(locator, { from: view.fromMessage, bytes: view.windowBytes, messages: view.windowMessages, marks: view.marks }, readOptions);
+    const windowed = await loadClaudeRecordWindow(locator, { from: view.fromMessage, bytes: view.windowBytes, messages: view.windowMessages, marks: view.marks, known: view.knownMarks }, readOptions);
     if (windowed != null) return windowed;
   }
   // So is a view from a message on of a Codex rollout's display history read from an anchor.
   if (view?.fromMessage != null && !view.includeSubagents && view.displayHistory && view.fromByte != null) {
-    const windowed = await loadCodexRecordWindow(locator, view.fromByte, { from: view.fromMessage, bytes: view.windowBytes, messages: view.windowMessages, marks: view.marks }, readOptions);
+    const windowed = await loadCodexRecordWindow(locator, view.fromByte, { from: view.fromMessage, bytes: view.windowBytes, messages: view.windowMessages, marks: view.marks, known: view.knownMarks }, readOptions);
     if (windowed != null) return windowed;
   }
   const session = view?.displayHistory
@@ -114,8 +160,37 @@ export async function loadSessionRead(params, context = {}) {
       : await loadSessionDisplayLocator(locator, view.messageLimit ?? 500, readOptions)
     : await loadSessionLocator(locator, readOptions);
   if (view?.fromByte == null) boundSessionView(session, view?.messageLimit, view?.maxMessageChars);
+  // A view is a window of the transcript; its background agents are of the whole file (a launch long before it,
+  // or before a compaction, included). Only a Claude Code transcript records them.
+  const backgroundAgents = locator.harness === 'claude-code' ? await loadClaudeBackgroundAgents(locator, readOptions).catch(() => null) : null;
   return { session: { ...normalizedSessionJson(session), resolved_profile: recordedSessionProfile(session),
-    resolved_profile_history: recordedSessionProfileHistory(session) } };
+    resolved_profile_history: recordedSessionProfileHistory(session), ...(backgroundAgents ? { background_agents: backgroundAgents } : {}) } };
+}
+/** The most messages one history page holds (harness.v1.sessions.history), and the most transcript it reads them from. */
+export const SESSION_HISTORY_MESSAGES = 200, SESSION_HISTORY_BYTES = 8 * 1024 * 1024;
+/**
+ * A page of a session's history read with every segment before its compactions (`harness.v1.sessions.history`):
+ * `{ locator, before, messages, bytes }`, the messages before the place `before` of that read, or, with `before` null,
+ * before where a read from the latest compaction on begins (loadClaudeHistoryWindow). Answers the page as a window read
+ * does (`session.messages`, `window.offset`, `window.segment_start`, `window.reading` while its transcript is still being
+ * read through); a session whose reader keeps no such history (any but a Claude Code transcript) answers
+ * `{ session: null, window: null, unsupported }`.
+ */
+export async function loadSessionHistory(params, context = {}) {
+  object(params, 'session history params');
+  const { locator } = parseSessionReadParams({ locator: params.locator }, context);
+  const before = unsigned(params, 'before'), messages = unsigned(params, 'messages', SESSION_HISTORY_MESSAGES) ?? 50;
+  const bytes = unsigned(params, 'bytes', SESSION_HISTORY_BYTES) ?? SESSION_HISTORY_BYTES, textUnits = unsigned(params, 'text_units');
+  const page = await loadClaudeHistoryWindow(locator, { before, messages: Math.max(1, messages), bytes }, context);
+  if (page == null) return { session: null, window: null, unsupported: 'only a Claude Code transcript keeps its history before a compaction apart from its capture' };
+  // `text_units`: each string of the page cut to that many UTF-16 units here, in the reading worker, so what its asker
+  // takes over is bounded whatever a message holds
+  if (textUnits != null && page.session.messages) {
+    const cut = (value) => typeof value === 'string' ? (value.length > textUnits ? `${value.slice(0, textUnits)}… (shortened)` : value)
+      : Array.isArray(value) ? value.map(cut) : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).map(([key, item]) => [key, cut(item)])) : value;
+    page.session.messages = page.session.messages.map(cut);
+  }
+  return page;
 }
 export async function openSessionReadFollower(params, context = {}) {
   object(params, 'session read params');
@@ -131,6 +206,8 @@ export async function loadRecordedSessionConfiguration(params, context = {}) {
   // LocatorParams ignores unrelated fields. This door always reads the full
   // lossless source, independent of any supplied display/load-view knobs.
   const { locator } = parseSessionReadParams({ locator: params.locator }, context);
+  const indexed = await loadRecordedConfigurationRecords(locator, context);
+  if (indexed != null) return indexed;
   const folded = await withSessionRecords(locator, async (source, records) => {
     const fold = recordedConfigurationFold(), meta = sessionMetaFold(source, fold);
     // The runtime fold takes every record's calls before any record: the file is read once more for it.

package/session-recorded-config.mjs

@@ -7,10 +7,11 @@ import { claudeRuntimeManifest } from './session-claude-runtime.mjs';
 const HEADER_KEYS = ['cwd', 'model', 'approval_policy', 'sandbox_policy'];
 
 /** Codex headers in recorded order, the last value of each key standing. */
-export function recordedConfigurationFold() {
-  let recorded = new Map();
+export function recordedConfigurationFold(saved = null) {
+  let recorded = new Map(saved ?? []);
   return {
     clear() { recorded = new Map(); },
+    clone() { return recordedConfigurationFold(recorded); },
     header(header) {
       const payload = field(header, 'payload') === undefined ? header : header.payload;
       for (const key of HEADER_KEYS) if (field(payload, key) !== undefined) recorded.set(key, stringifyNativeJsonMember(payload, key));

package/session-records.mjs

@@ -6,7 +6,7 @@ import { basename, dirname, extname, join } from 'node:path';
 import { withSessionFile } from './file-io.mjs';
 import { sourceStat } from './store-registry.mjs';
 import { sessionFileLines } from './session-file.mjs';
-import { parseNativeJson } from './native-json.mjs';
+import { cloneNativeJson, parseNativeJson } from './native-json.mjs';
 import { nativeTrim } from './text.mjs';
 import { field, stringField } from './session-codec-utils.mjs';
 import { createSession } from './session-model.mjs';
@@ -50,14 +50,19 @@ async function* records(reader) {
 
 /** `work(source, records)` over the transcript a locator names, or null when
  * it is not a plain Claude Code or Codex JSONL file. */
-export async function withSessionRecords(locator, work, { metrics } = {}) {
+export async function withSessionRecords(locator, work, context = {}) {
+  return withSessionRecordFile(locator, (source, reader) => work(source, () => records(reader)), context);
+}
+
+/** The verified open snapshot for an append-aware record fold. */
+export async function withSessionRecordFile(locator, work, { metrics } = {}) {
   const { path, kind } = locator.storage;
   if (kind !== 'file' || locator.harness === 'hermes' || isCompressedSessionPath(path)) return null;
   if ((await sourceStat(join(dirname(path), `${basename(path, extname(path))}.meta.json`)))?.isFile()) return null;
   if (!(await sourceStat(path))?.isFile() || await looksLikeSessionSqlite(path, metrics)) return null;
   return (await withSessionFile(path, async (reader) => {
     const source = await recordedSource(reader);
-    return ['claude_code', 'codex'].includes(source) ? { result: await work(source, () => records(reader)) } : null;
+    return ['claude_code', 'codex'].includes(source) ? { result: await work(source, reader) } : null;
   }, metrics)).result;
 }
 
@@ -65,15 +70,16 @@ export async function withSessionRecords(locator, work, { metrics } = {}) {
  * in the same order. `headers` takes each Codex header as it stands, and is
  * cleared when a restored provenance (in a record of either dialect)
  * replaces those read before it. */
-export function sessionMetaFold(source, headers = null) {
-  const { meta } = createSession(source);
-  let restored = false, held = meta.codex_headers;
+export function sessionMetaFold(source, headers = null, saved = null) {
+  const meta = saved?.meta ?? createSession(source).meta;
+  let restored = saved?.restored ?? false, held = meta.codex_headers;
   const replaced = () => {
     if (meta.codex_headers === held) return;
     held = meta.codex_headers; headers?.clear(); for (const header of held) headers?.header(header);
   };
   return {
     meta,
+    clone(nextHeaders) { return sessionMetaFold(source, nextHeaders, { meta: cloneNativeJson(meta), restored }); },
     observe({ raw, value }) {
       if (source === 'claude_code') { if (value !== undefined) { captureClaudeMeta(value, meta, raw); replaced(); } return; }
       // The Codex codec parses its trimmed line.

package/session-residue-store.mjs

@@ -0,0 +1,90 @@
+// Best-effort cache only: validated restoration, never a second source of session truth.
+import { mkdir, readFile, writeFile, rename, readdir, stat, lstat, open, unlink, rmdir } from 'node:fs/promises';
+import { join, resolve, extname } from 'node:path';
+import { userInfo } from 'node:os';
+import { nativeDuplicateObjectKeys, parseNativeJson, stringifyNativeJson } from './native-json.mjs';
+import { decodeSessionUtf8 } from './session-file.mjs';
+import { RESIDUE_FORMAT_NAMES, residueSegments } from './session-residue.mjs';
+
+const DAY = 86_400_000, MAX_AGE = 90 * DAY, MAX_BYTES = 4n * 1024n * 1024n * 1024n;
+function cacheRoot({ env = process.env, cwd = process.cwd() } = {}) {
+  let home = env.HOME || (process.platform === 'win32' && env.USERPROFILE);
+  if (!home) try { home = userInfo().homedir || '.'; } catch { home = '.'; }
+  const instructions = env.SUPERCODE_HOME || (env.XDG_CONFIG_HOME ? join(env.XDG_CONFIG_HOME, 'supercode') : join(home, '.config', 'supercode'));
+  return resolve(cwd, instructions, 'residue');
+}
+function decodedSegment(text) {
+  const value = parseNativeJson(text);
+  if (value == null || typeof value !== 'object' || Array.isArray(value) || !Array.isArray(value.lines)
+    || !value.lines.every(line => typeof line === 'string') || typeof value.end_of_source !== 'boolean'
+    || typeof value.trailing_newline !== 'boolean') return null;
+  if (nativeDuplicateObjectKeys(value).some(key => ['lines', 'end_of_source', 'trailing_newline', 'digest', 'source', 'source_session'].includes(key))) return null;
+  for (const key of ['digest', 'source']) {
+    if (!Object.hasOwn(value, key)) value[key] = '';
+    if (typeof value[key] !== 'string') return null;
+  }
+  if (value.source_session == null) value.source_session = null;
+  if (value.source_session !== null && typeof value.source_session !== 'string') return null;
+  return value;
+}
+
+async function pruneIfDue(root) {
+  const marker = join(root, '.pruned'), now = Date.now();
+  let due; try { const at = (await stat(marker)).mtimeMs; due = at > now || now - at >= DAY; } catch { due = true; }
+  if (!due) return;
+  try { await mkdir(root, { recursive: true }); await writeFile(marker, ''); } catch { return; }
+  const pending = [root], dirs = [], segments = [];
+  while (pending.length) {
+    const directory = pending.pop(); let entries;
+    try { entries = await readdir(directory); } catch { continue; }
+    for (const name of entries) {
+      const path = join(directory, name); let metadata;
+      try { metadata = await lstat(path, { bigint: true }); } catch { continue; }
+      if (metadata.isDirectory()) { pending.push(path); dirs.push(path); }
+      else if (extname(path) === '.json') segments.push({ path, bytes: metadata.size, modified: metadata.mtimeNs });
+    }
+  }
+  segments.sort((a, b) => a.modified < b.modified ? -1 : a.modified > b.modified ? 1 : 0);
+  let total = segments.reduce((sum, entry) => sum + entry.bytes, 0n);
+  const wall = BigInt(Date.now()) * 1_000_000n;
+  for (const segment of segments) {
+    const stale = wall >= segment.modified && wall - segment.modified > BigInt(MAX_AGE) * 1_000_000n;
+    if (!stale && total <= MAX_BYTES) break;
+    try { await unlink(segment.path); total -= segment.bytes; } catch { /* A failed prune leaves the cache intact. */ }
+  }
+  dirs.sort((a, b) => b.split(/[\\/]/u).length - a.split(/[\\/]/u).length);
+  for (const path of dirs) try { await rmdir(path); } catch { /* Only empty directories can be removed. */ }
+}
+
+export function createResidueStore(context = {}) {
+  const root = cacheRoot(context);
+  const directory = (format, key) => join(root, RESIDUE_FORMAT_NAMES[format].toLowerCase(), key.slice(0, 2) || '00', key);
+  return {
+    async store(session) {
+      const segments = residueSegments(session); if (!segments.length) return;
+      await pruneIfDue(root);
+      for (const keyed of segments) {
+        const parent = directory(keyed.format, keyed.key), path = join(parent, `${keyed.segment.source}.json`);
+        try { await stat(path); continue; } catch { /* Missing or unreadable path: attempt the native best-effort write. */ }
+        try {
+          await mkdir(parent, { recursive: true }); await writeFile(path + '.tmp', stringifyNativeJson(keyed.segment)); await rename(path + '.tmp', path);
+        } catch { /* A failed cache write does not prevent translation. */ }
+      }
+    },
+    async lookup(format, key) {
+      const parent = directory(format, key), segments = []; let entries;
+      try { entries = await readdir(parent); } catch { return segments; }
+      for (const name of entries) {
+        const path = join(parent, name); if (extname(path) !== '.json') continue;
+        let segment; try { segment = decodedSegment(decodeSessionUtf8(await readFile(path))); } catch { continue; }
+        if (segment == null) continue;
+        let handle;
+        try { handle = await open(path, 'r+'); const metadata = await handle.stat(); await handle.utimes(metadata.atime, new Date()); }
+        catch { /* Read-only cache entries remain usable without an mtime refresh. */ }
+        finally { if (handle != null) await handle.close().catch(() => {}); }
+        segments.push(segment);
+      }
+      return segments;
+    },
+  };
+}

package/session-residue.mjs

@@ -0,0 +1,150 @@
+// Portable source segments complement a target projection; cached bytes are never trusted alone.
+import { blake3 } from '@noble/hashes/blake3.js';
+import { cloneNativeJson, stringifyNativeJson } from './native-json.mjs';
+import { SESSION_FORMATS } from './session-model.mjs';
+import { readSessionDocument } from './session-document.mjs';
+import { toSessionJsonlSpliced } from './session-write.mjs';
+import { parsedJsonField } from './session-write-utils.mjs';
+
+export const RESIDUE_FORMAT_NAMES = Object.freeze({ claude_code: 'ClaudeCode', codex: 'Codex', opencode: 'OpenCode',
+  pi: 'Pi', grok: 'Grok', gemini: 'Gemini', goose: 'Goose' });
+const hash = buffers => Buffer.from(blake3(Buffer.concat(buffers))).toString('hex');
+const emptyKey = () => hash([Buffer.from('supercode-residue-v1')]);
+function groups(messages) {
+  const result = [];
+  for (const [index, message] of messages.entries()) {
+    if (message.role === 'tool' && result.length) result[result.length - 1].end = index + 1;
+    else result.push({ start: index, end: index + 1 });
+  }
+  return result;
+}
+function messageText(message) {
+  return message.content_parts == null ? message.content ?? '' : message.content_parts
+    .filter(part => part?.type === 'text' && typeof part?.text === 'string').map(part => part.text).join('');
+}
+function canonicalGroup(messages) {
+  const head = messages[0], calls = head.tool_calls ?? [];
+  const callPosition = result => { const index = calls.findIndex(call => call.id === result.tool_call_id); return index < 0 ? Infinity : index; };
+  const results = messages.slice(1).sort((left, right) => callPosition(left) - callPosition(right));
+  return [head.role, messageText(head), calls.map(call => {
+    const value = [call.function.name, null]; parsedJsonField(value, '1', call.function.arguments); return value;
+  }), results.map(messageText)];
+}
+
+export function residueChainKeys(messages) {
+  let previous = emptyKey();
+  return groups(messages).map(group => {
+    previous = hash([Buffer.from(previous), Buffer.from(stringifyNativeJson(canonicalGroup(messages.slice(group.start, group.end))))]);
+    return { group, key: previous };
+  });
+}
+
+export function segmentDigest(lines) {
+  const buffers = [];
+  for (const line of lines) {
+    const bytes = Buffer.from(line), length = Buffer.alloc(8); length.writeBigUInt64LE(BigInt(bytes.length));
+    buffers.push(length, bytes);
+  }
+  return hash(buffers);
+}
+export const verifiedSegment = segment => segment.digest === segmentDigest(segment.lines);
+function segment(lines, end, trailing, source, sessionId) {
+  return { lines, end_of_source: end, trailing_newline: trailing, digest: segmentDigest(lines), source, source_session: sessionId };
+}
+
+export function residueSegments(session) {
+  const format = session.meta.source;
+  if (!SESSION_FORMATS.includes(format) || !session.raw_is_verbatim || session.meta.message_records.length !== session.messages.length) return [];
+  const keyed = residueChainKeys(session.messages);
+  const source = hash([Buffer.from(RESIDUE_FORMAT_NAMES[format]), Buffer.from(session.meta.session_id ?? ''), Buffer.from(session.raw[0] ?? '')]);
+  const keyedSegment = (key, lines, end) => ({ key, format,
+    segment: segment(lines, end, session.raw_trailing_newline, source, session.meta.session_id) });
+  if (!keyed.length) return session.raw.length ? [keyedSegment(emptyKey(), [...session.raw], true)] : [];
+  const starts = [];
+  for (const { group } of keyed) {
+    const record = session.meta.message_records[group.start]; if (record == null) break;
+    starts.push(BigInt(record));
+  }
+  const segments = [];
+  for (let index = 0; index < starts.length; index++) {
+    const from = index ? starts[index] : 0n, end = index + 1 === keyed.length;
+    const to = end ? BigInt(session.raw.length) : starts[index + 1] ?? BigInt(session.raw.length);
+    if (from > to || to > BigInt(session.raw.length)) break;
+    segments.push(keyedSegment(keyed[index].key, session.raw.slice(Number(from), Number(to)), end));
+  }
+  return segments;
+}
+
+async function residueSource(session, format, lookup, keyed) {
+  const own = session.meta.session_id, recorded = session.meta.source === 'grok' ? null : own;
+  const candidates = (await lookup(format, keyed[0].key)).filter(verifiedSegment)
+    .filter(candidate => recorded == null || candidate.source_session == null || candidate.source_session === recorded);
+  let best = [];
+  for (const candidate of candidates) {
+    let matched = 0; const lines = [];
+    for (const { key } of keyed) {
+      const found = (await lookup(format, key)).find(segment => segment.source === candidate.source && verifiedSegment(segment));
+      if (found == null) break;
+      matched++; lines.push(...found.lines); if (found.end_of_source) break;
+    }
+    best.push({ source: candidate.source, session: candidate.source_session, matched, lines });
+  }
+  if (!best.length) return null;
+  const longest = Math.max(...best.map(candidate => candidate.matched)); best = best.filter(candidate => candidate.matched === longest);
+  if (best.length > 1 && own != null && best.some(candidate => candidate.session === own)) best = best.filter(candidate => candidate.session === own);
+  const first = best[0];
+  return best.every(candidate => candidate.lines.length === first.lines.length && candidate.lines.every((line, index) => line === first.lines[index]))
+    ? first.source : null;
+}
+
+async function restoreEmpty(session, format, lookup) {
+  let candidates = (await lookup(format, emptyKey())).filter(verifiedSegment);
+  if (candidates.length > 1 && session.meta.session_id != null) candidates = candidates.filter(segment => segment.source_session === session.meta.session_id);
+  if (candidates.length !== 1) return null;
+  const segment = candidates[0], text = segment.lines.join('\n') + (segment.trailing_newline ? '\n' : '');
+  let written; try { written = readSessionDocument(text, { source: format }); } catch { return null; }
+  return written.messages.length ? null : { content: text, report: { restored_messages: 0, rendered_messages: 0 } };
+}
+
+async function restorePrefix(session, format, lookup, keyed, limit) {
+  const lines = []; let restoredGroups = 0, restoredMessages = 0, whole = null;
+  for (const { group, key } of keyed.slice(0, limit)) {
+    const segment = await lookup(format, key); if (segment == null) break;
+    lines.push(...segment.lines); restoredGroups++; restoredMessages = group.end;
+    if (segment.end_of_source) { whole = segment.trailing_newline; break; }
+  }
+  if (!restoredGroups) return { kind: 'nothing' };
+  const report = { restored_messages: restoredMessages, rendered_messages: session.messages.length - restoredMessages };
+  let content;
+  if (whole != null && !report.rendered_messages) content = lines.join('\n') + (whole ? '\n' : '');
+  else {
+    const spliced = cloneNativeJson(session); spliced.meta.source = format;
+    spliced.raw = [...lines, ...Array(report.rendered_messages).fill('')]; spliced.raw_is_verbatim = true;
+    spliced.imported_message_count = restoredMessages; content = toSessionJsonlSpliced(spliced, format);
+  }
+  let actual;
+  try { actual = residueChainKeys(readSessionDocument(content, { source: format }).messages); }
+  catch { return { kind: 'unsound', firstMismatch: 0, restoredGroups }; }
+  const shorter = Math.min(actual.length, keyed.length);
+  let mismatch = 0; while (mismatch < shorter && actual[mismatch].key === keyed[mismatch].key) mismatch++;
+  if (mismatch < keyed.length || actual.length !== keyed.length) return { kind: 'unsound', firstMismatch: mismatch, restoredGroups };
+  return { kind: 'sound', content, report };
+}
+
+/** A cache miss, ambiguity or unsound prefix falls back to ordinary rendering. */
+export async function restoreResidue(session, format, lookup) {
+  if (!SESSION_FORMATS.includes(format)) throw new TypeError(`unknown session format: ${format}`);
+  const keyed = residueChainKeys(session.messages);
+  if (!keyed.length) return restoreEmpty(session, format, lookup);
+  const source = await residueSource(session, format, lookup, keyed); if (source == null) return null;
+  const selected = async (format, key) => (await lookup(format, key)).find(segment => segment.source === source && verifiedSegment(segment));
+  let limit = keyed.length;
+  for (;;) {
+    const result = await restorePrefix(session, format, selected, keyed, limit);
+    if (result.kind === 'sound') return { content: result.content, report: result.report };
+    if (result.kind === 'nothing') return null;
+    const shorter = Math.min(result.firstMismatch, Math.max(0, result.restoredGroups - 1));
+    if (!shorter || shorter >= limit) return null;
+    limit = shorter;
+  }
+}

package/session-resume-instructions.mjs

@@ -14,7 +14,7 @@ function startupArguments(harness, cwd, unattended) {
   return arguments_;
 }
 
-function grokHomeEnvironment(env, cwd) {
+export 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 {}; } }

package/session-saved-read.mjs

@@ -0,0 +1,105 @@
+// Read the native saved-session family. Individual active/archive fallback
+// deliberately matches SessionStore; this is not a store migration or writer.
+import { mkdir, readFile, readdir, stat } from 'node:fs/promises';
+import { isAbsolute, join, sep } from 'node:path';
+import { userInfo } from 'node:os';
+import { decodeSessionUtf8 } from './session-file.mjs';
+import { nativeDuplicateObjectKeys, nativeInteger, parseNativeJson } from './native-json.mjs';
+import { deserializeMessage } from './message.mjs';
+import { fromNativeMessages } from './session-native.mjs';
+import { nativeTrim } from './text.mjs';
+import { emptyReductionLog, readReductionLog, REDUCTION_SENTINEL } from './reduction-log.mjs';
+
+const lexicalJoin = (root, ...parts) => process.platform === 'win32' && /^[A-Za-z]:$/u.test(root) ? root + parts.join(sep) : join(root, ...parts);
+export function savedSessionRoot(env = process.env) {
+  if (env.SUPERCODE_HOME) return lexicalJoin(env.SUPERCODE_HOME, 'sessions');
+  if (env.XDG_CONFIG_HOME) return lexicalJoin(env.XDG_CONFIG_HOME, 'supercode', 'sessions');
+  let home = env.HOME || (process.platform === 'win32' && env.USERPROFILE);
+  if (!home) try { home = userInfo().homedir; } catch { home = '.'; }
+  return lexicalJoin(home, '.config', 'supercode', 'sessions');
+}
+export async function savedPathExists(path) { try { await stat(path); return true; } catch { return false; } }
+const textFile = async path => decodeSessionUtf8(await readFile(path));
+const byteOrder = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+function validateName(name) {
+  if (!name || /[/\\\0]/u.test(name) || ['.', '..'].includes(name) || isAbsolute(name) || nativeTrim(name) !== name) throw new Error(`invalid session name: \`${name}\``);
+}
+function metadataName(value) {
+  if (value == null || typeof value !== 'object' || Array.isArray(value) || typeof value.name !== 'string') return null;
+  const strings = ['name', 'title', 'tier'], booleans = ['archived', 'reduced'], integers = ['full_bytes', 'view_bytes', 'stub_count', 'escalations', 'format_version'];
+  for (const key of nativeDuplicateObjectKeys(value)) if ([...strings, ...booleans, ...integers].includes(key)) return null;
+  for (const key of strings) if (Object.hasOwn(value, key) && typeof value[key] !== 'string') return null;
+  for (const key of booleans) if (Object.hasOwn(value, key) && typeof value[key] !== 'boolean') return null;
+  for (const key of integers) if (Object.hasOwn(value, key)) {
+    const number = nativeInteger(value, key), max = ['stub_count', 'escalations', 'format_version'].includes(key) ? 0xffffffffn : (1n << 64n) - 1n;
+    if (number == null || number > max) return null;
+  }
+  return value.name;
+}
+
+export class SavedSessionReader {
+  constructor(root) { this.root = root; }
+  directory(archived) { return archived ? lexicalJoin(this.root, 'archived') : this.root; }
+  async resolve(query) {
+    // Native SessionStore::open creates its otherwise absent directory even
+    // for this name lookup; no family member is altered by the reader.
+    await mkdir(this.root, { recursive: true });
+    const names = [];
+    for (const archived of [false, true]) {
+      let entries; try { entries = await readdir(this.directory(archived)); } catch { continue; }
+      for (const file of entries) if (file.endsWith('.meta.json')) {
+        try { const name = metadataName(parseNativeJson(await textFile(lexicalJoin(this.directory(archived), file)))); if (name != null) names.push(name); } catch { /* native catalog skips unreadable/malformed metadata */ }
+      }
+    }
+    names.sort(byteOrder);
+    if (names.includes(query)) return query;
+    const matches = names.filter(name => name.includes(query));
+    if (matches.length === 1) return matches[0];
+    if (!matches.length) throw new Error(`no session matching \`${query}\``);
+    throw new Error(`\`${query}\` is ambiguous (${matches.length} matches)`);
+  }
+  async familyPath(name, suffix) {
+    validateName(name);
+    const active = lexicalJoin(this.directory(false), name + suffix);
+    return await savedPathExists(active) ? active : lexicalJoin(this.directory(true), name + suffix);
+  }
+  async read(name, suffix, optional = false) {
+    const path = await this.familyPath(name, suffix);
+    if (optional && !await savedPathExists(path)) return null;
+    return textFile(path);
+  }
+  async reductionLog(name) {
+    const text = await this.read(name, '.reduction.json', true);
+    if (text != null) return readReductionLog(text);
+    if ((await this.read(name, '.jsonl', true))?.includes(REDUCTION_SENTINEL)) throw new Error(`\`${name}\` has reduction stubs in its persisted working view, but its reduction log is missing — cannot safely interpret this reduced session; restore \`${name}.reduction.json\` or recreate the reduced session from its full sidecar/export`);
+    return emptyReductionLog();
+  }
+  async childIds(name) {
+    validateName(name); const ids = new Set();
+    for (const archived of [false, true]) {
+      let entries; try { entries = await readdir(lexicalJoin(this.directory(archived), `${name}.subagents`)); } catch { continue; }
+      for (const entry of entries) if (entry.endsWith('.sidecar.jsonl')) ids.add(entry.slice(0, -'.sidecar.jsonl'.length));
+    }
+    return [...ids].sort(byteOrder);
+  }
+  async child(name, id) {
+    validateName(id);
+    return this.read(name, `.subagents${sep}${id}.sidecar.jsonl`, true);
+  }
+}
+
+export function parseSavedMessages(name, text) {
+  const known = ['role', 'content', 'tool_calls', 'tool_call_id', 'name'];
+  try {
+    const messages = text.split('\n').filter(line => nativeTrim(line) !== '').map(line => {
+      const value = parseNativeJson(line);
+      for (const key of nativeDuplicateObjectKeys(value)) if (known.includes(key)) throw new Error(`duplicate field ${key}`);
+      for (const call of value?.tool_calls ?? []) {
+        for (const key of nativeDuplicateObjectKeys(call)) if (['id', 'type', 'function'].includes(key)) throw new Error(`duplicate tool-call field ${key}`);
+        for (const key of nativeDuplicateObjectKeys(call.function)) if (['name', 'arguments'].includes(key)) throw new Error(`duplicate function field ${key}`);
+      }
+      return deserializeMessage(value);
+    });
+    const session = fromNativeMessages(messages); session.meta.session_id = name; return session;
+  } catch (error) { throw new Error(`parsing stored session \`${name}\`: ${error.message}`, { cause: error }); }
+}