@volter/supercode-interchange 0.1.22 → 0.1.24

package/jobs-read.mjs

@@ -0,0 +1,198 @@
+// Observed job rows, shared by public reads and harness-owned mutation readback.
+// This reader neither starts a scheduler nor writes.
+import { existsSync, readFileSync, readdirSync, statSync, realpathSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { resolveHarnessHomes } from './homes.mjs';
+import { hermesJobRecords, hermesJobValues } from './hermes-read-validation.mjs';
+import { readOpenclawRunHome } from './openclaw-profile-home.mjs';
+import { loadSessionPath } from './session-path.mjs';
+import { readUncompressedJsonl } from './jsonl.mjs';
+import { claudeRuntimeManifest } from './session-claude-runtime.mjs';
+import { childPath, directoryEntries, isDirectory, jsonl } from './session-spend-files.mjs';
+import { profilePathJoin as join, profilePathParent as parent } from './profile-paths.mjs';
+import { descriptorOrder } from './query.mjs';
+import { nativeDuplicateObjectKeys, nativeInteger, parseNativeJson, setNativeFloat, stringifyNativeJsonMember } from './native-json.mjs';
+import { openclawJobs } from './openclaw-jobs-read.mjs';
+
+export const JOB_HARNESSES = Object.freeze(['claude-code', 'hermes', 'openclaw', 'orchestrator']);
+const scanLimit = 200;
+const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+const object = value => value != null && typeof value === 'object' && !Array.isArray(value);
+const string = value => typeof value === 'string' ? value : null;
+const display = path => Buffer.isBuffer(path) ? path.toString('utf8') : path;
+const compare = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+const filesystem = (path, cwd) => !display(path).length || isAbsolute(display(path)) || process.platform === 'win32' && /^[A-Za-z]:/u.test(display(path)) ? path : childPath(cwd, path);
+const refuse = (message, rpcCode = -32602) => { throw Object.assign(new Error(message), { rpcCode }); };
+function struct(value, fields, name) {
+  if (Array.isArray(value)) {
+    if (value.length > fields.length) refuse(`${name} has too many fields`);
+    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) {
+  const selected = struct(params, get ? ['harness', 'id', 'homes'] : ['harness', 'session', 'profile', 'homes'], 'jobs params');
+  for (const key of get ? ['harness', 'id'] : ['harness', 'session', 'profile']) if (get ? typeof selected[key] !== 'string' : selected[key] != null && typeof selected[key] !== 'string') refuse(`${key} must be a string`);
+  const homes = resolveHarnessHomes(context.env);
+  if (Object.hasOwn(selected, 'homes')) {
+    const supplied = struct(selected.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 (selected.harness != null && !JOB_HARNESSES.includes(selected.harness)) refuse(`\`${selected.harness}\` has no scheduled jobs; \`jobs.${get ? 'get' : 'list'}\` is supported for: ${JOB_HARNESSES.join(', ')}`, -32020);
+  return { ...selected, harness: selected.harness ?? null, session: get ? null : selected.session ?? null, profile: get ? null : selected.profile ?? null, homes };
+}
+const source = (harness, path, state, profile = null, detail = null) => ({ harness, path: display(path), state, profile, sessions_scanned: null, scan_limit: null, detail });
+export function jobFloat(value, trim = false) {
+  if (trim && Math.abs(value % 1) < Number.EPSILON) {
+    const low = -(1n << 63n), high = (1n << 63n) - 1n;
+    return String(value <= Number(low) ? low : value >= Number(high) ? high : BigInt(Math.trunc(value)));
+  }
+  if (Object.is(value, -0)) return '-0';
+  const text = String(value), match = /^(-?)(\d+)(?:\.(\d+))?e([+-]?\d+)$/u.exec(text);
+  if (!match) return text;
+  const digits = match[2] + (match[3] ?? ''), at = match[2].length + Number(match[4]);
+  return match[1] + (at <= 0 ? `0.${'0'.repeat(-at)}${digits}` : at >= digits.length ? digits + '0'.repeat(at - digits.length) : `${digits.slice(0, at)}.${digits.slice(at)}`);
+}
+export function jobPayload(record) {
+  const payload = record?.payload, text = keys => keys.map(key => string(payload?.[key])).find(value => value != null);
+  const native = text(['kind', 'type']) ?? ['payloadKind', 'payload_kind'].map(key => string(record?.[key])).find(value => value != null);
+  const names = { systemEvent: 'system_event', system_event: 'system_event', message: 'prompt', prompt: 'prompt', agentTurn: 'prompt', agent_turn: 'prompt', command: 'command', script: 'script' };
+  const has = key => payload != null && Object.hasOwn(Object(payload), key) || record != null && Object.hasOwn(Object(record), key);
+  return { kind: names[native] ?? (has('systemEvent') ? 'system_event' : has('command') ? 'command' : has('script') ? 'script' : 'prompt'), text: text(['text', 'message', 'command', 'script']) ?? ['message', 'command', 'script'].map(key => string(record?.[key])).find(value => value != null) ?? null };
+}
+export function projectJob(harness, profile, job) {
+  const raw = job.raw, kind = job.schedule.kind;
+  const schedule = { kind, expr: kind === 'cron' ? job.schedule.expr : null, minutes: null, run_at: kind === 'once' ? job.schedule.run_at : null,
+    display: kind === 'cron' ? job.schedule.expr : kind === 'once' ? `once @${job.schedule.run_at}` : `every ${jobFloat(job.schedule.minutes, true)} min` };
+  if (kind === 'interval') setNativeFloat(schedule, 'minutes', job.schedule.minutes);
+  const delivery = object(raw.__delivery) ? raw.__delivery : null, d = key => string(delivery?.[key]);
+  const target = job.deliver, explicit = target.kind === 'explicit';
+  const rendered = explicit ? target.platform + (target.chat_id == null ? '' : `:${target.chat_id}${target.thread_id == null ? '' : `:${target.thread_id}`}`) : target.kind;
+  return { id: job.id, harness, scope: 'install', profile: harness === 'openclaw' ? string(Object.hasOwn(raw, 'agentId') ? raw.agentId : raw.agent_id) ?? profile : profile, session_id: null, schedule,
+    payload: Object.hasOwn(raw, '__payload') ? jobPayload({ payload: raw.__payload }) : typeof raw.script === 'string' ? { kind: 'script', text: raw.script } : { kind: 'prompt', text: job.prompt },
+    session_target: job.session_target, deliver: { target: harness === 'openclaw' ? d('channel') : rendered, chat_id: d('to') ?? job.origin?.chat_id ?? (explicit ? target.chat_id : null), thread_id: d('threadId') ?? job.origin?.thread_id ?? (explicit ? target.thread_id : null), account: d('accountId'), mode: d('mode') },
+    enabled: job.enabled, state: job.enabled ? 'active' : 'paused', next_run_at: job.next_run_at, last_run_at: job.last_run_at, last_status: job.last_status, last_delivery_error: string(raw.last_delivery_error), created_at: job.created_at, recurring: kind !== 'once' };
+}
+function stores(harness, homes, cwd) {
+  if (harness === 'openclaw') return [{ path: join(homes.openclaw, 'state/openclaw.sqlite'), profile: null }, { path: join(homes.openclaw, 'cron/jobs.json'), profile: null }];
+  const root = harness === 'hermes' ? parent(homes.hermes) ?? '.' : homes.orchestrator;
+  if (harness === 'orchestrator' && !isDirectory(filesystem(root, cwd))) return [];
+  const result = [{ path: join(root, 'cron/jobs.json'), profile: null }], profiles = join(root, 'profiles');
+  try {
+    const named = readdirSync(filesystem(profiles, cwd), { encoding: 'buffer' }).flatMap(name => {
+      const text = harness === 'hermes' ? name.toString('utf8') : (() => { try { return utf8.decode(name); } catch { return null; } })();
+      const path = childPath(profiles, name);
+      if (harness === 'orchestrator') { if (!statSync(filesystem(path, cwd)).isDirectory()) return []; }
+      else if (!isDirectory(filesystem(path, cwd))) return [];
+      if (text == null || text.startsWith('.') || harness === 'hermes' && text === 'node_modules') return [];
+      return [{ path: childPath(path, 'cron/jobs.json'), profile: harness === 'orchestrator' && text === 'default' ? null : text, sort: text }];
+    }).sort((a, b) => compare(a.sort, b.sort)); result.push(...named);
+  } catch (error) { if (harness === 'orchestrator' && !['ENOENT', 'ENOTDIR'].includes(error.code)) return []; }
+  return result;
+}
+function folderJobs(harness, selected, context) {
+  const jobs = [], sources = [];
+  for (const store of stores(harness, selected.homes, context.cwd)) {
+    const path = filesystem(store.path, context.cwd);
+    if (!existsSync(path)) { sources.push(source(harness, store.path, 'absent_store', store.profile)); continue; }
+    try {
+      const value = parseNativeJson(utf8.decode(readFileSync(path))), decoded = hermesJobRecords(display(store.path), value), rows = hermesJobValues(display(store.path), value);
+      const byId = new Map(rows.map(row => [row.id, row]));
+      for (const id of [...decoded.keys()].sort(compare)) {
+        const raw = byId.get(id), job = decoded.get(id);
+        jobs.push(projectJob(harness, store.profile, { ...job, raw, schedule: raw.schedule, prompt: raw.prompt ?? null, session_target: raw.session_target ?? null, enabled: raw.enabled ?? true, next_run_at: raw.next_run_at ?? null, last_run_at: raw.last_run_at ?? null, last_status: raw.last_status ?? null, created_at: raw.created_at ?? null }));
+      }
+      sources.push(source(harness, store.path, 'read', store.profile));
+    } catch (error) { sources.push(source(harness, store.path, 'unreadable', store.profile, error.message)); }
+  }
+  return { jobs, sources };
+}
+async function claudeLocators(selected, context) {
+  const root = filesystem(selected.homes.claude_code, context.cwd), files = [], walked = new Set();
+  function walk(dir) {
+    let real; try { real = realpathSync(dir); } catch { real = display(dir); }
+    if (walked.has(real)) return; walked.add(real);
+    for (const entry of directoryEntries(dir)) {
+      if (isDirectory(entry.path)) { if (!entry.name.equals(Buffer.from('subagents'))) walk(entry.path); }
+      else { try { if (statSync(entry.path).isFile() && jsonl(entry.name)) files.push(entry.path); } catch { /* refused native directory entry */ } }
+    }
+  }
+  walk(root);
+  const found = [];
+  for (const file of files) { try { const read = await readUncompressedJsonl(display(file), 'claude-code'); if (read.result?.descriptor && (read.result.state.header.session_id != null || read.result.state.header.cwd != null)) found.push(read.result.descriptor); } catch { /* native metadata skips unreadable headers */ } }
+  // The native scan excludes child directories, then projects header parents.
+  const rows = found.filter(row => row.parent_session_id == null).sort(descriptorOrder);
+  return (selected.session == null ? rows.slice(0, scanLimit) : rows.filter(row => row.locator.session_id === selected.session)).map(row => row.locator);
+}
+function marker(path) {
+  let bytes; try { bytes = readFileSync(path); } catch { return false; }
+  let from = 0;
+  for (let at = 0; at <= bytes.length; at++) if (at === bytes.length || bytes[at] === 10) {
+    let line; try { line = utf8.decode(bytes.subarray(from, at)); } catch { return false; } from = at + 1;
+    if (line.includes('CronCreate') || line.includes('ScheduleWakeup')) return true;
+  }
+  return false;
+}
+function claudeJob(session, record, wake) {
+  return { id: wake ? record.tool_use_id : record.id, harness: 'claude-code', scope: 'session', profile: null, session_id: session,
+    schedule: { kind: wake ? 'once' : 'cron', expr: wake ? null : record.schedule, minutes: null, run_at: wake ? record.scheduled_for : null, display: wake ? `once, +${nativeInteger(record, 'delay_seconds') ?? record.delay_seconds}s` : record.schedule },
+    payload: { kind: wake ? 'wakeup' : 'prompt', text: wake ? record.prompt ?? record.reason : record.prompt }, session_target: null, deliver: { target: 'session', chat_id: null, thread_id: null, account: null, mode: null }, enabled: true, state: wake ? 'pending' : 'active', next_run_at: wake ? record.scheduled_for : null, last_run_at: null, last_status: null, last_delivery_error: null, created_at: record.created_at, recurring: wake ? false : record.recurring };
+}
+async function claudeJobs(selected, context) {
+  const locators = await claudeLocators(selected, context), jobs = [], sources = [];
+  for (const locator of locators) {
+    if (!marker(locator.storage.path)) continue;
+    let loaded; try { loaded = await loadSessionPath(locator.storage.path, { ...context, fidelity: 'byte_lossless', includeSubagents: true }); }
+    catch { sources.push(source('claude-code', locator.storage.path, 'unreadable', null, 'session could not be loaded')); continue; }
+    const manifest = claudeRuntimeManifest(loaded);
+    jobs.push(...manifest.active_crons.map(record => claudeJob(locator.session_id, record, false)), ...manifest.pending_wakeups.map(record => claudeJob(locator.session_id, record, true)));
+  }
+  sources.push({ ...source('claude-code', selected.homes.claude_code, 'scanned'), sessions_scanned: locators.length, scan_limit: selected.session == null ? scanLimit : null });
+  return { jobs, sources };
+}
+function openJobs(selected, context) {
+  const path = join(selected.homes.openclaw, 'state/openclaw.sqlite'), legacy = join(selected.homes.openclaw, 'cron/jobs.json'), jobs = [], sources = [];
+  if (!existsSync(filesystem(path, context.cwd))) sources.push(source('openclaw', path, 'absent_store'));
+  else try {
+    const profiles = openclawJobs(readOpenclawRunHome(filesystem(selected.homes.openclaw, context.cwd)));
+    for (const [name, records] of [...profiles].sort(([a], [b]) => (a !== 'default') - (b !== 'default') || compare(a, b))) {
+      for (const id of [...records.keys()].sort(compare)) jobs.push(projectJob('openclaw', name === 'default' ? null : name, records.get(id)));
+    }
+    sources.push(source('openclaw', path, 'read'));
+  } catch (error) { sources.push(source('openclaw', path, 'unreadable', null, error.message)); }
+  sources.push(source('openclaw', legacy, existsSync(filesystem(legacy, context.cwd)) ? 'read' : 'absent_store'));
+  return { jobs, sources };
+}
+async function collect(selected, context) {
+  const jobs = [], sources = [];
+  for (const harness of JOB_HARNESSES) if (selected.harness == null || selected.harness === harness) {
+    const read = harness === 'claude-code' ? await claudeJobs(selected, context) : harness === 'openclaw' ? openJobs(selected, context) : folderJobs(harness, selected, context);
+    jobs.push(...read.jobs); sources.push(...read.sources);
+  }
+  return { jobs: jobs.filter(job => (selected.session == null || job.session_id === selected.session) && (selected.profile == null || job.profile === selected.profile)), sources };
+}
+function rawRecords(path) { try { const value = parseNativeJson(utf8.decode(readFileSync(path))); return Array.isArray(value) ? value : Array.isArray(value?.jobs) ? value.jobs : []; } catch { return []; } }
+export async function listJobs(params, { env = process.env, cwd = process.cwd() } = {}) {
+  const context = { env, cwd }; return collect(query(params, context, false), context);
+}
+export async function getJob(params, { env = process.env, cwd = process.cwd() } = {}) {
+  const context = { env, cwd }, selected = query(params, context, true), job = (await collect(selected, context)).jobs.find(job => job.id === selected.id);
+  if (!job) refuse(`\`${selected.harness}\` has no scheduled job \`${selected.id}\``, -32000);
+  let raw = null;
+  if (job.harness === 'claude-code') {
+    for (const locator of await claudeLocators({ ...selected, session: job.session_id }, context)) try {
+      const manifest = claudeRuntimeManifest(await loadSessionPath(locator.storage.path, { ...context, fidelity: 'byte_lossless', includeSubagents: true }));
+      raw = manifest.active_crons.find(record => record.id === job.id) ?? manifest.pending_wakeups.find(record => record.tool_use_id === job.id) ?? null;
+      if (raw != null) break;
+    } catch { /* native raw read keeps trying selected locators */ }
+  } else for (const store of stores(job.harness, selected.homes, cwd)) {
+    raw = rawRecords(filesystem(store.path, cwd)).find(record => ['id', 'job_id', 'jobId'].map(key => string(record?.[key])).find(id => id != null) === job.id) ?? null;
+    if (raw != null) break;
+  }
+  return { job, source: raw };
+}

package/jsonl.mjs

@@ -1,6 +1,6 @@
 import { basename, dirname, extname } from 'node:path';
 import { withSessionFile, readHeaderRecords, parseJsonLine, visitAppendedLines, sameFingerprint, appendableFingerprint } from './file-io.mjs';
-import { finalizeNouns, headerFacts, headerComplete, readTailFacts, foldTailRecord, finishAppendedFacts } from './metadata.mjs';
+import { finalizeNouns, headerFacts, headerComplete, readTailFacts, foldTailRecord, finishAppendedFacts, claudeSessionName, carryNames } from './metadata.mjs';
 import { readCompressedCodexHeader } from './compressed.mjs';
 
 /** A cold suffix is kept only when the final line is unfinished. A partial
@@ -35,7 +35,8 @@ async function descriptor(path, harness, reader, header, facts, nativeTopic) {
   // the parent from discovery. It is named by its own file, under its parent.
   const subagentOf = harness === 'claude-code' && basename(dirname(path)) === 'subagents' ? basename(dirname(dirname(path))) : null;
   const sessionId = subagentOf ? basename(path, extname(path)) : header.session_id ?? basename(path, extname(path));
-  let title = header.title ?? header.topic;
+  // A rename or a newer topic is written after the header froze: the tail's names stand before the header's.
+  let title = harness === 'claude-code' ? claudeSessionName(facts, header) : header.title ?? header.topic;
   if (title == null && harness === 'codex') {
     if (typeof nativeTopic !== 'function') throw new Error('Codex metadata requires its native thread-name source');
     title = await nativeTopic(path, sessionId);
@@ -123,6 +124,6 @@ export async function advanceMetadataTail(reader, harness, old) {
   }
   // The old EOF record may have been valid before the appended bytes changed
   // it. Its predecessor is not implied by the cached newest-record facts.
-  const nextFacts = old.trailing ? await readTailFacts(reader, harness) : await finishAppendedFacts(reader, harness, old.facts, facts);
+  const nextFacts = carryNames(old.trailing ? await readTailFacts(reader, harness) : await finishAppendedFacts(reader, harness, old.facts, facts), facts);
   return { facts: nextFacts, ...suffix };
 }

package/memory-show.mjs

@@ -0,0 +1,187 @@
+// Recorded prose only. The search engine and every harness mutation have
+// separate owners; listing reads the same selected stores as the native noun.
+import { openSync, readSync, closeSync, statSync, readdirSync, existsSync, readFileSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { userInfo } from 'node:os';
+import { resolveHarnessHomes } from './homes.mjs';
+import { profilePathJoin as join, profilePathParent as parent } from './profile-paths.mjs';
+import { childPath } from './session-spend-files.mjs';
+import { listProfiles } from './profiles-read.mjs';
+import { parseNativeJson, setNativeInteger } from './native-json.mjs';
+import { nativeTrim, truncateScalars } from './text.mjs';
+import { usageMoment } from './session-usage-time.mjs';
+
+export const MEMORY_HARNESSES = Object.freeze(['claude-code', 'hermes', 'openclaw']);
+const bytes = 1024 * 1024, documents = 512, depthLimit = 4;
+const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+const display = path => Buffer.isBuffer(path) ? path.toString('utf8') : path;
+const compare = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+const directory = path => { try { return statSync(path).isDirectory(); } catch { return false; } };
+const file = path => { try { return statSync(path).isFile(); } catch { return false; } };
+const invalid = message => { throw Object.assign(new Error(message), { rpcCode: -32602 }); };
+const unsupported = message => { throw Object.assign(new Error(message), { rpcCode: -32020 }); };
+const object = value => value != null && typeof value === 'object' && !Array.isArray(value);
+function struct(value, keys, name) {
+  if (Array.isArray(value)) {
+    if (value.length > keys.length) invalid(`${name} has too many fields`);
+    return Object.fromEntries(value.map((entry, at) => [keys[at], entry]));
+  }
+  if (!object(value)) invalid(`${name} must be a struct`);
+  return value;
+}
+function query(params, context) {
+  const value = struct(params, ['harness', 'query', 'profile', 'session', 'full', 'regex', 'cwd', 'homes'], 'memory params');
+  for (const key of ['harness', 'query', 'profile', 'session', 'cwd']) if (value[key] != null && typeof value[key] !== 'string') invalid(`${key} must be a string`);
+  for (const key of ['full', 'regex']) if (Object.hasOwn(value, key) && typeof value[key] !== 'boolean') invalid(`${key} must be a boolean`);
+  const homes = resolveHarnessHomes(context.env);
+  if (Object.hasOwn(value, 'homes')) {
+    const selected = struct(value.homes, Object.keys(homes), 'homes');
+    for (const key of Object.keys(homes)) if (Object.hasOwn(selected, key)) {
+      if (typeof selected[key] !== 'string') invalid(`homes.${key} must be a string`);
+      homes[key] = selected[key];
+    }
+  }
+  if (value.harness == null) invalid('`harness` is required');
+  if (!MEMORY_HARNESSES.includes(value.harness)) unsupported(`harness \`${value.harness}\` has no memory store (memory exists for: ${MEMORY_HARNESSES.join(', ')})`);
+  if (value.session != null && value.harness !== 'claude-code') unsupported(`\`${value.harness}\` scopes memory by profile, not by session — drop \`session\` or use \`profile\``);
+  return { ...value, homes, full: value.full ?? false };
+}
+function selectedFile(path, cwd) {
+  const text = display(path);
+  if (!text.length || isAbsolute(text) || process.platform === 'win32' && /^[A-Za-z]:/u.test(text)) return path;
+  return childPath(cwd, path);
+}
+function entries(path, cwd) {
+  try { return readdirSync(selectedFile(path, cwd), { encoding: 'buffer' }).map(name => childPath(path, name)).sort(compare); }
+  catch { return []; }
+}
+function leaf(path) {
+  const trailing = process.platform === 'win32' ? /[\\/]+$/u : /\/+$/u;
+  let text = display(path).replace(trailing, '');
+  while (text.endsWith('/.') || process.platform === 'win32' && text.endsWith('\\.')) text = text.slice(0, -2).replace(trailing, '');
+  const name = text.slice(Math.max(text.lastIndexOf('/'), process.platform === 'win32' ? text.lastIndexOf('\\') : -1) + 1);
+  return !name || name === '.' || name === '..' || process.platform === 'win32' && /^[A-Za-z]:$/u.test(name) ? null : name;
+}
+function store(harness, scope, profile, root, files, directories) { return { harness, scope, profile, root, files: files.map(name => join(root, name)), directories: directories.map(name => name ? join(root, name) : root) }; }
+function unknown(harness, profile) { invalid(`\`${harness}\` has no memory store for \`${profile}\``); }
+function claude(query, context) {
+  let project;
+  if (query.profile != null) {
+    project = isAbsolute(query.profile) ? query.profile : join(query.homes.claude_code, query.profile);
+    if (!directory(selectedFile(project, context.cwd))) unknown(query.harness, query.profile);
+  } else if (query.session != null) {
+    project = entries(query.homes.claude_code, context.cwd).find(path => directory(selectedFile(path, context.cwd)) && file(selectedFile(join(path, `${query.session}.jsonl`), context.cwd)));
+    if (project == null) invalid(`no Claude Code project directory holds session \`${query.session}\``);
+    project = display(project);
+  } else {
+    const cwd = query.cwd ?? context.cwd; let enclosing = cwd;
+    for (let ancestor = cwd; ancestor != null; ancestor = parent(ancestor)) if (existsSync(selectedFile(join(ancestor, '.git'), context.cwd))) { enclosing = ancestor; break; }
+    project = join(query.homes.claude_code, [...enclosing].map(char => /^[A-Za-z0-9]$/u.test(char) ? char : '-').join(''));
+  }
+  const nested = join(project, 'memory'), root = directory(selectedFile(nested, context.cwd)) ? nested : project;
+  return directory(selectedFile(root, context.cwd)) ? [store('claude-code', 'project', leaf(project), root, ['MEMORY.md'], [''])] : [];
+}
+function hermes(query, context) {
+  const home = parent(query.homes.hermes); if (home == null) return [];
+  let wanted = [['default', home], ...entries(join(home, 'profiles'), context.cwd).filter(path => directory(selectedFile(path, context.cwd))).map(path => [leaf(path), display(path)]).sort((a, b) => compare(a[0], b[0]) || compare(a[1], b[1]))];
+  if (query.profile != null) { wanted = wanted.filter(([name]) => name === query.profile); if (!wanted.length) unknown('hermes', query.profile); }
+  return wanted.filter(([, path]) => directory(selectedFile(path, context.cwd))).map(([name, path]) => store('hermes', name === 'default' ? 'user' : 'profile', name, path, ['MEMORY.md', 'USER.md'], ['memories']));
+}
+// memory's native profiles::read_json5 removes comments/trailing commas only.
+// Its workspace projection does not accept the codec's broader key/quote forms.
+function stripJson5(text) {
+  const chars = [...text]; let out = '', quoted = false, escaped = false;
+  for (let at = 0; at < chars.length; at++) {
+    const ch = chars[at];
+    if (quoted) { out += ch; if (escaped) escaped = false; else if (ch === '\\') escaped = true; else if (ch === '"') quoted = false; continue; }
+    if (ch === '"') { quoted = true; out += ch; }
+    else if (ch === '/' && chars[at + 1] === '/') { while (++at < chars.length) if (chars[at] === '\n') { out += '\n'; break; } }
+    else if (ch === '/' && chars[at + 1] === '*') { at++; let previous = '\0'; while (++at < chars.length) { if (previous === '*' && chars[at] === '/') break; previous = chars[at]; } out += ' '; }
+    else out += ch;
+  }
+  const scanned = [...out]; let cleaned = ''; quoted = false; escaped = false;
+  for (let at = 0; at < scanned.length; at++) {
+    const ch = scanned[at];
+    if (quoted) { cleaned += ch; if (escaped) escaped = false; else if (ch === '\\') escaped = true; else if (ch === '"') quoted = false; continue; }
+    if (ch === '"') quoted = true;
+    if (ch === ',') { let next = at + 1; while (scanned[next] != null && nativeTrim(scanned[next]) === '') next++; if (['}', ']'].includes(scanned[next])) continue; }
+    cleaned += ch;
+  }
+  return cleaned;
+}
+function configuredWorkspace(home, agent, context) {
+  let doc; try { doc = parseNativeJson(stripJson5(utf8.decode(readFileSync(selectedFile(join(home, 'openclaw.json'), context.cwd))))); } catch { return null; }
+  const entry = (Array.isArray(doc?.agents?.list) ? doc.agents.list.find(item => item?.id === agent) : null) ?? doc?.agents?.entries?.[agent];
+  if (typeof entry?.workspace !== 'string') return null;
+  const workspace = nativeTrim(entry.workspace); if (!workspace) return null;
+  if (workspace.startsWith('~/')) {
+    let home = context.env.HOME || (process.platform === 'win32' && context.env.USERPROFILE);
+    if (!home) { try { home = userInfo().homedir; } catch { /* no home fallback */ } }
+    if (home) return join(home, workspace.slice(2));
+  }
+  return workspace;
+}
+function openclaw(query, context) {
+  const home = query.homes.openclaw;
+  let wanted; try { wanted = listProfiles({ homes: query.homes, harness: 'openclaw' }, context).profiles.map(row => [row.name, row.default]); } catch { wanted = []; }
+  if (!wanted.length) wanted = [['main', true]];
+  else if (!wanted.some(([, defaults]) => defaults)) { const main = wanted.findIndex(([name]) => name === 'main'); wanted[main < 0 ? 0 : main][1] = true; }
+  if (query.profile != null) { wanted = wanted.filter(([name]) => name === query.profile); if (!wanted.length) unknown('openclaw', query.profile); }
+  return wanted.flatMap(([name, defaults]) => {
+    let root = configuredWorkspace(home, name, context);
+    if (root == null && !defaults) root = join(home, `workspace-${name}`);
+    if (root == null && context.env.OPENCLAW_WORKSPACE_DIR) root = context.env.OPENCLAW_WORKSPACE_DIR;
+    const profile = nativeTrim(context.env.OPENCLAW_PROFILE ?? '');
+    root ??= join(home, profile && profile !== 'default' ? `workspace-${profile}` : 'workspace');
+    return directory(selectedFile(root, context.cwd)) ? [store('openclaw', 'agent', name, root, ['MEMORY.md', 'DREAMS.md', 'dreams.md'], ['memory'])] : [];
+  });
+}
+function walk(path, depth, out, cwd) {
+  if (depth >= depthLimit || out.length >= documents) return;
+  for (const child of entries(path, cwd)) {
+    if (out.length >= documents) return;
+    const name = leaf(child); if (name?.startsWith('.')) continue;
+    if (directory(selectedFile(child, cwd))) walk(child, depth + 1, out, cwd);
+    else if (/\.(md|markdown|txt)$/i.test(name ?? '')) out.push(child);
+  }
+}
+function paths(store, cwd) {
+  const out = store.files.filter(path => file(selectedFile(path, cwd)));
+  for (const path of store.directories) {
+    const found = []; walk(path, 0, found, cwd); found.sort(compare);
+    for (const path of found) if (!out.some(existing => Buffer.from(existing).equals(Buffer.from(path)))) out.push(path);
+  }
+  return out;
+}
+function memoryLines(text) {
+  if (!text) return [];
+  const lines = text.split('\n'); if (lines.at(-1) === '') lines.pop();
+  return lines.map((line, at) => (at < lines.length - 1 || text.endsWith('\n')) && line.endsWith('\r') ? line.slice(0, -1) : line);
+}
+const clip = line => { const trimmed = line.replace(/[\u0009-\u000d\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]+$/u, ''); return [...trimmed].length <= 200 ? trimmed : truncateScalars(trimmed, 200) + '…'; };
+function read(path) {
+  let fd;
+  try {
+    fd = openSync(path, 'r'); const buffer = Buffer.alloc(bytes); let used = 0;
+    while (used < bytes) { const count = readSync(fd, buffer, used, bytes - used, null); if (!count) break; used += count; }
+    return utf8.decode(buffer.subarray(0, used));
+  } catch { return null; }
+  finally { if (fd != null) closeSync(fd); }
+}
+function document(store, path, full, cwd) {
+  const actual = selectedFile(path, cwd); let info; try { info = statSync(actual, { bigint: true }); } catch { /* unknown metadata */ }
+  const text = read(actual), lines = text == null ? [] : memoryLines(text), preview = lines.slice(0, 5).map(clip);
+  const root = Buffer.from(store.root), source = Buffer.from(path), relative = source.subarray(root.length + Number(root.length && source[root.length] === (process.platform === 'win32' ? 92 : 47)));
+  const row = { name: relative.toString('utf8').replaceAll('\\', '/'), harness: store.harness, scope: store.scope, ...(store.profile == null ? {} : { profile: store.profile }), path: display(path) };
+  setNativeInteger(row, 'size', info?.size ?? 0n);
+  if (info?.mtimeNs >= 0n) row.updated_at = usageMoment(info.mtimeNs / 1000000n > (1n << 63n) - 1n ? (1n << 63n) - 1n : info.mtimeNs / 1000000n);
+  row.preview = preview; row.truncated = lines.length > preview.length || (info?.size ?? 0n) > BigInt(bytes);
+  if (full && text != null) row.content = text;
+  return row;
+}
+export function showMemory(params, { env = process.env, cwd = process.cwd() } = {}) {
+  const context = { env, cwd }, selected = query(params, context), stores = selected.harness === 'claude-code' ? claude(selected, context) : selected.harness === 'hermes' ? hermes(selected, context) : openclaw(selected, context);
+  const out = [];
+  for (const store of stores) for (const path of paths(store, cwd)) { if (out.length >= documents) return { schema: 'supercode.memory.v1', documents: out }; out.push(document(store, path, selected.full, cwd)); }
+  return { schema: 'supercode.memory.v1', documents: out };
+}

