@volter/supercode-interchange 0.1.22 → 0.1.24

package/session-materialize.mjs

@@ -0,0 +1,186 @@
+// A continuation chooses a fresh native identity and destination cwd. Source
+// recovery is cached first; it is never installed as a vendor store file.
+import { join } from 'node:path';
+import { resolveHarnessHomes } from './homes.mjs';
+import { parseNativeJson, stringifyNativeJson, stringifyNativeJsonPretty, swapRemoveNativeJsonMember } from './native-json.mjs';
+import { nativeTrim } from './text.mjs';
+import { readSessionDocument } from './session-document.mjs';
+import { fromNativeStr } from './session-native.mjs';
+import { toSessionJsonlSpliced } from './session-write.mjs';
+import { createResidueStore } from './session-residue-store.mjs';
+import { materializeOpenCode } from './session-materialize-opencode.mjs';
+import { isObject, nativeJoin, operationPath, canonicalPath, safeArtifactPath, freshSessionId, writeExclusive, containedDirectory, samePath } from './session-materialize-files.mjs';
+
+const invalid = message => { throw Object.assign(new Error(message), { rpcCode: -32602 }); };
+const string = (value, name) => { if (typeof value !== 'string') invalid(`${name} must be a string`); return value; };
+const homesFields = ['claude_code', 'codex', 'pi', 'opencode', 'grok', 'gemini', 'goose', 'supercode', 'openclaw', 'hermes', 'orchestrator'];
+function struct(value, fields, name, minimum = fields.length) {
+  if (Array.isArray(value)) {
+    if (value.length < minimum || value.length > fields.length) invalid(`${name} positional fields require ${minimum} to ${fields.length} values`);
+    return Object.fromEntries(value.map((value, index) => [fields[index], value]));
+  }
+  if (!isObject(value)) invalid(`${name} must be an object`);
+  return value;
+}
+function fidelity(value) {
+  if (isObject(value)) {
+    const keys = Object.keys(value);
+    if (keys.length !== 1 || value[keys[0]] !== null) invalid('artifact.fidelity must be a fidelity variant');
+    value = keys[0];
+  }
+  if (!['semantic', 'value_lossless', 'byte_lossless'].includes(value)) invalid('artifact.fidelity must be a fidelity variant');
+  return value;
+}
+
+export function parseSessionMaterializeParams(params, { env = process.env } = {}) {
+  params = struct(params, ['artifact', 'cwd', 'homes'], 'materialize params', 2);
+  const supplied = struct(params.artifact, ['target_harness', 'session_id', 'content', 'files', 'fidelity'], 'artifact');
+  if (!Array.isArray(supplied.files)) invalid('artifact.files must be an array');
+  const artifact = { target_harness: string(supplied.target_harness, 'artifact.target_harness'),
+    session_id: supplied.session_id == null ? null : string(supplied.session_id, 'artifact.session_id'),
+    content: string(supplied.content, 'artifact.content'), files: supplied.files.map(value => {
+      const file = struct(value, ['path', 'content', 'role'], 'artifact file');
+      return { path: string(file.path, 'artifact file.path'), content: string(file.content, 'artifact file.content'), role: string(file.role, 'artifact file.role') };
+    }), fidelity: fidelity(supplied.fidelity) };
+  const homes = resolveHarnessHomes(env, { joinPath: nativeJoin });
+  if (Object.hasOwn(params, 'homes')) {
+    const suppliedHomes = struct(params.homes, homesFields, 'homes', 0);
+    for (const key of homesFields) if (Object.hasOwn(suppliedHomes, key)) homes[key] = string(suppliedHomes[key], `homes.${key}`);
+  }
+  return { artifact, cwd: string(params.cwd, 'cwd'), homes };
+}
+
+export async function validateMaterialization(artifact, cwd, harness, companions, context) {
+  if (artifact.fidelity === 'byte_lossless') throw new Error('fresh native identity materialization cannot meet byte_lossless fidelity');
+  const primary = artifact.files.filter(file => file.role === 'primary');
+  if (primary.length !== 1 || primary[0].content !== artifact.content) throw new Error('native artifact must contain one matching primary file');
+  if (artifact.files.some(file => !safeArtifactPath(file.path))) throw new Error('native artifact contains an unsafe relative filename');
+  const extra = artifact.files.find(file => file.role !== 'primary' && file.role !== 'source_recovery' && !companions.includes(file.path));
+  if (extra) throw new Error(`${harness} continuation does not carry the companion artifact ${extra.path}`);
+  context.signal?.throwIfAborted();
+  try { return await canonicalPath(operationPath(cwd, context.cwd)); }
+  catch (error) { throw new Error(`continuation cwd is unavailable: ${error.message}`, { cause: error }); }
+}
+
+function* lines(text) {
+  if (text === '') return;
+  const records = text.split('\n');
+  for (let index = 0; index < records.length; index++) {
+    if (index === records.length - 1 && records[index] === '') break;
+    const line = records[index];
+    yield index < records.length - 1 && line.endsWith('\r') ? line.slice(0, -1) : line;
+  }
+}
+function rewrittenRecords(session, format, id, name, rewrite) {
+  let text = '';
+  for (const line of lines(toSessionJsonlSpliced(session, format, id))) {
+    let value;
+    try { value = parseNativeJson(line); }
+    catch (error) { throw new Error(`invalid rewritten ${name} record: ${error.message}`, { cause: error }); }
+    rewrite(value); text += stringifyNativeJson(value) + '\n';
+  }
+  return text;
+}
+function loadedSession(artifact, source) {
+  const session = readSessionDocument(artifact.content, { source });
+  if (artifact.session_id != null && session.meta.session_id !== artifact.session_id) throw new Error('native artifact declared session identity does not match its content');
+  return session;
+}
+const fileLocator = (harness, session_id, path) => ({ harness, session_id, storage: { kind: 'file', path } });
+
+async function materializeFile(artifact, cwd, homes, context) {
+  const { signal } = context, harness = artifact.target_harness;
+  const names = { 'claude-code': 'Claude', codex: 'Codex', pi: 'Pi' }, name = names[harness];
+  const destination = await validateMaterialization(artifact, cwd, name, [], context);
+  const source = harness === 'claude-code' ? 'claude_code' : harness;
+  const session = loadedSession(artifact, source), id = freshSessionId();
+  const text = rewrittenRecords(session, source, id, name, value => {
+    if (!isObject(value)) return;
+    if (harness === 'claude-code' || harness === 'pi' && value.type === 'session') value.cwd = destination;
+    if (harness === 'codex' && ['session_meta', 'turn_context'].includes(value.type) && isObject(value.payload) && Object.hasOwn(value.payload, 'cwd')) value.payload.cwd = destination;
+  });
+  const home = operationPath(homes[source], context.cwd);
+  let directory, filename;
+  if (harness === 'claude-code') {
+    const project = [...destination].map(character => /^[A-Za-z0-9]$/u.test(character) ? character : '-').join('');
+    directory = await containedDirectory(home, [project], signal, true); filename = `${id}.jsonl`;
+  } else if (harness === 'codex') {
+    const now = new Date().toISOString();
+    directory = await containedDirectory(home, [now.slice(0, 4), now.slice(5, 7), now.slice(8, 10)], signal);
+    filename = `rollout-${now.slice(0, 19).replace(/:/gu, '-')}-${id}.jsonl`;
+  } else {
+    const selected = context.env.PI_CODING_AGENT_SESSION_DIR;
+    const flat = selected != null && selected !== '' && await samePath(selected, homes.pi, context.cwd);
+    const folder = `--${destination.replace(/^[\/\\]/u, '').replace(/[\/\\:]/gu, '-')}--`;
+    directory = await containedDirectory(home, flat ? [] : [folder], signal);
+    filename = `${new Date().toISOString().replace(/[:.]/gu, '-')}_${id}.jsonl`;
+  }
+  const path = join(directory, filename); await writeExclusive(path, text, signal);
+  return fileLocator(harness, id, path);
+}
+
+function grokWorkspace(cwd) {
+  return [...Buffer.from(cwd)].map(byte => /[A-Za-z0-9._~-]/u.test(String.fromCharCode(byte)) ? String.fromCharCode(byte) : `%${byte.toString(16).toUpperCase().padStart(2, '0')}`).join('');
+}
+async function materializeGrok(artifact, cwd, homes, context) {
+  const destination = await validateMaterialization(artifact, cwd, 'Grok', ['summary.json', 'updates.jsonl'], context);
+  const session = readSessionDocument(artifact.content, { source: 'grok' });
+  const companion = path => artifact.files.find(file => file.role !== 'primary' && file.path === path)?.content;
+  const summaryText = companion('summary.json'); let summary;
+  try { summary = summaryText == null ? {} : parseNativeJson(summaryText); }
+  catch (error) { throw new Error(`invalid Grok summary.json: ${error.message}`, { cause: error }); }
+  const sourceId = typeof summary?.info?.id === 'string' ? summary.info.id : null;
+  if (artifact.session_id != null && sourceId != null && artifact.session_id !== sourceId) throw new Error('native artifact declared session identity does not match its content');
+  const model = typeof summary?.current_model_id === 'string' ? summary.current_model_id : session.meta.model ?? '';
+  const id = freshSessionId(), now = new Date().toISOString();
+  const transcript = toSessionJsonlSpliced(session, 'grok', id);
+  summary = isObject(summary) ? summary : {};
+  for (const key of ['agent_id', 'attempt_id', 'request_id', 'grok_home', 'sandbox_profile']) swapRemoveNativeJsonMember(summary, key);
+  summary.info = { id, cwd: destination };
+  if (!Object.hasOwn(summary, 'session_summary')) summary.session_summary = '';
+  if (!Object.hasOwn(summary, 'created_at')) summary.created_at = now;
+  summary.updated_at = now;
+  if (!Object.hasOwn(summary, 'num_messages')) summary.num_messages = session.messages.length;
+  summary.current_model_id = model;
+  const directory = await containedDirectory(operationPath(homes.grok, context.cwd), [grokWorkspace(destination), id], context.signal);
+  const path = join(directory, 'chat_history.jsonl');
+  await writeExclusive(path, transcript, context.signal);
+  await writeExclusive(join(directory, 'summary.json'), stringifyNativeJsonPretty(summary), context.signal);
+  const updates = companion('updates.jsonl');
+  if (updates != null && sourceId != null) {
+    let rewritten = '';
+    for (const line of lines(updates)) {
+      if (nativeTrim(line) === '') continue;
+      let record;
+      try { record = parseNativeJson(line); }
+      catch (error) { throw new Error(`invalid Grok updates record: ${error.message}`, { cause: error }); }
+      if (isObject(record?.params)) {
+        if (record.params.sessionId === sourceId) record.params.sessionId = id;
+        if (isObject(record.params._meta) && typeof record.params._meta.eventId === 'string' && record.params._meta.eventId.startsWith(sourceId)) record.params._meta.eventId = id + record.params._meta.eventId.slice(sourceId.length);
+      }
+      rewritten += stringifyNativeJson(record) + '\n';
+    }
+    await writeExclusive(join(directory, 'updates.jsonl'), rewritten, context.signal);
+  }
+  return fileLocator('grok', id, path);
+}
+
+export async function materializeSession(params, { cwd = process.cwd(), env = process.env, signal } = {}) {
+  signal?.throwIfAborted();
+  const context = { cwd, env, signal }, parsed = parseSessionMaterializeParams(params, context);
+  const store = createResidueStore(context);
+  for (const file of parsed.artifact.files) {
+    if (file.role !== 'source_recovery' || file.path !== 'recovery/source.supercode.jsonl') continue;
+    let source; try { source = fromNativeStr(file.content); } catch { continue; }
+    await store.store(source);
+  }
+  signal?.throwIfAborted();
+  const harness = parsed.artifact.target_harness;
+  if (['claude-code', 'codex', 'pi'].includes(harness)) return { locator: await materializeFile(parsed.artifact, parsed.cwd, parsed.homes, context) };
+  if (harness === 'grok') return { locator: await materializeGrok(parsed.artifact, parsed.cwd, parsed.homes, context) };
+  if (harness === 'opencode') {
+    const destination = await validateMaterialization(parsed.artifact, parsed.cwd, 'OpenCode', [], context);
+    return { locator: await materializeOpenCode(parsed.artifact, destination, parsed.homes.opencode, context) };
+  }
+  throw new Error('native materialization is not yet supported for this harness');
+}

