@volter/supercode-interchange 0.1.22 → 0.1.24

package/runs-read.mjs

@@ -0,0 +1,224 @@
+// Recorded fire history, after the owning codec's complete home validity
+// boundary. No scheduler, claim, retry, pruning or write runs here.
+import { readdirSync, statSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { resolveHarnessHomes } from './homes.mjs';
+import { childPath, textName } from './session-spend-files.mjs';
+import { profilePathJoin as join, profilePathParent as parent } from './profile-paths.mjs';
+import { readRunFolderHome } from './hermes-read-home.mjs';
+import { readOpenclawRunHome } from './openclaw-profile-home.mjs';
+import { hermesRowText } from './hermes-fires.mjs';
+import { usageMoment } from './session-usage-time.mjs';
+import { nativeDuplicateObjectKeys, nativeInteger, parseNativeJson, setNativeInteger, stringifyNativeJsonMember } from './native-json.mjs';
+
+export const RUN_HARNESSES = Object.freeze(['hermes', 'openclaw', 'orchestrator']);
+const object = value => value != null && typeof value === 'object' && !Array.isArray(value);
+const compare = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+const string = value => typeof value === 'string' ? value : null;
+const display = path => Buffer.isBuffer(path) ? path.toString('utf8') : path;
+const file = path => { try { return statSync(path).isFile(); } catch { return false; } };
+const directory = path => { try { return statSync(path).isDirectory(); } catch { return false; } };
+const filesystem = (path, cwd) => !path.length || isAbsolute(display(path)) || process.platform === 'win32' && /^[A-Za-z]:/u.test(display(path)) ? path : Buffer.isBuffer(path) ? childPath(cwd, path) : join(cwd, path);
+const refuse = (message, rpcCode = -32602) => { throw Object.assign(new Error(message), { rpcCode }); };
+const intMin = -(1n << 63n), intMax = (1n << 63n) - 1n, uintMax = (1n << 64n) - 1n;
+function struct(value, fields, name) {
+  if (Array.isArray(value)) {
+    if (value.length > fields.length) refuse(`${name} has too many fields`);
+    // Preserve integer facts when a serde struct is represented as a sequence.
+    return parseNativeJson(`{${value.map((_, at) => `${JSON.stringify(fields[at])}:${stringifyNativeJsonMember(value, String(at))}`).join(',')}}`);
+  }
+  if (!object(value)) refuse(`${name} must be a struct`);
+  if (nativeDuplicateObjectKeys(value).some(key => fields.includes(key))) refuse(`${name} has a duplicate field`);
+  return value;
+}
+function query(params, context, get = false) {
+  const query = struct(params, get ? ['harness', 'id', 'homes'] : ['harness', 'job', 'limit', 'homes'], 'runs params');
+  for (const key of get ? ['harness', 'id'] : ['harness', 'job']) {
+    if (get ? typeof query[key] !== 'string' : query[key] != null && typeof query[key] !== 'string') refuse(`${key} must be a string`);
+  }
+  let limit = null;
+  if (!get && query.limit != null) {
+    limit = nativeInteger(query, 'limit');
+    if (limit == null) refuse('limit must be a native unsigned integer');
+  }
+  const homes = resolveHarnessHomes(context.env);
+  if (Object.hasOwn(query, 'homes')) {
+    const supplied = struct(query.homes, Object.keys(homes), 'homes');
+    for (const key of Object.keys(homes)) if (Object.hasOwn(supplied, key)) {
+      if (typeof supplied[key] !== 'string') refuse(`homes.${key} must be a string`);
+      homes[key] = supplied[key];
+    }
+  }
+  if (query.harness != null && !RUN_HARNESSES.includes(query.harness)) refuse(`\`${query.harness}\` keeps no run store; \`runs.${get ? 'get' : 'list'}\` is supported for: ${RUN_HARNESSES.join(', ')}`, -32020);
+  return { harness: query.harness ?? null, job: get ? null : query.job ?? null, id: query.id, limit, homes };
+}
+const limited = (rows, limit) => limit == null || limit >= BigInt(rows.length) ? rows : rows.slice(0, Number(limit));
+const source = (harness, path, profile, state, detail = null) => ({ harness, path: display(path), state, profile, detail });
+const member = (row, key, fallback = 'null') => Object.hasOwn(row, key) ? stringifyNativeJsonMember(row, key) : fallback;
+const nativeObject = entries => parseNativeJson(`{${entries.map(([key, token]) => `${JSON.stringify(key)}:${token}`).join(',')}}`);
+const token = value => JSON.stringify(value);
+
+function ledgers(root, harness, cwd) {
+  if (harness === 'orchestrator' && !directory(filesystem(root, cwd))) return [];
+  const rows = [{ path: join(root, 'cron/executions.db'), profile: null }], profiles = join(root, 'profiles');
+  try {
+    const named = readdirSync(filesystem(profiles, cwd), { encoding: 'buffer' }).flatMap(name => {
+      const dir = childPath(profiles, name);
+      if (harness === 'orchestrator') {
+        // This inventory's native wrapper returns no directories on any
+        // registry read error. Its complete home read still refuses separately.
+        if (!statSync(filesystem(dir, cwd)).isDirectory()) return [];
+        const text = textName(name); if (text == null || text.startsWith('.')) return [];
+        return [{ path: childPath(dir, 'cron/executions.db'), profile: text === 'default' ? null : text, sort: text }];
+      }
+      return directory(filesystem(dir, cwd)) ? [{ path: childPath(dir, 'cron/executions.db'), profile: name.toString('utf8'), sort: name.toString('utf8') }] : [];
+    }).sort((a, b) => compare(a.sort, b.sort));
+    rows.push(...named);
+  } catch (error) { if (harness === 'orchestrator' && !['ENOENT', 'ENOTDIR'].includes(error.code)) return []; }
+  return rows;
+}
+const float = value => {
+  if (typeof value === 'number') return value;
+  if (typeof value !== 'string') return null;
+  if (/^[+-]?(?:inf|infinity)$/iu.test(value)) return value.startsWith('-') ? -Infinity : Infinity;
+  if (/^[+-]?nan$/iu.test(value)) return NaN;
+  return /^[+-]?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][+-]?[0-9]+)?$/u.test(value) ? Number(value) : null;
+};
+const cast = (number, low, high) => Number.isNaN(number) ? 0n : number <= Number(low) ? low : number >= Number(high) ? high : BigInt(Math.trunc(number));
+function obligationDelivery(profiles, id) {
+  let obligation;
+  for (const [, profile] of [...profiles].sort(([a], [b]) => compare(a, b))) {
+    obligation = profile.obligations.find(row => row.id === id); if (obligation) break;
+  }
+  if (!obligation) return null;
+  const row = obligation.row, thread = hermesRowText(row, 'thread_id'), state = row.state === 'sent' ? 'delivered' : row.state;
+  const updated = hermesRowText(row, 'updated_at') ?? obligation.created_at;
+  const at = state === 'delivered' ? float(updated) : null;
+  const delivery = { target: `${obligation.target.platform}:${obligation.target.chat_id}${thread ? `:${thread}` : ''}`, state,
+    attempts: 0, last_error: hermesRowText(row, 'last_error') || null, delivered_at: at == null ? null : usageMoment(cast(at * 1000, intMin, intMax)) };
+  setNativeInteger(delivery, 'attempts', cast(float(row.attempts) ?? 0, 0n, uintMax));
+  return delivery;
+}
+function hermesSource(fire) {
+  return nativeObject([
+    ['id', token(fire.id)], ['job_id', token(fire.job_id)], ['source', member(fire.residue, 'source', '"scheduler"')],
+    ['process_id', member(fire.residue, 'process_id', '""')], ['pid', member(fire.residue, 'pid', '0')],
+    ['process_started_at', member(fire.residue, 'process_started_at')], ['status', token(fire.status === 'succeeded' ? 'completed' : fire.status)],
+    ...['claimed_at', 'started_at', 'finished_at', 'error'].map(key => [key, token(fire[key])]),
+  ]);
+}
+function folderRuns(harness, selected, context) {
+  const home = harness === 'hermes' ? parent(selected.homes.hermes) ?? '.' : selected.homes.orchestrator;
+  const inventory = ledgers(home, harness, context.cwd), rows = [], sources = [];
+  // Display the caller's lexical paths, just as native PathBuf serialization
+  // does, while filesystem access resolves them against the caller's cwd.
+  const actual = filesystem(home, context.cwd);
+  let profiles;
+  try { profiles = readRunFolderHome(actual, harness); }
+  catch (error) {
+    for (const ledger of inventory) { const state = file(filesystem(ledger.path, context.cwd)) ? 'unreadable' : 'absent_store'; sources.push(source(harness, ledger.path, ledger.profile, state, state === 'unreadable' ? error.message : null)); }
+    return { rows, sources };
+  }
+  for (const ledger of inventory) {
+    const profile = profiles.get(ledger.profile ?? 'default'), state = file(filesystem(ledger.path, context.cwd)) && profile ? 'read' : 'absent_store';
+    sources.push(source(harness, ledger.path, ledger.profile, state)); if (state !== 'read') continue;
+    const fires = limited(profile.fires.filter(fire => selected.job == null || fire.job_id === selected.job).sort((a, b) => compare(b.claimed_at, a.claimed_at) || compare(b.id, a.id)), selected.limit);
+    for (const fire of fires) rows.push({ run: { id: fire.id, harness, job_id: fire.job_id, status: fire.status === 'succeeded' ? 'completed' : fire.status,
+      claimed_at: fire.claimed_at, started_at: fire.started_at, finished_at: fire.finished_at, error: fire.error,
+      session_id: fire.session_id, delivery: fire.obligation_id == null ? null : obligationDelivery(profiles, fire.obligation_id) }, source: hermesSource(fire) });
+  }
+  return { rows, sources };
+}
+
+const floor = (a, b) => a < 0n ? (a - b + 1n) / b : a / b;
+function openclawMoment(ms) {
+  if (ms == null) return null;
+  const seconds = floor(ms, 1000n), sub = ms - seconds * 1000n, days = floor(seconds, 86400n), sod = seconds - days * 86400n;
+  const z = days + 719468n, era = floor(z, 146097n), doe = z - era * 146097n;
+  const yoe = (doe - doe / 1460n + doe / 36524n - doe / 146096n) / 365n;
+  let y = yoe + era * 400n;
+  const doy = doe - (365n * yoe + yoe / 4n - yoe / 100n), mp = (5n * doy + 2n) / 153n;
+  const day = doy - (153n * mp + 2n) / 5n + 1n, month = mp < 10n ? mp + 3n : mp - 9n;
+  y += month <= 2n ? 1n : 0n;
+  const pad = (n, width = 2) => n < 0n ? `-${String(-n).padStart(width - 1, '0')}` : String(n).padStart(width, '0');
+  return `${pad(y, 4)}-${pad(month)}-${pad(day)}T${pad(sod / 3600n)}:${pad(sod % 3600n / 60n)}:${pad(sod % 60n)}.${pad(sub, 3)}Z`;
+}
+const msOf = (row, key) => nativeInteger(row, key, { signed: true }) ?? (float(row[key]) == null ? null : cast(float(row[key]), intMin, intMax));
+const openText = (row, key) => typeof row[key] === 'string' ? row[key] || null : typeof row[key] === 'number' ? stringifyNativeJsonMember(row, key) : null;
+const jsonObject = value => { try { const parsed = typeof value === 'string' ? parseNativeJson(value) : null; return object(parsed) ? parsed : {}; } catch { return {}; } };
+const present = (...entries) => entries.find(([row, key]) => object(row) && Object.hasOwn(row, key));
+function openclawProfiles(loaded) {
+  const profiles = new Map(loaded.profiles.map(name => [name, { jobs: new Map(), fires: [] }])), owners = new Map();
+  const owner = value => { const name = value === loaded.defaultAgent ? 'default' : value; return profiles.has(name) ? name : 'default'; };
+  for (const row of loaded.jobs) {
+    const id = openText(row, 'job_id') ?? '', record = jsonObject(row.job_json);
+    const field = present([record, 'agentId'], [row, 'agent_id'], [row, 'owner_agent_id']);
+    const name = owner(field ? string(field[0][field[1]]) ?? loaded.defaultAgent : loaded.defaultAgent);
+    const delivery = object(record.delivery) ? record.delivery : Object.fromEntries(['channel', 'to'].flatMap(key => row[`delivery_${key}`] != null && row[`delivery_${key}`] !== '' ? [[key, row[`delivery_${key}`]]] : []));
+    profiles.get(name).jobs.set(id, delivery); owners.set(id, name);
+  }
+  let legacy; try { legacy = loaded.legacy == null ? null : parseNativeJson(loaded.legacy); } catch { /* infallible legacy decoding */ }
+  for (const row of Array.isArray(legacy) ? legacy : Array.isArray(legacy?.jobs) ? legacy.jobs : []) {
+    const id = [row?.id, row?.job_id, row?.jobId].find(value => typeof value === 'string');
+    if (!id || [...profiles.values()].some(profile => profile.jobs.has(id))) continue;
+    const field = present([row, 'agentId'], [row, 'agent_id']), name = owner(field ? string(field[0][field[1]]) ?? loaded.defaultAgent : loaded.defaultAgent);
+    profiles.get(name).jobs.set(id, object(row.delivery) ? row.delivery : {}); owners.set(id, name);
+  }
+  for (const row of loaded.fires) {
+    const id = openText(row, 'run_id'), job_id = openText(row, 'job_id') ?? '', start = msOf(row, 'run_at_ms'), finish = msOf(row, 'ts');
+    profiles.get(owners.get(job_id) ?? 'default').fires.push({ row, job_id, id: id ?? `${job_id}#${member(row, 'seq', '')}`,
+      started_at: openclawMoment(start), finished_at: openclawMoment(finish), start, finish });
+  }
+  return profiles;
+}
+const openColumns = ['store_key', 'job_id', 'seq', 'ts', 'status', 'error', 'summary', 'diagnostics_summary', 'delivery_status', 'delivery_error', 'delivered', 'session_id', 'session_key', 'run_id', 'run_at_ms', 'duration_ms', 'next_run_at_ms', 'model', 'provider', 'total_tokens', 'entry_json', 'created_at'];
+function openclawSource(fire) {
+  const row = fire.row, encoded = new Map(openColumns.map(key => [key, 'null']));
+  const ts = fire.finished_at?.startsWith('-') ? 0n : fire.finish ?? 0n, start = fire.started_at?.startsWith('-') ? null : fire.start;
+  encoded.set('store_key', row.store_key == null ? '""' : member(row, 'store_key'));
+  encoded.set('job_id', token(fire.job_id)); encoded.set('ts', String(ts));
+  // Mapped seq is consumed by decoding and is absent from Fire residue.
+  encoded.set('status', row.status == null ? '"skipped"' : member(row, 'status'));
+  for (const key of ['error', 'session_id']) encoded.set(key, token(openText(row, key)));
+  for (const key of ['delivery_status', 'delivery_error', 'delivered', 'session_key']) encoded.set(key, row[key] == null ? 'null' : member(row, key));
+  encoded.set('run_id', fire.id.includes('#') ? 'null' : token(fire.id)); encoded.set('run_at_ms', start == null ? 'null' : String(start));
+  encoded.set('entry_json', row.entry_json == null ? token(`{"action":"finished","ts":${ts},"jobId":${token(fire.job_id)},"status":${encoded.get('status')}}`) : member(row, 'entry_json'));
+  encoded.set('created_at', row.created_at == null ? String(ts) : member(row, 'created_at'));
+  return nativeObject([...encoded]);
+}
+function openclawRuns(selected, context) {
+  const path = join(selected.homes.openclaw, 'state/openclaw.sqlite'), actual = filesystem(path, context.cwd);
+  if (!file(actual)) return { rows: [], sources: [source('openclaw', path, null, 'absent_store')] };
+  let loaded;
+  try { loaded = readOpenclawRunHome(filesystem(selected.homes.openclaw, context.cwd)); }
+  catch (error) { return { rows: [], sources: [source('openclaw', path, null, 'unreadable', error.message)] }; }
+  const fires = [...openclawProfiles(loaded)].sort(([a], [b]) => compare(a, b)).flatMap(([, profile]) => profile.fires.map(fire => ({ fire, profile })));
+  fires.sort((a, b) => a.fire.finished_at == null ? b.fire.finished_at == null ? compare(b.fire.id, a.fire.id) : 1 : b.fire.finished_at == null ? -1 : compare(b.fire.finished_at, a.fire.finished_at) || compare(b.fire.id, a.fire.id));
+  const rows = limited(fires.filter(({ fire }) => selected.job == null || selected.job === fire.job_id), selected.limit).map(({ fire, profile }) => {
+    const row = fire.row, words = profile.jobs.get(fire.job_id), channel = string(words?.channel) || null, to = string(words?.to) || null;
+    const target = channel && to ? `${channel}:${to}` : channel ?? to;
+    const status = string(row.delivery_status) || null, error = string(row.delivery_error) || null, delivered = nativeInteger(row, 'delivered', { signed: true });
+    return { run: { id: fire.id, harness: 'openclaw', job_id: fire.job_id, status: string(row.status) ?? '', claimed_at: null,
+      started_at: fire.started_at, finished_at: fire.finished_at, error: openText(row, 'error'), session_id: openText(row, 'session_id'),
+      delivery: status == null && error == null && delivered == null ? null : { target, state: status ?? (delivered == null ? null : delivered === 0n ? 'not-delivered' : 'delivered'), attempts: null, last_error: error, delivered_at: null } }, source: openclawSource(fire) };
+  });
+  return { rows, sources: [source('openclaw', path, null, 'read')] };
+}
+function collect(selected, context) {
+  const rows = [], sources = [];
+  for (const harness of RUN_HARNESSES) if (selected.harness == null || selected.harness === harness) {
+    const reading = harness === 'openclaw' ? openclawRuns(selected, context) : folderRuns(harness, selected, context);
+    rows.push(...reading.rows); sources.push(...reading.sources);
+  }
+  return { rows, sources };
+}
+export function listRuns(params, { env = process.env, cwd = process.cwd() } = {}) {
+  const context = { env, cwd }, selected = query(params, context), result = collect(selected, context);
+  return { runs: limited(result.rows, selected.limit).map(row => row.run), sources: result.sources };
+}
+export function getRun(params, { env = process.env, cwd = process.cwd() } = {}) {
+  const context = { env, cwd }, selected = query(params, context, true);
+  const found = collect(selected, context).rows.find(row => row.run.id === selected.id);
+  if (!found) refuse(`\`${selected.harness}\` has no run \`${selected.id}\``, -32000);
+  return found;
+}