package/metadata.mjs

@@ -1,3 +1,4 @@
+import { basename, dirname } from 'node:path';
 import { tailRecords } from './file-io.mjs';
 import { nativeTrim } from './text.mjs';
 
@@ -53,11 +54,16 @@ export function recordTimestamp(record, harness) {
  * append-aware owner. Newest means the last valid stamped record in the file,
  * rather than the maximum clock across records or the file's mtime. */
 export async function readTailFacts(reader, harness) {
-  const facts = { last_turn_ms: null, model: null, clock_offset: null, model_offset: null };
+  const facts = { last_turn_ms: null, model: null, clock_offset: null, model_offset: null, ...(harness === 'claude-code' ? { ...UNNAMED } : {}) };
+  // A Claude session's names are looked for in at most the last 128 KiB, never in a subagent's transcript (it has none),
+  // and only once a whole batch of them is passed: one cut at the window's edge would name it by the wrong one.
+  const naming = harness === 'claude-code' && basename(dirname(reader.path ?? '')) !== 'subagents';
+  let named = !naming, batch = false;
   let window = Math.min(16 * 1024, reader.size);
   for (;;) {
     const from = reader.size - window;
     const bytes = await reader.read(from, window);
+    batch = false;
     for (const { value, start } of tailRecords(bytes, window < reader.size)) {
       if (facts.last_turn_ms == null) {
         facts.last_turn_ms = recordTimestamp(value, harness);
@@ -67,17 +73,52 @@ export async function readTailFacts(reader, harness) {
         facts.model = recordModel(value, harness);
         if (facts.model != null) facts.model_offset = from + start;
       }
-      if (facts.last_turn_ms != null && facts.model != null) break;
+      if (naming && !named) {
+        const name = recordName(value);
+        if (name != null) { facts[name.key] ??= name.value; batch = true; }
+        else if (batch) named = true;
+      }
+      if (facts.last_turn_ms != null && facts.model != null && named) break;
     }
-    if (facts.last_turn_ms != null || window >= reader.size || window >= 1024 * 1024) return { ...facts, scan_from: from };
+    const searching = !named && window < NAMING_BYTES;
+    if ((facts.last_turn_ms != null && !searching) || window >= reader.size || window >= 1024 * 1024) return { ...facts, scan_from: from };
     window = Math.min(window * 2, reader.size, 1024 * 1024);
   }
 }
 
+const NAMING_BYTES = 128 * 1024;
+const UNNAMED = Object.freeze({ agent_name: null, custom_title: null, ai_title: null });
+const NAMES = Object.freeze({ 'agent-name': ['agent_name', 'agentName'], 'custom-title': ['custom_title', 'customTitle'], 'ai-title': ['ai_title', 'aiTitle'] });
+
+/** A Claude session's names, as Claude Code writes them again in one batch as the session goes on (custom-title,
+ * ai-title, agent-name), so the newest of each stands near the end. An empty one is a name cleared, and stands. */
+function recordName(record) {
+  const name = NAMES[record?.type];
+  if (!name || typeof record[name[1]] !== 'string') return null;
+  return { key: name[0], value: nativeTrim(record[name[1]]) };
+}
+
+/** A Claude session's name as Claude Code lists it: its agent name, else its custom title, else its generated topic;
+ * each the newest the tail holds, else the first its header holds. */
+export function claudeSessionName(facts, header) {
+  const newest = (tail, head) => (tail ?? head ?? '') || null;
+  return newest(facts?.agent_name, header.agent_name) ?? newest(facts?.custom_title, header.custom_title) ?? newest(facts?.ai_title, header.topic);
+}
+
 export function foldTailRecord(facts, record, harness, start) {
   const clock = recordTimestamp(record, harness), model = recordModel(record, harness);
   if (clock != null) { facts.last_turn_ms = clock; facts.clock_offset = start; }
   if (model != null) { facts.model = model; facts.model_offset = start; }
+  if (harness === 'claude-code') {
+    const name = recordName(record);
+    if (name != null) facts[name.key] = name.value;
+  }
+}
+
+/** A full rescan of the tail that found no batch of names keeps those the appended lines carried. */
+export function carryNames(next, previous) {
+  for (const key of Object.keys(UNNAMED)) if (next[key] == null && previous?.[key] != null) next[key] = previous[key];
+  return next;
 }
 
 /** Reuse known positions only while the new native tail window contains them.
@@ -127,6 +168,7 @@ export function applyHeaderRecord(result, value, harness) {
   if (harness === 'claude-code') {
     fill(result, 'session_id', value?.sessionId); fill(result, 'cwd', value?.cwd);
     fill(result, 'title', value?.customTitle); fill(result, 'title', value?.agentName);
+    fill(result, 'custom_title', value?.customTitle); fill(result, 'agent_name', value?.agentName);
     if (value?.type === 'ai-title') fill(result, 'topic', value.aiTitle);
     fill(result, 'model', value?.message?.model);
   } else if (harness === 'codex') {

package/native-json.mjs

@@ -65,7 +65,7 @@ function numberFact(token) {
   return { value: decimalValue(token), kind: 'float' };
 }
 
-export function parseNativeJson(text) {
+function readNativeJson(text) {
   let at = 0;
   const white = () => { while (/[\x20\t\r\n]/.test(text[at] ?? '') && at < text.length) at++; };
   const takeString = () => {
@@ -84,7 +84,7 @@ export function parseNativeJson(text) {
     if (char === '[' || char === '{') {
       if (depth >= 127) invalid();
       const array = char === '[', result = array ? [] : Object.create(null);
-      const meta = { keys: [], numbers: new Map() };
+      const meta = { keys: [], numbers: new Map(), duplicates: [] };
       facts.set(result, meta);
       const end = array ? ']' : '}';
       at++; white();
@@ -99,6 +99,7 @@ export function parseNativeJson(text) {
         }
         const child = value(depth + 1);
         if (!Object.hasOwn(result, key)) meta.keys.push(key);
+        else meta.duplicates.push(key);
         result[key] = child.value;
         if (child.kind) meta.numbers.set(key, child); else meta.numbers.delete(key);
         white();
@@ -120,7 +121,33 @@ export function parseNativeJson(text) {
   };
   const result = value(0);
   white(); if (at !== text.length) invalid();
-  return result.value;
+  return result;
+}
+
+export function parseNativeJson(text) { return readNativeJson(text).value; }
+
+/** Preserve a scalar JSON number's native type when installing parsed metadata. */
+export function setNativeJsonText(destination, key, text) {
+  const parsed = readNativeJson(text);
+  if (parsed.kind === 'integer') setNativeInteger(destination, key, parsed.integer);
+  else if (parsed.kind === 'float') setNativeFloat(destination, key, parsed.value);
+  else Object.defineProperty(destination, key, { value: parsed.value, enumerable: true, writable: true, configurable: true });
+}
+
+/** Copy a member without rounding its native integer or erasing its float
+ * type. Nested values keep their existing facts; no payload clone is needed. */
+export function copyNativeJsonMember(destination, key, source, sourceKey = key) {
+  key = String(key); sourceKey = String(sourceKey);
+  const value = source[sourceKey], fact = facts.get(source)?.numbers.get(sourceKey);
+  if (fact && Object.is(value, fact.value)) {
+    if (fact.kind === 'integer') setNativeInteger(destination, key, fact.integer);
+    else setNativeFloat(destination, key, fact.value);
+    return;
+  }
+  const meta = facts.get(destination);
+  if (meta && !Object.hasOwn(destination, key)) meta.keys.push(key);
+  meta?.numbers.delete(key);
+  Object.defineProperty(destination, key, { value, enumerable: true, writable: true, configurable: true });
 }
 
 export function nativeObjectKeys(value) {
@@ -130,6 +157,22 @@ export function nativeObjectKeys(value) {
   return [...keys.filter((key) => Object.hasOwn(value, key)), ...Object.keys(value).filter((key) => !known.has(key))];
 }
 
+/** serde_json's insertion-ordered Map::remove swaps its last entry into the
+ * removed slot. Preserve that order and the remaining scalar number facts. */
+export function swapRemoveNativeJsonMember(value, key) {
+  const keys = nativeObjectKeys(value), index = keys.indexOf(key);
+  if (index < 0) return;
+  const last = keys.pop(); if (index < keys.length) keys[index] = last;
+  const meta = facts.get(value) ?? { numbers: new Map() };
+  meta.keys = keys; meta.numbers.delete(key); facts.set(value, meta);
+  delete value[key];
+}
+
+
+// Direct serde struct reads reject a repeated field; Value reads keep its
+// last value. The private parser fact lets typed readers preserve that split.
+export function nativeDuplicateObjectKeys(value) { return facts.get(value)?.duplicates ?? []; }
+
 // Transcript projections clone JSON before bounding strings or eliding media.
 // Keep the source's numeric tokens and insertion order with those values.
 export function cloneNativeJson(value) {

package/ontology-contracts.d.ts

@@ -0,0 +1,5 @@
+export interface OntologyOperation { action: string; method: string }
+export const ONTOLOGY_RECORDS: readonly string[];
+export function ontologyOperations(): OntologyOperation[];
+export function ontologySchema(record?: string): Record<string, unknown> | undefined;
+export function formatOntologyContract(value: unknown): string;

package/ontology-contracts.mjs

@@ -0,0 +1,29 @@
+// The committed ontology contracts own schema output and SDK generation.
+// Native execution types remain with the native capabilities still using them.
+import { readFileSync } from 'node:fs';
+import { parseNativeJson, cloneNativeJson, stringifyNativeJson, stringifyNativeJsonMember, stringifyNativeJsonPretty } from './native-json.mjs';
+
+const schemas = parseNativeJson(readFileSync(new URL('./ontology-schemas.json', import.meta.url), 'utf8'));
+const operations = parseNativeJson(readFileSync(new URL('./ontology-operations.json', import.meta.url), 'utf8'));
+export const ONTOLOGY_RECORDS = Object.freeze([...schemas.records]);
+export function ontologyOperations() { return cloneNativeJson(operations); }
+
+/** Return a fresh schema, retaining its record-specific definitions and numeric facts. */
+export function ontologySchema(record = 'Orchestration') {
+  if (!Object.hasOwn(schemas.roots, record)) return undefined;
+  const root = schemas.roots[record], members = new Map();
+  for (const key of Object.keys(root.schema)) members.set(key, stringifyNativeJsonMember(root.schema, key));
+  if (root.definitions.length) members.set('$defs', `{${root.definitions.map(name => `${JSON.stringify(name)}:${stringifyNativeJson(schemas.definitions[name])}`).join(',')}}`);
+  const schema = parseNativeJson(`{${root.members.map(key => `${JSON.stringify(key)}:${members.get(key)}`).join(',')}}`);
+  // The shipped Windows native schemas embed the checked-out role prompt
+  // templates with CRLF. Keep those default values in this metadata contract;
+  // no provider prompt is executed or rewritten here.
+  const roles = schema.properties?.workflow?.default?.run?.roles;
+  if (process.platform === 'win32' && roles) for (const name of ['implementer', 'reviewer', 'triager']) {
+    if (typeof roles[name]?.prompt === 'string') roles[name].prompt = roles[name].prompt.replace(/\r?\n/gu, '\r\n');
+  }
+  return schema;
+}
+
+/** Native JSON formatting, including integer/float distinction and map ordering. */
+export function formatOntologyContract(value) { return stringifyNativeJsonPretty(value); }