package/session-message.mjs

@@ -0,0 +1,85 @@
+// Public message admission and the user-level Claude inbound report. This
+// reads settings only; delivery and policy changes retain their own owners.
+import { readFileSync } from 'node:fs';
+import { dirname, parse, sep } from 'node:path';
+import { blake3 } from '@noble/hashes/blake3.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
+import { resolveHarnessHomes } from './homes.mjs';
+import { parseNativeJson, stringifyNativeJsonMember } from './native-json.mjs';
+import { treeSelectedPath } from './session-machine-tree.mjs';
+
+const invalid = message => { throw Object.assign(new Error(message), { rpcCode: -32602 }); };
+const fields = ['locator', 'text', 'subject', 'idempotency_key', 'channel', 'from_name', 'voice_for', 'sender_name', 'in_reply_to', 'marker', 'reply_marker', 'surface', 'notify_when_idle', 'as_user', 'homes'];
+function struct(value, keys, name) {
+  if (value == null || typeof value !== 'object') invalid(`${name} must be a struct`);
+  if (!Array.isArray(value)) return value;
+  if (value.length > keys.length) invalid(`too many ${name} fields`);
+  return Object.fromEntries(value.map((item, at) => [keys[at], item]));
+}
+const string = (value, name) => { if (typeof value !== 'string') invalid(`${name} must be a string`); };
+// Rust char::is_whitespace follows Unicode White_Space, which differs from
+// JavaScript's \s for U+0085 and U+FEFF.
+const whitespace = /[\u0009-\u000d\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]/u;
+function address(value) {
+  string(value, 'voice_for');
+  if (!/^sc:[A-Za-z0-9._-]+:[A-Za-z0-9._-]+:.+$/su.test(value) || whitespace.test(value)) invalid('voice_for must be a session address');
+}
+export function parseSessionMessageParams(params, { env = process.env } = {}) {
+  const decoded = struct(params, fields, 'message params');
+  const target = struct(decoded.locator, ['harness', 'session_id', 'storage'], 'locator');
+  string(target.harness, 'locator.harness'); string(target.session_id, 'locator.session_id'); string(decoded.text, 'text');
+  if (target.storage != null) {
+    if (typeof target.storage !== 'object' || Array.isArray(target.storage)) invalid('locator.storage must be an object');
+    if (!['file', 'sqlite'].includes(target.storage.kind)) invalid('locator.storage.kind must be file or sqlite');
+    string(target.storage.path, 'locator.storage.path');
+    if (target.storage.kind === 'sqlite') string(target.storage.selector, 'locator.storage.selector');
+  }
+  for (const key of ['subject', 'idempotency_key', 'from_name', 'sender_name', 'in_reply_to', 'marker', 'reply_marker', 'surface']) if (decoded[key] != null) string(decoded[key], key);
+  if (decoded.voice_for != null) address(decoded.voice_for);
+  for (const key of ['channel', 'notify_when_idle', 'as_user']) if (Object.hasOwn(decoded, key) && typeof decoded[key] !== 'boolean') invalid(`${key} must be a boolean`);
+  const homes = resolveHarnessHomes(env);
+  if (Object.hasOwn(decoded, 'homes')) {
+    const supplied = struct(decoded.homes, Object.keys(homes), 'homes');
+    for (const key of Object.keys(homes)) if (Object.hasOwn(supplied, key)) { string(supplied[key], `homes.${key}`); homes[key] = supplied[key]; }
+  }
+  return { homes };
+}
+
+function settingsPath(root) {
+  let parent;
+  if (!root || root === parse(root).root) parent = '.';
+  else { parent = dirname(root); if (parent === '.' && !root.includes(sep) && !(process.platform === 'win32' && root.includes('/'))) parent = ''; }
+  return !parent ? 'settings.json' : `${parent}${parent.endsWith(sep) || process.platform === 'win32' && /^[A-Za-z]:$/.test(parent) ? '' : sep}settings.json`;
+}
+export function readClaudeInteropSettings(homes, cwd) {
+  const path = settingsPath(homes.claude_code); let bytes;
+  try { bytes = readFileSync(treeSelectedPath(path, cwd)); }
+  catch (error) { if (error.code === 'ENOENT') bytes = new Uint8Array(); else throw new Error(`Claude Code settings I/O failed: ${error.message}`); }
+  let settings;
+  try { settings = bytes.length ? parseNativeJson(new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes)) : {}; }
+  catch (error) { throw new Error(`Claude Code settings JSON is invalid: ${error.message}`); }
+  if (settings == null || typeof settings !== 'object' || Array.isArray(settings)) throw new Error(`Claude Code settings at ${path} must be a JSON object`);
+  const configured = Object.hasOwn(settings, 'crossSessionInbound') ? settings.crossSessionInbound : null;
+  if (Object.hasOwn(settings, 'crossSessionInbound') && !['accept', 'hold', 'refuse'].includes(configured)) throw new Error(`Claude Code setting \`crossSessionInbound\` at ${path} must be \`accept\`, \`hold\`, or \`refuse\`, not ${stringifyNativeJsonMember(settings, 'crossSessionInbound')}`);
+  return {
+    schema: 'supercode.harness-interop-settings.v1', harness: 'claude-code', revision: bytesToHex(blake3(bytes)),
+    controls: [{ key: 'cross_session_inbound', native_key: 'crossSessionInbound', label: 'Messages from other sessions',
+      description: 'How Claude Code handles messages arriving from another live Claude Code session.', scope: 'user', source_path: path,
+      configured_value: configured, effective_value: null, effective_known: false,
+      effective_note: 'This is the user-level value. Managed, project, or command-line policy may override it for a particular process.',
+      choices: [{ value: 'accept', label: 'Allow automatically', description: "Deliver messages from the user's other Claude Code sessions without a separate inbound approval.",
+        risk: "A trusted peer session can introduce instructions into this session; the receiver's configured permission mode still governs subsequent tool use." },
+      { value: 'hold', label: 'Ask before delivery', description: 'Hold messages from sessions in a different permission-mode class for review.' },
+      { value: 'refuse', label: 'Refuse automatically', description: 'Do not deliver messages from sessions in a different permission-mode class.' }],
+      writable: true, resettable: configured != null, requires_restart: false }],
+    advisories: configured === 'accept' ? [] : [{ code: 'claude_cross_session_inbound_accept', severity: 'warning', title: 'Claude may hold messages from other sessions',
+      message: "Volter Harness can hand a message to Claude's inbox, but Claude may hold or refuse it under the current user-level inbound policy.", setting: 'cross_session_inbound',
+      recommendation: { label: 'Allow messages from my other Claude sessions', description: "Set Claude Code's user-level cross-session inbound policy to accept.",
+        consequence: "Other Claude Code sessions owned by this user can introduce instructions without a separate inbound approval. The receiving session's configured permission mode still applies.",
+        change: { key: 'cross_session_inbound', value: 'accept' }, command: 'supercode harness configure claude-code --cross-session-inbound accept' } }],
+  };
+}
+export function sessionMessageInboundControls(homes, { cwd = process.cwd() } = {}) {
+  try { return { inbound_controls: readClaudeInteropSettings(homes, cwd), inbound_controls_error: null }; }
+  catch (error) { return { inbound_controls: null, inbound_controls_error: `Volter Harness could not inspect Claude Code inbound controls: ${error.message}` }; }
+}