package/session-activity.d.ts

@@ -0,0 +1,23 @@
+import type { SessionReadContext } from './session-read.js';
+export interface SessionActivityReading {
+  harness: string; session_id: string;
+  presence: 'persisted' | 'running' | 'shutting_down';
+  turn: 'unknown' | 'idle' | 'working' | 'needs_input';
+  evidence: { source: string; native_state: string | null; observed_at_ms: number; harness_version: string | null; waiting_for?: string; native_state_since_ms?: number; turn_trigger?: string };
+}
+export interface ActivitySubscriptionQuery {
+  locators: Array<{ harness: string; session_id: string; storage: { kind: 'file' | 'sqlite'; path: string; selector?: string } }>;
+  homes: Record<string, string>; home: string;
+}
+export const SESSION_ACTIVITY_EVENT: 'harness.v1.sessions.activity_event';
+export function sessionActivityKey(activity: { harness: string; session_id: string }): string;
+export function activitySubscribeQuery(params: unknown, context?: SessionReadContext): ActivitySubscriptionQuery;
+export function activityUnsubscribeQuery(params: unknown): string;
+export function sameSessionActivity(left: SessionActivityReading, right: SessionActivityReading): boolean;
+export function activityUnderQuery(params: unknown, context?: SessionReadContext): { pids: number[]; homes: Record<string, string>; home: string };
+export function codexDescendantActivity(statuses: Map<string, string>): Map<string, string>;
+export function sampledSessionActivity(locator: { harness: string; session_id: string; storage: { path: string } }, evidence: {
+  claude: Map<string, { status?: string | null; version?: string | null; waitingFor?: string | null; statusUpdatedAt?: number | null }>;
+  codex: Map<string, string>; codexTurns?: Map<string, { trigger: string | null; started_at_ms: number | null }>; descendants: Map<string, string>; owned: Map<string, string>; observedAt?: number;
+  hermes?: Map<string, { status: string; pid: number | null }>; live?: (pid: number) => boolean; codexPath?: string;
+}): SessionActivityReading;

package/session-activity.mjs

@@ -0,0 +1,124 @@
+// Proven lifecycle evidence, separate from transcript freshness and attention.
+import { sessionTreeQuery, treeUnsigned, treeRolloutHeader } from './session-machine-tree.mjs';
+import { parseSessionReadParams } from './session-read.mjs';
+import { setNativeInteger } from './native-json.mjs';
+
+const invalid = message => { throw Object.assign(new Error(message), { rpcCode: -32602 }); };
+const object = value => value != null && typeof value === 'object' && !Array.isArray(value);
+const key = locator => JSON.stringify([locator.harness, locator.session_id]);
+const rank = { running: 0, idle: 1, busy: 2, waiting: 3 };
+const stronger = (left, right) => left == null ? right : right == null || rank[left] >= rank[right] ? left : right;
+
+export const SESSION_ACTIVITY_EVENT = 'harness.v1.sessions.activity_event';
+export const sessionActivityKey = key;
+
+/** Subscription admission reads locators as addresses, without loading a
+ * transcript or applying load/view options. Unmodeled request keys are ignored. */
+export function activitySubscribeQuery(params, context = {}) {
+  if (!object(params)) invalid('activity subscribe params must be an object');
+  if (!Array.isArray(params.locators)) invalid('locators must be an array');
+  if (!params.locators.length) invalid('sessions.activity.subscribe requires at least one locator');
+  if (params.locators.length > 2048) invalid('sessions.activity.subscribe accepts at most 2048 locators');
+  const locators = params.locators.map(supplied => {
+    const { locator } = parseSessionReadParams({ locator: supplied }, context);
+    // Activity's native locator keeps its lexical path. The ownership sampler
+    // canonicalizes it at lookup time, without changing the recorded address.
+    locator.storage.path = supplied.storage.path;
+    return locator;
+  });
+  const query = sessionTreeQuery(Object.hasOwn(params, 'homes') ? { homes: params.homes } : {}, context);
+  return { locators, homes: query.homes, home: query.home };
+}
+
+export function activityUnsubscribeQuery(params) {
+  if (!object(params) || typeof params.subscription !== 'string') invalid('subscription must be a string');
+  return params.subscription;
+}
+
+/** Observation time is evidence, but changing only the clock is no transition. */
+export function sameSessionActivity(left, right) {
+  return left.harness === right.harness && left.session_id === right.session_id
+    && left.presence === right.presence && left.turn === right.turn
+    && left.evidence.source === right.evidence.source
+    && left.evidence.native_state === right.evidence.native_state
+    && left.evidence.waiting_for === right.evidence.waiting_for
+    && (treeUnsigned(left.evidence, 'native_state_since_ms') ?? left.evidence.native_state_since_ms)
+      === (treeUnsigned(right.evidence, 'native_state_since_ms') ?? right.evidence.native_state_since_ms)
+    && left.evidence.turn_trigger === right.evidence.turn_trigger
+    && left.evidence.harness_version === right.evidence.harness_version;
+}
+
+export function activityUnderQuery(params, context) {
+  if (!object(params)) invalid('activity_under params must be an object');
+  for (const name of Object.keys(params)) if (!['pids', 'homes'].includes(name)) invalid(`unknown field ${name}`);
+  if (!Array.isArray(params.pids)) invalid('pids must be an array');
+  if (params.pids.length > 1024) invalid('sessions.activity_under accepts at most 1024 pids');
+  const pids = params.pids.map((_, index) => {
+    const pid = treeUnsigned(params.pids, String(index));
+    if (pid == null || pid > 0xffffffffn) invalid('pids must contain unsigned 32-bit integers');
+    return Number(pid);
+  });
+  const query = sessionTreeQuery(Object.hasOwn(params, 'homes') ? { homes: params.homes } : {}, context);
+  return { pids, homes: query.homes, home: query.home };
+}
+
+/** Strongest live descendant at the root of the recorded parent chain. */
+export function codexDescendantActivity(statuses) {
+  const lineage = [...statuses].flatMap(([path, status]) => {
+    const header = treeRolloutHeader(path); return header == null ? [] : [{ ...header, status }];
+  });
+  const parents = new Map(lineage.filter(row => row.parent != null).map(row => [row.thread, row.parent]));
+  const result = new Map();
+  for (const row of lineage) {
+    if (row.parent == null) continue;
+    let root = row.parent; const seen = new Set();
+    while (!seen.has(root)) {
+      seen.add(root); if (!parents.has(root)) break; root = parents.get(root);
+    }
+    result.set(root, stronger(result.get(root), row.status));
+  }
+  return result;
+}
+
+/** Runtime evidence wins over stock evidence; absent ownership stays unknown. */
+export function sampledSessionActivity(locator, { claude, codex, codexTurns = new Map(), descendants, owned, hermes = new Map(), live = () => false, codexPath = locator.storage.path, observedAt = Date.now() }) {
+  const result = { harness: locator.harness, session_id: locator.session_id, presence: 'persisted', turn: 'unknown',
+    evidence: { source: 'persisted_store', native_state: null, observed_at_ms: observedAt, harness_version: null } };
+  const runtime = owned.get(key(locator));
+  if (runtime != null) {
+    result.presence = runtime === 'persisted' ? 'persisted' : runtime === 'shutting_down' ? 'shutting_down' : 'running';
+    result.turn = runtime === 'busy' ? 'working' : runtime === 'idle' ? 'idle' : 'unknown';
+    result.evidence.source = 'supercode_runtime'; result.evidence.native_state = runtime;
+    return result;
+  }
+  if (locator.harness === 'claude-code' && claude.has(locator.session_id)) {
+    const peer = claude.get(locator.session_id), status = peer.status === 'shell' ? 'idle' : peer.status;
+    result.presence = 'running'; result.evidence.source = 'claude_registry';
+    result.evidence.native_state = ['busy', 'idle', 'waiting'].includes(status) ? status : null;
+    result.turn = status === 'waiting' && peer.waitingFor === 'dialog open' ? 'unknown'
+      : ({ busy: 'working', idle: 'idle', waiting: 'needs_input' })[status] ?? 'unknown';
+    if (status === 'waiting' && peer.waitingFor != null) result.evidence.waiting_for = peer.waitingFor;
+    const since = treeUnsigned(peer, 'statusUpdatedAt');
+    if (since != null) setNativeInteger(result.evidence, 'native_state_since_ms', since);
+    result.evidence.harness_version = peer.version ?? null;
+  } else if (locator.harness === 'hermes' && hermes.has(locator.session_id)) {
+    const fire = hermes.get(locator.session_id), running = ['claimed', 'running'].includes(fire.status);
+    const proven = running && fire.pid != null && live(fire.pid);
+    result.presence = proven ? 'running' : 'persisted'; result.turn = proven ? 'working' : 'unknown';
+    result.evidence.source = 'hermes_executions';
+    result.evidence.native_state = running && !proven ? 'abandoned' : fire.status === 'succeeded' ? 'completed' : fire.status;
+  } else if (locator.harness === 'codex') {
+    const status = stronger(codex.get(codexPath), descendants.get(locator.session_id));
+    if (status != null) {
+      result.presence = 'running'; result.evidence.source = 'codex_rollout'; result.evidence.native_state = status;
+      result.turn = ({ busy: 'working', idle: 'idle', waiting: 'needs_input' })[status] ?? 'unknown';
+      if (result.turn === 'working') {
+        const turn = codexTurns.get(codexPath);
+        if (turn?.trigger != null) result.evidence.turn_trigger = turn.trigger;
+        const since = treeUnsigned(turn, 'started_at_ms');
+        if (since != null) setNativeInteger(result.evidence, 'native_state_since_ms', since);
+      }
+    }
+  }
+  return result;
+}