package/session-model.d.ts

@@ -21,7 +21,12 @@ export interface MessageWire {
 }
 export interface MessageJson extends MessageWire { metadata: Record<string, string> }
 export type ToolOutcome = 'known_success' | 'known_error' | 'unknown';
+export interface NativeFirstResponse {
+  outcome: 'response' | 'error'; at: string | null; record_id: string | null; error_code: string | null;
+}
 export interface SessionMeta {
+  /** First main-chain Claude assistant record, including native API errors. */
+  first_response?: NativeFirstResponse;
   source: SessionSource; session_id: string | null; ended_at: string | null; end_reason: string | null;
   model: string | null; cwd: string | null; system_prompt: string | null;
   codex_headers: JsonValue[]; codex_provenance: JsonValue[];
@@ -39,6 +44,8 @@ export interface Session {
   raw_is_verbatim: boolean; parse_error_lines: number; load_residue: string[];
 }
 export interface NormalizedSession {
+  /** First main-chain Claude assistant record; response does not attest turn completion. */
+  first_response?: NativeFirstResponse;
   source: SessionSource; session_id: string | null; ended_at: string | null; end_reason: string | null;
   model: string | null; cwd: string | null; system_prompt: string | null;
   agent_id: string | null; parent_tool_use_id: string | null; lineage: Record<string, string>;
@@ -60,6 +67,8 @@ export interface RecordedSessionProfile {
 }
 export interface RecordedSessionProfileChange { native_key: string; at: string | null; profile: RecordedSessionProfile }
 export interface ProjectedSession {
+  /** First main-chain Claude assistant record; response does not attest turn completion. */
+  first_response?: NativeFirstResponse;
   source: SessionSource; session_id: string | null; ended_at: string | null; end_reason: string | null;
   model: string | null; resolved_profile: RecordedSessionProfile; resolved_profile_history: RecordedSessionProfileChange[];
   cwd: string | null; system_prompt: string | null; agent_id: string | null; parent_tool_use_id: string | null;

package/session-model.mjs

@@ -50,6 +50,7 @@ export function normalizedSessionJson(session) {
   const { meta } = session;
   return {
     source: meta.source, session_id: meta.session_id, ended_at: meta.ended_at, end_reason: meta.end_reason,
+    ...(meta.first_response ? { first_response: cloneNativeJson(meta.first_response) } : {}),
     model: meta.model, cwd: meta.cwd, system_prompt: meta.system_prompt, agent_id: meta.agent_id,
     parent_tool_use_id: meta.parent_tool_use_id, lineage: cloneNativeJson(meta.lineage), trigger: sessionTrigger(meta),
     surface: cloneNativeJson(meta.surface), profile: meta.profile, recurrence: cloneNativeJson(meta.recurrence),

package/session-opencode-store.mjs

@@ -3,7 +3,7 @@ import { readStore, statement, tableColumns, text, integer } from './sqlite-read
 import { sourceStat } from './store-registry.mjs';
 import { optionalFile, verifySources } from './source-files.mjs';
 import { sessionFileText } from './session-file.mjs';
-import { parseNativeJson, setNativeInteger, setNativeFloat } from './native-json.mjs';
+import { parseNativeJson, copyNativeJsonMember, setNativeInteger, setNativeFloat } from './native-json.mjs';
 import { isObject, stringField } from './session-codec-utils.mjs';
 import { fromOpenCodeStr, opencodeEnvelope } from './session-opencode.mjs';
 
@@ -51,8 +51,11 @@ function nativeRow(row, sessionId, messageId, options) {
   const id = text(row.id), value = jsonColumn(text(row.data), messageId == null ? 'message.data' : 'part.data', id, options);
   // A malformed/non-object data column remains diagnostically absent, as native.
   if (isObject(value)) {
-    value.id = id; value.sessionID = sessionId;
-    if (messageId != null) value.messageID = messageId;
+    // Register injected identity fields before timestamps in the parsed
+    // object's native insertion order, matching the SQLite envelope writer.
+    const identity = { id, sessionID: sessionId };
+    if (messageId != null) identity.messageID = messageId;
+    for (const key of Object.keys(identity)) copyNativeJsonMember(value, key, identity);
     stamp(value, 'time_created', integer(row.time_created)); stamp(value, 'time_updated', integer(row.time_updated));
   } else { integer(row.time_created); integer(row.time_updated); }
   return value;
@@ -99,3 +102,36 @@ export async function readOpenCodeSqlite(path, sessionId = null, options = {}) {
   const session = fromOpenCodeStr(`${lines.join('\n')}\n`); session.raw_is_verbatim = false;
   return { result: session, sources };
 }
+
+/** Complete corpus projection using the same native row reconstruction as
+ * selected-session reads. A zero native limit still selects the first id. */
+export async function readOpenCodeCorpus(path, limit = null, options = {}) {
+  if (!(await sourceStat(path))?.isFile()) throw new Error(`OpenCode SQLite store not found at ${path} — expected an \`opencode*.db\` file`);
+  const captured = await readStore(path, db => {
+    if (!statement(db, "SELECT count(*) AS count FROM sqlite_master WHERE type='table' AND name='session'").get().count) throw new Error(`${path} is a SQLite database but has no \`session\` table — not a recognized OpenCode store`);
+    const selected = [];
+    for (const row of statement(db, 'SELECT id FROM session ORDER BY time_created,id').iterate()) {
+      const id = text(row.id); selected.push({id, lines:envelopeLines(db, id, options)});
+      if (limit != null && BigInt(selected.length) >= limit) break;
+    }
+    return selected;
+  }, options.metrics);
+  const lines = [], sources = [...captured.sources];
+  for (const selected of captured.result) {
+    lines.push(...selected.lines);
+    const sidecarPath = join(dirname(path), 'storage', 'session_diff', `${selected.id}.json`);
+    // The corpus sidecar is best effort, including read/UTF-8 failures.
+    // A present malformed JSON value still emits the native diagnostic.
+    try {
+      const sidecar = await optionalFile(sidecarPath, async reader => {
+        const source = await sessionFileText(reader);
+        try { return {parsed:true, value:parseNativeJson(source)}; }
+        catch (error) { diagnostic(options, {message:'opencode session_diff sidecar failed to parse as JSON — skipping', path:sidecarPath, error:error.message}); return {parsed:false}; }
+      }, options.metrics);
+      sources.push(sidecar);
+      if (sidecar.result?.parsed) lines.push(opencodeEnvelope(['session_diff', selected.id], sidecar.result.value));
+    } catch (error) { if (error.code === 'ESTALE') throw error; }
+  }
+  await verifySources(sources);
+  return lines;
+}

package/session-path.mjs

@@ -6,7 +6,7 @@ import { withSessionFile, fileFingerprint } from './file-io.mjs';
 import { sourceStat } from './store-registry.mjs';
 import { optionalFile, verifySources, decodeWorkspaceFolder } from './source-files.mjs';
 import { readStore, statement } from './sqlite-reader.mjs';
-import { decodeSessionUtf8, sessionFileBytes, sessionFileText, textTooLong, SESSION_UNREADABLE } from './session-file.mjs';
+import { decodeSessionUtf8, sessionFileBytes, sessionFileText, textTooLong, sessionByteLimit, MAX_SESSION_DOCUMENT_BYTES, SESSION_UNREADABLE } from './session-file.mjs';
 import { field, stringField, valueString } from './session-codec-utils.mjs';
 import { parseNativeJson } from './native-json.mjs';
 import { nonEmptyLines } from './session-lines.mjs';
@@ -26,8 +26,11 @@ export async function sessionReaderText(reader) {
   let bytes = await sessionFileBytes(reader);
   if (isCompressedSessionPath(reader.path)) {
     if (typeof zlib.zstdDecompress !== 'function') throw new Error('compressed transcripts require Node 22.15 or later with zstdDecompress');
-    try { bytes = await promisify(zlib.zstdDecompress)(bytes); }
-    catch (error) { throw new Error(`${reader.path} is not a readable zstd stream: ${error.message}`, { cause: error }); }
+    try { bytes = await promisify(zlib.zstdDecompress)(bytes, { maxOutputLength: MAX_SESSION_DOCUMENT_BYTES }); }
+    catch (error) {
+      if (error.code === 'ERR_BUFFER_TOO_LARGE') throw sessionByteLimit(reader.path, 'decompressed output', error);
+      throw new Error(`${reader.path} is not a readable zstd stream: ${error.message}`, { cause: error });
+    }
   }
   try { return decodeSessionUtf8(bytes); } catch (error) { throw sessionTextError(reader.path, error); }
 }

package/session-pi-content.mjs

@@ -4,6 +4,10 @@ import { field, stringField, valueString, functionCall } from './session-codec-u
 import { nativeTrim } from './text.mjs';
 
 const append = (text, part) => typeof part === 'string' ? text + (text === '' ? '' : '\n') + part : text;
+export function piImageShape(block) {
+  const mime = stringField(block, 'mimeType'), data = stringField(block, 'data');
+  return mime != null && mime !== '' && data != null && data !== '' && !/[^A-Za-z0-9+/=]/.test(data) ? {mime, data} : null;
+}
 function stampNativeClock(value, message) {
   const timestamp = nativeInteger(value, 'timestamp');
   if (timestamp != null) message.metadata.pi_msg_timestamp = String(timestamp);
@@ -22,8 +26,9 @@ function contentParts(content) {
     if (kind === 'text') text = append(text, stringField(block, 'text'));
     else if (kind === 'image') {
       hasImage = true;
-      const mime = stringField(block, 'mimeType'), data = stringField(block, 'data');
-      if (mime == null || mime === '' || data == null || data === '' || !/^[A-Za-z0-9+/=]+$/.test(data)) return { text: '', parts: null, unknown: true };
+      const shape = piImageShape(block);
+      if (shape == null) return { text: '', parts: null, unknown: true };
+      const {mime, data} = shape;
       parts.push({ type: 'image_url', image_url: { url: `data:${mime};base64,${data}` } });
     }
   }

package/session-read.d.ts

@@ -5,13 +5,53 @@ export const SESSION_READ_METHODS: readonly string[];
 export const SESSION_READ_EVENT: 'harness.v1.sessions.event';
 /** The read doors' error code for a file this reader cannot read for what is in it. */
 export const SESSION_UNREADABLE: -32050;
-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 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; tree: true; activity_under: 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: readonly ['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 interface SessionReadContext { cwd?: string; env?: Record<string, string | undefined> }
+export interface ProfileRow {
+  name: string; harness: string;
+  kind: 'preset' | 'codex_profile' | 'hermes_profile' | 'openclaw_agent' | 'orchestrator_profile';
+  home: string | null; default: boolean; routes: number | null; sessions: number | null; model: string | null; worker?: string;
+}
+/** The harness command is followed by its own profile-store readback. */
+export function mutateProfile(verb: 'create' | 'delete', params: unknown, context?: SessionReadContext & { signal?: AbortSignal }): Promise<{ harness: 'hermes' | 'openclaw' | 'orchestrator'; verb: 'create' | 'delete'; ran: string; name: string; profile?: ProfileRow; deleted?: boolean }>;
+/** Counts preserve native integer literals on the RPC wire. */
+export function listProfiles(params: unknown, context?: SessionReadContext): { schema: 'supercode.profiles.v1'; profiles: ProfileRow[] };
+export function getProfile(params: unknown, context?: SessionReadContext): { schema: 'supercode.profiles.v1'; profile: ProfileRow };
+export interface RecordedChannel {
+  name: string; harness: string; kind: string; account: string | null; enabled: boolean | null; configured: boolean; status: 'unknown'; sessions: number | null;
+}
+/** Credential presence and catalog session counts only; probes no connection. */
+export function listChannels(params: unknown, context?: SessionReadContext): Promise<{ schema: 'supercode.channels.v1'; channels: RecordedChannel[] }>;
+export function channelStatus(params: unknown, context?: SessionReadContext): Promise<{ schema: 'supercode.channels.v1'; channel: RecordedChannel }>;
+export interface RecordedTrigger {
+  name: string; harness: string; kind: 'webhook' | 'hook_mapping' | 'builtin_wake' | 'builtin_agent'; route: string; events?: string[];
+  target: { action?: string; profile?: string; session_key?: string; wake_mode?: string; model?: string };
+  deliver: { target?: string; chat_id?: string }; enabled: boolean; authenticated: boolean; source: string; description?: string;
+}
+/** Recorded endpoint facts only, after complete home validity; starts no trigger. */
+export function listTriggers(params: unknown, context?: SessionReadContext): { schema: 'supercode.triggers.v1'; triggers: RecordedTrigger[] };
+export interface RecordedRoute {
+  harness: string; target: string;
+  match: { platform?: string; account?: string; guild?: string; team?: string; chat_id?: string; peer_kind?: string; thread_id?: string; roles?: string[] };
+  specificity: number; default: boolean; source: string;
+}
+/** Recorded matches and precedence after complete home validity; resolves no traffic. */
+export function listRoutes(params: unknown, context?: SessionReadContext): { schema: 'supercode.routes.v1'; routes: RecordedRoute[] };
+export interface MemoryDocument {
+  name: string; harness: string; scope: 'user' | 'project' | 'profile' | 'agent';
+  profile?: string; path: string; size: number; updated_at?: string;
+  preview: string[]; truncated: boolean; content?: string;
+}
+/** Native integer sizes are retained on the RPC wire. */
+export function showMemory(params: unknown, context?: SessionReadContext): { schema: 'supercode.memory.v1'; documents: MemoryDocument[] };
 export function parseSessionWire(text: string): unknown;
 export function stringifySessionWire(value: unknown): string;
+/** Keeps the original request ID's native integer/float facts on its reply. */
+export function sessionWireReply(request: { id?: unknown } | null | undefined, answer: Record<string, unknown>): Record<string, unknown>;
 export function prettySessionWire(value: unknown): string;
 export function parseSessionReadParams(params: unknown, context?: SessionReadContext): { locator: ReadLocator; fidelity: string; view: (SessionFollowOptions & { fromByte: number | null; fromMessage: number | null; windowBytes: number | null; windowMessages: number | null; marks: boolean }) | 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[]; window?: { offset: number; returned: number; total_messages: number; marks: string[]; all_marks?: string[] } } }>;
+export function loadSessionRead(params: unknown, context?: SessionReadContext): Promise<ProjectedSessionResult | { session: NormalizedSession & { resolved_profile: RecordedSessionProfile; resolved_profile_history: RecordedSessionProfileChange[]; window?: { offset: number; returned: number; total_messages: number | null; marks: string[]; marks_from?: number; tail_marks?: string[]; reading?: { bytes: number; size: number }; replay?: { whole: boolean; reason: string | null } } } }>;
 export function openSessionReadFollower(params: unknown, context?: SessionReadContext): Promise<SessionFollower>;
 /** Recorded values only; malformed complete Claude runtime state leaves mode unknown. */
 export function loadRecordedSessionConfiguration(params: unknown, context?: SessionReadContext): Promise<{ harness: string; session_id: string | null; cwd: unknown; model: unknown; approval_policy: unknown; sandbox_policy: unknown; permission_mode: string | null }>;
@@ -36,3 +76,95 @@ export interface MachineTokenSpend extends RecordedTokenSpend {
 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> } }>;
+
+/** Strict native integer facts for opaque daemon replies, independent of SDK Number decoding. */
+export function sessionWireInteger(parent: unknown, key: string, options?: { signed?: boolean }): bigint | null;
+export function parseSessionMessageParams(params: unknown, context?: SessionReadContext): { homes: Record<string, string> };
+/** User-level evidence only; it neither changes policy nor establishes an effective process value. */
+export function sessionMessageInboundControls(homes: Record<string, string>, context?: SessionReadContext): { inbound_controls: unknown; inbound_controls_error: string | null };
+
+/** Explicit in-memory document import; no store, vendor process or format detection. */
+export function importSessionDocument(params: unknown): { session: NormalizedSession };
+
+/** Compiled implementation facts; does not start or probe a vendor. */
+export function supportRegistryReport(context?: SessionReadContext): { schema: "supercode.support-registry.v1"; harnesses: Record<string, unknown>[] };
+
+/** User-level settings only; no mutation or effective-process-policy claim. */
+export function loadHarnessSettings(params: unknown, context?: SessionReadContext): {
+  schema: 'supercode.harness-interop-settings.v1'; harness: string; revision: string;
+  controls: Array<{
+    key: string; native_key: string; label: string; description: string; scope: string;
+    source_path: string; configured_value: string | null; effective_value: string | null;
+    effective_known: boolean; effective_note: string;
+    choices: Array<{ value: string; label: string; description: string; risk?: string }>;
+    writable: boolean; resettable: boolean; requires_restart: boolean;
+  }>;
+  advisories: Array<{
+    code: string; severity: string; title: string; message: string; setting: string;
+    recommendation: { label: string; description: string; consequence: string;
+      change: { key: string; value: string | null }; command: string };
+  }>;
+};
+
+/** Read-only installed packages; runtime loading retains its native owner. */
+export function listInstalledSkills(params: unknown, context?: SessionReadContext): Array<{
+  name: string; harness: string; scope: 'managed' | 'user' | 'project' | 'plugin' | 'bundled';
+  location: string; description?: string; version?: string; enabled: boolean | null;
+}>;
+
+/** Install/remove through the selected harness's CLI or documented loader root. */
+export function mutateInstalledSkill(verb: 'install' | 'remove', params: unknown, context?: SessionReadContext & { signal?: AbortSignal }): Promise<{
+  harness: string; verb: 'install' | 'remove'; ran: string; name: string;
+  skill?: ReturnType<typeof listInstalledSkills>[number]; removed?: true;
+}>;
+
+/** Read-only Hermes notepad; selected job/profile must exist before opening its store. */
+export function readJobNotepad(params: unknown, context?: { env?: Record<string, string | undefined>; cwd?: string }): { harness: string; id: string; entries: { key: string; value: string; updated_at: string }[] };
+
+/** Complete validated home history; read-only, with exact native integer facts on the wire. */
+export interface RecordedRunDelivery { target: string | null; state: string | null; attempts: number | null; last_error: string | null; delivered_at: string | null }
+export interface RecordedRun { id: string; harness: string; job_id: string; status: string; claimed_at: string | null; started_at: string | null; finished_at: string | null; error: string | null; session_id: string | null; delivery: RecordedRunDelivery | null }
+export interface RecordedRunSource { harness: string; path: string; state: 'read' | 'absent_store' | 'unreadable'; profile: string | null; detail: string | null }
+export function listRuns(params: unknown, context?: SessionReadContext): { runs: RecordedRun[]; sources: RecordedRunSource[] };
+export function getRun(params: unknown, context?: SessionReadContext): { run: RecordedRun; source: Record<string, unknown> };
+
+/** Complete job sources and observed projections; starts no scheduler. */
+export interface RecordedJob {
+  id: string; harness: string; scope: 'session' | 'install'; profile: string | null; session_id: string | null;
+  schedule: { kind: string; expr: string | null; minutes: number | null; run_at: string | null; display: string };
+  payload: { kind: string; text: string | null }; session_target: string | null;
+  deliver: { target: string | null; chat_id: string | null; thread_id: string | null; account: string | null; mode: string | null };
+  enabled: boolean; state: string; next_run_at: string | null; last_run_at: string | null; last_status: string | null;
+  last_delivery_error: string | null; created_at: string | null; recurring: boolean;
+}
+export interface RecordedJobSource { harness: string; path: string; state: 'read' | 'absent_store' | 'unreadable' | 'scanned'; profile: string | null; sessions_scanned: number | null; scan_limit: number | null; detail: string | null }
+export function listJobs(params: unknown, context?: SessionReadContext): Promise<{ jobs: RecordedJob[]; sources: RecordedJobSource[] }>;
+export function getJob(params: unknown, context?: SessionReadContext): Promise<{ job: RecordedJob; source: unknown }>;
+
+/** Complete read-only Hermes or supercode board projection; no dispatch or writer. */
+export function loadWorkflow(params: unknown, context?: SessionReadContext): { workflow: { root: string; boards: Record<string, unknown> } };
+
+export interface SessionTransferArtifact {
+  source_harness: string; target_harness: string; session_id: string | null;
+  content: string; suggested_filename: string;
+  files: Array<{ path: string; content: string; role: 'primary' | 'subagent' | 'bundle' | 'source_recovery' }>;
+  fidelity: 'byte_lossless' | 'value_lossless' | 'semantic'; residue: string[];
+}
+export interface ImportedHermesSession { session_id: string; home: string; rollout: string; via: 'hermes sessions import --from codex' }
+/** Full lossless load and artifact construction. Export to Hermes invokes its own import command;
+ * every transfer may populate the content-addressed source residue cache. */
+export function transferSession(params: unknown, context?: SessionReadContext & { exporting?: boolean; signal?: AbortSignal }): Promise<{ artifact: SessionTransferArtifact; imported?: ImportedHermesSession }>;
+
+/** Frozen branch with an optional target artifact. Cuts require one recorded user-message ID. */
+export function branchSession(params: unknown, context?: SessionReadContext & { signal?: AbortSignal }): Promise<{ parent: ReadLocator; session: NormalizedSession; bootstrap_prompt: string; artifact: SessionTransferArtifact | null }>;
+export interface HandoffLaunch { cwd: string; program: string; arguments: string[]; env: Record<string, string> }
+/** Fresh target identity and launch/materialization instructions; invokes no vendor command. */
+export function handoffSession(params: unknown, context?: SessionReadContext & { signal?: AbortSignal }): Promise<{ artifact: SessionTransferArtifact; launch: HandoffLaunch; materialize: HandoffLaunch | null; requires_materialization: true; note: string }>;
+
+/** Fresh-ID exclusive continuation files or OpenCode CLI import/read-only confirmation.
+ * Recovery cache writes precede validation; earlier bundle files survive later failure. */
+export function materializeSession(params: unknown, context?: SessionReadContext & { signal?: AbortSignal }): Promise<{ locator: ReadLocator }>;
+
+export const CONTROLLED_JOB_HARNESSES: readonly ['hermes', 'openclaw', 'orchestrator'];
+export function mutateJob(verb: 'create' | 'update' | 'pause' | 'resume' | 'run' | 'delete', params: unknown, context?: SessionReadContext & { signal?: AbortSignal }): Promise<{ harness: string; verb: string; ran: string; id: string; job?: RecordedJob; deleted?: true }>;
+export function mutateJobNotepad(verb: 'set' | 'delete', params: unknown, context?: SessionReadContext & { signal?: AbortSignal }): Promise<ReturnType<typeof readJobNotepad> & { ran: string }>;