package/session-append-scan.mjs

@@ -1,31 +1,40 @@
 import { createHash } from 'node:crypto';
 
-export const EDGE_BYTES = 64 * 1024, VERIFY_MS = 10 * 60_000;
+export const EDGE_BYTES = 64 * 1024, CHECK_BYTES = 4 * 1024 * 1024;
 export const shortHash = (bytes) => createHash('sha256').update(bytes).digest('hex').slice(0, 24);
 
 /** What a pass over a file that is only added to keeps of where it read: the file, the bytes it read through (from
- * `from` to `bytes`, each given to `hashed` as it was read) and how the file stood when it stopped. The next read of
- * the same file takes only what was written since. */
+ * `from` to `bytes`, given to `took` as they were read) and how the file stood when it stopped. The next read of the
+ * same file takes only what was written since. The bytes read are kept as checks of at most CHECK_BYTES each (the
+ * hash of each run of whole lines), so that what was read is verified a bounded read at a time, never all at once. */
 export class AppendScan {
-  bytes = 0; from = 0; hashed = createHash('sha256'); stamp = null; edge = null; size = 0; verified = Date.now();
+  bytes = 0; from = 0; stamp = null; edge = null; size = 0;
+  checks = []; open = null; verifyAt = 0;
 
   constructor(reader) { this.device = reader.fingerprint.device; this.inode = reader.fingerprint.inode; }
 
+  /** A line's bytes, read through to `end`: added to the check being made, which closes at CHECK_BYTES. */
+  took(bytes, end) {
+    if (this.open == null) this.open = { from: end - bytes.length, hash: createHash('sha256') };
+    this.open.hash.update(bytes);
+    if (end - this.open.from >= CHECK_BYTES) { this.checks.push({ from: this.open.from, to: end, hash: this.open.hash.digest('hex') }); this.open = null; }
+  }
+
   /** Whether this is the scan of `reader`'s file: the same file, no shorter, its scanned bytes as they were. A file
-   * whose size and modification time are those last read is as it was. One that grew is an append while the last
-   * EDGE_BYTES the scan read are as they were (a bounded read), and is taken as one for at most VERIFY_MS after its
-   * bytes were last read through. Any other (written without growing, an edge that moved, or a growing file not read
-   * through for that long) is read through to where the scan stopped and compared by the hash of those bytes, no
-   * line decoded: a record rewritten in place, whatever its length, ends the scan and every mark made from it, at
-   * once when the file did not also grow, and within VERIFY_MS when it did. */
+   * whose size and modification time are those last read is as it was. Any other must still hold the last EDGE_BYTES
+   * the scan read, and one check of what it read, taken in turn from read to read, must hold too: a record rewritten
+   * in place, whatever its length, ends the scan and every mark made from it within as many reads as the scan has
+   * checks, each a bounded read (a scan of no more than one check is verified whole at every read). */
   async holds(reader) {
     if (reader.fingerprint.device !== this.device || reader.fingerprint.inode !== this.inode || reader.size < this.bytes) return false;
     if (this.unchanged(reader)) return true;
-    if (reader.size > this.size && Date.now() - this.verified < VERIFY_MS) return this.edge === await this.edgeOf(reader);
+    if (this.edge !== await this.edgeOf(reader)) return false;
+    const checks = this.open == null ? this.checks : [...this.checks, { from: this.open.from, to: this.bytes, hash: this.open.hash.copy().digest('hex') }];
+    if (!checks.length) return true;
+    const check = checks[this.verifyAt++ % checks.length];
     const hash = createHash('sha256');
-    for (let at = this.from; at < this.bytes;) { const block = await reader.read(at, Math.min(1024 * 1024, this.bytes - at)); hash.update(block); at += block.length; }
-    this.verified = Date.now();
-    return hash.digest('hex') === this.hashed.copy().digest('hex');
+    for (let at = check.from; at < check.to;) { const block = await reader.read(at, Math.min(1024 * 1024, check.to - at)); hash.update(block); at += block.length; }
+    return hash.digest('hex') === check.hash;
   }
 
   /** Whether the file's size and modification time are those this scan last read it at. */
@@ -36,9 +45,10 @@ export class AppendScan {
     return shortHash(await reader.read(from, this.bytes - from));
   }
 
-  /** The file as a pass that read on from `from` leaves it. */
-  async settle(reader, from) {
+  /** The file as a pass that read on from `from` leaves it. A pass that stopped before the file's last whole line
+   * (`behind`) leaves no stamp: the next read verifies and reads on. */
+  async settle(reader, from, behind = false) {
     if (this.bytes !== from || this.edge == null) this.edge = await this.edgeOf(reader);
-    this.size = reader.size; this.stamp = `${reader.fingerprint.size}:${reader.fingerprint.mtime_ns}`;
+    this.size = behind ? this.bytes : reader.size; this.stamp = behind ? null : `${reader.fingerprint.size}:${reader.fingerprint.mtime_ns}`;
   }
 }

package/session-branch-handoff.mjs

@@ -0,0 +1,115 @@
+// Frozen branch artifacts and handoff specifications. Neither door launches a
+// vendor or materializes its native store; the source residue cache is shared
+// with transfer. Cuts use a recorded user-message identity, never a view offset.
+import { resolve } from 'node:path';
+import { cloneNativeJson } from './native-json.mjs';
+import { normalizedSessionJson } from './session-model.mjs';
+import { loadSessionLocator } from './session-path.mjs';
+import { parseTransferLocator, transferTarget, sessionArtifact } from './session-transfer.mjs';
+import { freshSessionId } from './session-fresh-id.mjs';
+
+const fail = (message, rpcCode = -32602) => { throw Object.assign(new Error(message), { rpcCode }); };
+function struct(value, fields, name, required = fields.length) {
+  if (Array.isArray(value)) {
+    if (value.length < required || value.length > fields.length) fail(`${name} positional params require ${fields.join(', ')}`);
+    return Object.fromEntries(fields.map((field, at) => [field, value[at]]));
+  }
+  if (value == null || typeof value !== 'object') fail(`${name} must be an object`);
+  return value;
+}
+const string = (value, name) => { if (typeof value !== 'string') fail(`${name} must be a string`); return value; };
+function messageId(value) {
+  if (value == null) return null;
+  const id = struct(value, ['key', 'value'], 'before_message_id');
+  return { key: string(id.key, 'before_message_id.key'), value: string(id.value, 'before_message_id.value') };
+}
+function parseParams(value, handoff) {
+  const params = struct(value, handoff ? ['locator', 'target_harness', 'cwd', 'before_message_id']
+    : ['locator', 'target_harness', 'before_message_id'], handoff ? 'session handoff params' : 'session branch params', handoff ? 2 : 1);
+  const locator = parseTransferLocator(params.locator);
+  const target = !handoff && params.target_harness == null ? null : transferTarget(params.target_harness);
+  const cwd = handoff && params.cwd != null ? string(params.cwd, 'cwd') : null;
+  return { locator, target, cwd, before: messageId(params.before_message_id) };
+}
+
+function sessionBefore(session, id) {
+  if (id == null) return { session, cut: null };
+  if (id.key !== 'claude_uuid') fail(`${id.key} is not a per-message id supercode reads; a fork at a turn names a message by claude_uuid`, -32020);
+  const places = [];
+  for (const [at, message] of session.messages.entries()) {
+    if (message.role === 'user' && message.metadata[id.key] === id.value) places.push(at);
+    if (places.length === 2) break;
+  }
+  if (!places.length) fail(`no user message in this session has ${id.key} ${id.value}`, -32000);
+  if (places.length > 1) fail(`more than one user message has ${id.key} ${id.value}; it does not name one turn`, -32000);
+  const keep = places[0], messages = cloneNativeJson(session.messages.slice(0, keep));
+  const spawned = new Set(messages.flatMap(message => message.tool_calls ?? []).map(call => call.id));
+  const subagents = session.subagents.filter(child => child.meta.parent_tool_use_id != null && spawned.has(child.meta.parent_tool_use_id));
+  const meta = cloneNativeJson(session.meta);
+  // Other source headers/message records are retained as in Session::cut_before.
+  meta.native_residue = []; meta.native_residue_source = null; meta.codex_provenance = [];
+  return { cut: keep + 1, session: { ...session, meta, messages, subagents: cloneNativeJson(subagents),
+    raw: [], raw_trailing_newline: true, imported_message_count: null, raw_is_verbatim: false,
+    load_residue: [...session.load_residue] } };
+}
+async function loadBefore(params, context) {
+  context.signal?.throwIfAborted();
+  const locator = { ...params.locator, storage: { ...params.locator.storage,
+    path: resolve(context.cwd ?? process.cwd(), params.locator.storage.path) } };
+  const session = await loadSessionLocator(locator, { ...context, fidelity: 'byte_lossless', includeSubagents: true });
+  context.signal?.throwIfAborted();
+  return sessionBefore(session, params.before);
+}
+
+export async function branchSession(value, context = {}) {
+  const params = parseParams(value, false), { session, cut } = await loadBefore(params, context);
+  const { locator, target } = params;
+  const prefix = `Continue as a new branch from ${locator.harness} session ${locator.session_id}`;
+  const bootstrap_prompt = cut == null
+    ? `${prefix}. The frozen parent transcript is at ${locator.storage.path}. Read or load that parent for context, summarize the relevant state, then continue independently without mutating the parent session.`
+    : `${prefix}, forked before its message ${cut}. The frozen parent transcript is at ${locator.storage.path}. Read or load only what precedes message ${cut} for context, summarize the relevant state, then continue independently without mutating the parent session.`;
+  const artifact = target == null ? null : await sessionArtifact(locator, session, target, context);
+  return { parent: locator, session: normalizedSessionJson(session), bootstrap_prompt, artifact };
+}
+
+function handoffInstructions(target, sessionId, cwd) {
+  const launch = (program, args) => ({ cwd, program, arguments: args, env: {} });
+  let program, args, materialize = null, note;
+  switch (target) {
+    case 'claude-code':
+      program = 'claude'; args = ['--resume', sessionId];
+      note = "Write the artifact into Claude Code's native project session store before running the resume launch; Claude Code has no general transcript-import command."; break;
+    case 'hermes':
+      program = 'hermes'; args = ['--resume', sessionId];
+      note = 'Hand the artifact (a Codex rollout) to `hermes sessions import --from codex <file>` — `sessions.export --to hermes` does exactly that — and resume the id Hermes prints: Hermes mints its own id and writes its own store.'; break;
+    case 'codex':
+      program = 'codex'; args = ['resume', sessionId];
+      note = "Write the artifact into Codex's native rollout store before running the resume launch; Codex has no general transcript-import command."; break;
+    case 'opencode':
+      program = 'opencode'; args = ['--session', sessionId]; materialize = launch('opencode', ['import', '{artifact_path}']);
+      note = 'Write the artifact to a file, run the materialize command with its path, then launch the imported session.'; break;
+    case 'pi':
+      program = 'pi'; args = ['--session', '{artifact_path}'];
+      note = 'Write the artifact to a file and replace {artifact_path} in the launch arguments; Pi can resume that file directly.'; break;
+    case 'grok':
+      program = 'grok'; args = ['--resume', '{materialized_session_id}'];
+      note = "Grok has no import command. Materialize the artifact through `harness.v1.sessions.materialize` (target `grok`, `value_lossless`, the destination cwd): it writes Grok's store entry (`chat_history.jsonl` and the `summary.json` `--resume` requires) under a fresh id; replace {materialized_session_id} with the id it returns."; break;
+    case 'gemini':
+      program = 'gemini'; args = ['--session-file', '{artifact_path}'];
+      note = "Write the Gemini JSONL artifact to a file and replace {artifact_path}; Gemini imports it into the current project's chat store before opening the continuation."; break;
+    case 'goose':
+      program = 'goose'; args = ['session', '--resume', '--session-id', '{imported_session_id}'];
+      materialize = launch('goose', ['session', 'import', '{artifact_path}']);
+      note = 'Write the Goose JSON artifact to a file, run the materialize command, read the imported session id from its output, replace {imported_session_id}, then resume that native Goose session.'; break;
+    default: throw new TypeError(`unknown transfer target: ${target}`);
+  }
+  return { launch: launch(program, args), materialize, requires_materialization: true, note };
+}
+
+export async function handoffSession(value, context = {}) {
+  const params = parseParams(value, true), { session } = await loadBefore(params, context);
+  const fresh = freshSessionId(), id = params.target === 'opencode' ? `ses_${fresh.replaceAll('-', '')}` : fresh;
+  const artifact = await sessionArtifact(params.locator, session, params.target, context, id);
+  if (artifact.session_id == null) fail('handoff artifact omitted target session identity', -32000);
+  return { artifact, ...handoffInstructions(params.target, artifact.session_id, params.cwd ?? session.meta.cwd ?? '.') };
+}