@volter/supercode-interchange 0.0.0-stage → 0.1.0

package/hermes-store.mjs

@@ -0,0 +1,107 @@
+import { readStore, statement, tableColumns, text, integer, unsigned, jsonColumn } from './sqlite-reader.mjs';
+import { finalizeNouns } from './metadata.mjs';
+import { hermesMirrorKey } from './hermes-mirror.mjs';
+import { nativeInteger } from './native-json.mjs';
+
+const extendedColumns = ['session_key', 'chat_id', 'chat_type', 'thread_id', 'user_id', 'profile_name', 'handoff_state', 'handoff_platform', 'handoff_error'];
+const nonempty = (value) => typeof value === 'string' && value !== '' ? value : null;
+const numeric = (value) => value == null ? null : typeof value === 'number' || typeof value === 'bigint' ? Number(value) : (() => { throw new Error('Hermes returned a non-numeric epoch'); })();
+
+function sourceTrigger(source) {
+  if (!source) return 'unknown';
+  if (['cli', 'tui', 'acp', 'console'].includes(source)) return 'human';
+  if (['api_server', 'api'].includes(source)) return 'api';
+  if (source === 'cron' || source === 'webhook') return source;
+  return source === 'kanban' ? 'task' : 'channel';
+}
+
+function lineage(db, columns, row, config) {
+  if (row.parent_session_id == null) return null;
+  if (config?._delegate_from != null) return 'delegate';
+  if (config?._branched_from != null) return 'branch';
+  if (!columns.has('end_reason')) return 'unknown';
+  const parent = statement(db, 'SELECT end_reason, ended_at FROM sessions WHERE id=?').get(row.parent_session_id);
+  if (parent?.ended_at != null && typeof parent.ended_at !== 'number' && typeof parent.ended_at !== 'bigint') return 'unknown';
+  if (parent?.end_reason === 'compression') return 'compaction';
+  if (parent?.end_reason === 'branched' && (numeric(row.started_at) ?? Number.MAX_VALUE) >= (numeric(parent.ended_at) ?? Number.MAX_VALUE)) return 'branch';
+  return 'unknown';
+}
+
+function mirrorRecurrence(config) {
+  const value = config?._supercode_mirror?.recurrence;
+  if (value == null || typeof value.job_id !== 'string' || (value.kind !== undefined && typeof value.kind !== 'string')) return null;
+  return { job_id: value.job_id, kind: value.kind ?? 'cron' };
+}
+
+function nouns(row, relationship, config, extended) {
+  const source = nonempty(row.source) ?? '';
+  let trigger = relationship === 'delegate' ? 'parent' : sourceTrigger(source);
+  let recurrence = null;
+  const cron = /^cron_(.+)_([0-9]{8})_([0-9]{6})$/.exec(row.id);
+  if (cron) { trigger = 'cron'; recurrence = { job_id: cron[1], kind: 'cron' }; }
+  recurrence ??= mirrorRecurrence(config);
+  let surface = {}, profile = null;
+  if (extended) {
+    const key = nonempty(row.session_key);
+    const parts = key?.split(':');
+    if (parts?.[0] === 'agent' && parts.length >= 4) {
+      surface = { key, platform: parts[2], kind: parts[3] };
+      if (!['', 'main', 'default'].includes(parts[1])) profile = parts[1];
+      if (parts.length >= 5) surface.chat_id = parts[4];
+      if (parts.length >= 6) surface.thread_id = parts[5];
+      if (parts.length >= 7) surface.participant_id = parts[6];
+    } else if (key != null) surface.key = key;
+    for (const [column, field] of [['chat_id', 'chat_id'], ['chat_type', 'kind'], ['thread_id', 'thread_id'], ['user_id', 'participant_id']]) {
+      const value = nonempty(row[column]);
+      if (value != null) surface[field] = value;
+    }
+    if (surface.platform == null && trigger === 'channel') surface.platform = source;
+    profile = nonempty(row.profile_name) ?? profile;
+  }
+  const state = extended ? nonempty(row.handoff_state) : null;
+  const platform = nonempty(row.handoff_platform), error = nonempty(row.handoff_error);
+  return { trigger, ...(recurrence ? { recurrence } : {}),
+    ...(surface.key != null || surface.platform != null || surface.chat_id != null ? { surface } : {}),
+    ...(profile != null ? { profile } : {}),
+    ...(state != null ? { cross_surface: { state, ...(platform != null ? { platform } : {}), ...(error != null ? { error } : {}) } } : {}) };
+}
+
+export async function readHermesStore(path, { metrics = {} } = {}) {
+  return readStore(path, (db) => {
+    statement(db, 'SELECT count(*) FROM sessions').get();
+    const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map((row) => row.name));
+    if (!['sessions', 'messages', 'schema_version'].every((table) => tables.has(table))) return { rows: [], mirrors: new Map() };
+    const columns = tableColumns(db, 'sessions');
+    const extendedSchema = extendedColumns.every((column) => columns.has(column));
+    const values = statement(db, `SELECT id, cwd, title, model, message_count, started_at, ended_at, parent_session_id, source, model_config
+      ${extendedSchema ? ',' + extendedColumns.join(',') : ''} FROM sessions ORDER BY started_at DESC`).all();
+    const rows = [], mirrors = new Map();
+    for (const value of values) {
+      for (const column of ['cwd', 'title', 'model', 'parent_session_id', 'source', 'model_config']) text(value[column], true);
+      const id = text(value.id), config = jsonColumn(value.model_config);
+      const started = numeric(value.started_at), ended = numeric(value.ended_at);
+      const milliseconds = ended == null && started == null ? null : Math.max(0, Math.trunc((ended ?? started) * 1000));
+      if (milliseconds != null && !Number.isSafeInteger(milliseconds)) throw new Error(`${path} has an epoch outside the exact Node wire range`);
+      const nativeCount = integer(value.message_count, true);
+      const rawCount = nativeCount == null ? null : Number(nativeCount);
+      if (rawCount != null && !Number.isSafeInteger(rawCount)) throw new Error(`${path} has a non-integer or inexact native message count`);
+      const count = rawCount == null ? null : unsigned(Math.max(0, rawCount));
+      const extended = extendedSchema && extendedColumns.every((column) => value[column] == null || typeof value[column] === 'string');
+      const row = finalizeNouns({ locator: { harness: 'hermes', session_id: id, storage: { kind: 'file', path } },
+        cwd: value.cwd, title: value.title === '' ? null : value.title, model: value.model, message_count: count,
+        updated_at_ms: milliseconds, ...(value.parent_session_id != null ? { parent_session_id: value.parent_session_id } : {}),
+        ...nouns(value, lineage(db, columns, value, config), config, extended) });
+      const mirror = config?._supercode_mirror;
+      const mirroredCount = nativeInteger(mirror, 'messages', { signed: true });
+      if (mirroredCount != null && (mirroredCount < BigInt(Number.MIN_SAFE_INTEGER) || mirroredCount > BigInt(Number.MAX_SAFE_INTEGER))) throw new Error(`${path} has an inexact mirror message count`);
+      if (mirror != null) mirrors.set(hermesMirrorKey(row), {
+        harness: typeof mirror.harness === 'string' ? mirror.harness : null,
+        messages: mirroredCount == null ? null : Number(mirroredCount),
+        continued: Object.hasOwn(mirror, 'continued_as'), count: rawCount ?? 0,
+      });
+      rows.push(row);
+    }
+    metrics.store_sessions_read = (metrics.store_sessions_read ?? 0) + rows.length;
+    return { rows, mirrors };
+  }, metrics);
+}

package/homes.mjs

@@ -0,0 +1,37 @@
+import { userInfo } from 'node:os';
+import { join } from 'node:path';
+
+/** Native HarnessHomes defaults. An empty selected harness home is present;
+ * only HOME itself uses the nonempty rule from interchange::user_home. */
+export function resolveHarnessHomes(env = process.env) {
+  const accountHome = () => { try { return userInfo().homedir || '.'; } catch { return '.'; } };
+  const home = env.HOME || (process.platform === 'win32' && env.USERPROFILE) || accountHome();
+  const data = env.XDG_DATA_HOME ?? join(home, '.local', 'share');
+  const config = env.XDG_CONFIG_HOME ?? join(home, '.config');
+  const goose = env.GOOSE_PATH_ROOT != null
+    ? join(env.GOOSE_PATH_ROOT, 'data', 'sessions', 'sessions.db')
+    : process.platform === 'darwin'
+      ? join(home, 'Library', 'Application Support', 'Block', 'goose', 'sessions', 'sessions.db')
+      : process.platform === 'win32'
+        ? join(env.APPDATA ?? join(home, 'AppData', 'Roaming'), 'Block', 'goose', 'sessions', 'sessions.db')
+        : join(data, 'goose', 'sessions', 'sessions.db');
+  return {
+    claude_code: join(env.CLAUDE_CONFIG_DIR ?? join(home, '.claude'), 'projects'),
+    codex: join(env.CODEX_HOME ?? join(home, '.codex'), 'sessions'),
+    pi: env.PI_CODING_AGENT_SESSION_DIR ?? join(env.PI_CODING_AGENT_DIR ?? join(home, '.pi', 'agent'), 'sessions'),
+    opencode: env.OPENCODE_DB ?? join(data, 'opencode'),
+    grok: join(env.GROK_HOME ?? join(home, '.grok'), 'sessions'),
+    gemini: env.GEMINI_CLI_HOME ?? join(home, '.gemini'),
+    goose,
+    supercode: join(env.SUPERCODE_HOME ?? join(config, 'supercode'), 'sessions'),
+    openclaw: env.OPENCLAW_STATE_DIR ?? (env.OPENCLAW_HOME != null ? join(env.OPENCLAW_HOME, '.openclaw') : join(home, '.openclaw')),
+    hermes: join(env.HERMES_HOME ?? join(home, '.hermes'), 'state.db'),
+    orchestrator: env.SUPERCODE_ORCHESTRATOR_HOME ?? join(home, '.supercode', 'orchestrator'),
+  };
+}
+
+export const HARNESSES = Object.freeze(['claude-code', 'codex', 'pi', 'opencode', 'grok', 'gemini', 'goose', 'supercode', 'openclaw', 'hermes', 'orchestrator']);
+
+export function selectedHarnesses(query) {
+  return query.harnesses?.length ? [...new Set(query.harnesses)] : [...HARNESSES];
+}

package/index.d.ts

@@ -0,0 +1,125 @@
+export type HarnessId = string;
+export interface HarnessHomes {
+  claude_code: string; codex: string; pi: string; opencode: string;
+  grok: string; gemini: string; goose: string; supercode: string;
+  openclaw: string; hermes: string; orchestrator: string;
+}
+export type StorageLocator = { kind: 'file'; path: string } | { kind: 'sqlite'; path: string; selector: string };
+export interface SessionLocator { harness: HarnessId; session_id: string; storage: StorageLocator }
+export type SessionTrigger = 'human' | 'channel' | 'cron' | 'heartbeat' | 'webhook' | 'parent' | 'api' | 'task' | 'unknown';
+export interface SessionSurface {
+  key?: string; platform?: string; kind?: string; chat_id?: string; thread_id?: string; participant_id?: string;
+}
+export interface PreviewCandidate {
+  cursor?: string; role: 'user' | 'assistant'; content: string; metadata: Record<string, string>;
+}
+export interface SessionDescriptor {
+  locator: SessionLocator;
+  cwd: string | null; title: string | null; updated_at_ms: number | null;
+  message_count: number | null; model: string | null;
+  parent_session_id?: string | null; child_session_count?: number;
+  preview_candidates?: PreviewCandidate[]; latest_message_candidates?: PreviewCandidate[];
+  trigger?: SessionTrigger; surface?: SessionSurface; profile?: string;
+  recurrence?: { job_id: string; kind: string };
+  cross_surface?: { state: string; platform?: string; error?: string };
+  workspace?: { kind: 'repo' | 'channel' | 'none'; value?: string };
+}
+export interface DiscoveryQuery {
+  homes?: Partial<HarnessHomes>; harnesses?: HarnessId[];
+  workspace?: string | null; workspace_subtree?: boolean; workspace_family?: string | null;
+  updated_after_ms?: number | null; updated_before_ms?: number | null;
+  query?: string | null; search_previews?: boolean; cursor?: string | null; limit?: number | null;
+  include_topic_candidates?: boolean; include_child_sessions?: boolean;
+  root_session_id?: string | null; profile?: string | null;
+}
+export interface DiscoveryReceipt {
+  searched_previews?: boolean;
+  requested_after_ms?: number; requested_before_ms?: number; requested_limit?: number;
+  oldest_returned_ms?: number; newest_returned_ms?: number;
+  returned: number; total_matched: number; truncated: boolean;
+}
+export interface DiscoveryPage {
+  sessions: SessionDescriptor[]; next_cursor: string | null; receipt: DiscoveryReceipt;
+}
+export interface RepositoryFamily { identity: string; repository: boolean; origin: string | null }
+/** Source-private mirror facts are never added to a returned descriptor. */
+export interface MetadataProjectionOptions {
+  hermesMirrors?: Map<string, { harness: string | null; messages: number | null; continued: boolean; count: number }>;
+}
+export const HARNESSES: readonly HarnessId[];
+/** HOME-first defaults, preserving present empty harness-specific values. */
+export function resolveHarnessHomes(env?: Record<string, string | undefined>): HarnessHomes;
+export function selectedHarnesses(query: DiscoveryQuery): HarnessId[];
+export function workspaceScope(query: DiscoveryQuery): ((descriptor: SessionDescriptor) => boolean) | null;
+export function repositoryFamily(path: string): RepositoryFamily;
+export function sameRepositoryFamily(left: RepositoryFamily, right: RepositoryFamily): boolean;
+export function descriptorKey(row: SessionDescriptor): string;
+export function descriptorOrder(left: SessionDescriptor, right: SessionDescriptor): number;
+export function descriptorMatches(row: SessionDescriptor, lowerCaseSearch: string): boolean;
+/** Raw rows are cloned; metadata projection performs no preview reads. */
+export function projectMetadata(query: DiscoveryQuery, descriptors: Iterable<SessionDescriptor>, options?: MetadataProjectionOptions): SessionDescriptor[];
+/** Existing tuple pagination cursor, separate from a durable change cursor. */
+export function encodeDiscoveryCursor(row: SessionDescriptor): string;
+export function decodeDiscoveryCursor(cursor: string): [number | null, HarnessId, string];
+export function paginateDescriptors(query: DiscoveryQuery, rows: SessionDescriptor[]): { sessions: SessionDescriptor[]; next_cursor: string | null };
+export function discoveryReceipt(query: DiscoveryQuery, sessions: SessionDescriptor[], totalMatched: number, truncated: boolean, searchedPreviews?: boolean): DiscoveryReceipt;
+/** A metadata page only; public discovery enriches its returned rows separately. */
+export function projectMetadataPage(query: DiscoveryQuery, descriptors: Iterable<SessionDescriptor>, options?: MetadataProjectionOptions): DiscoveryPage;
+/** Read-only source APIs used by the daemon owner. These do not scan on behalf
+ * of SDK clients or mutate a foreign harness's store. */
+export type IndexMetrics = Record<string, number>;
+export interface FileFingerprint { device: string; inode: string; size: string; mtime_ns: string }
+export interface SourceStamp { path: string; missing?: boolean; fingerprint?: FileFingerprint }
+export interface FileReadCache {
+  fingerprint?: FileFingerprint; size?: number; modified_ms?: number | null;
+  result?: { descriptor?: SessionDescriptor | null; state?: Record<string, unknown> } | null;
+  descriptor?: SessionDescriptor | null; sources?: SourceStamp[];
+}
+export const FILE_HARNESSES: readonly HarnessId[];
+export const STORE_HARNESSES: readonly HarnessId[];
+export function normalizedSourcePath(path: string): Promise<string>;
+export function pathUnder(root: string, path: string): boolean;
+export function fileRoot(harness: HarnessId, homes: HarnessHomes): string | null;
+export function sessionPartFor(harness: HarnessId, root: string, path: string): Promise<string | null>;
+export function listSessionParts(harness: HarnessId, root: string, options?: { folder?: string; beforeDirectory?: (path: string) => Promise<void>; metrics?: IndexMetrics }): Promise<{ parts: Set<string>; directories: Set<string> }>;
+export function readFileMetadata(harness: HarnessId, root: string, path: string, options?: { previous?: FileReadCache; projects?: Map<string, string>; nativeTopic?: (path: string, id: string) => string | null; metrics?: IndexMetrics }): Promise<{ descriptor: SessionDescriptor | null; cache: FileReadCache | null }>;
+export function sourceStat(path: string): Promise<import('node:fs').BigIntStats | null>;
+export function sourceEntries(path: string): Promise<string[]>;
+export function selectStoreFiles(harness: HarnessId, homes: HarnessHomes): Promise<Array<{ path: string; profile: string | null }>>;
+export function storeRegistryDirectories(harness: HarnessId, homes: HarnessHomes): Promise<string[]>;
+export function fileFingerprint(info: import('node:fs').BigIntStats): FileFingerprint;
+export function sameFingerprint(left?: FileFingerprint | null, right?: FileFingerprint | null): boolean;
+export function verifySources(sources: SourceStamp[]): Promise<void>;
+export function storeFingerprints(path: string): Promise<SourceStamp[]>;
+export function readGeminiProjects(root: string, metrics?: IndexMetrics): Promise<{ source: SourceStamp; projects: Map<string, string> }>;
+export function readSourceJson(path: string, metrics?: IndexMetrics): Promise<SourceStamp & { result: unknown }>;
+export interface StoreRead<T> { sources: SourceStamp[]; result: T }
+export function readForeignStore(harness: HarnessId, path: string, options?: { previousMarks?: Map<string, string>; metrics?: IndexMetrics }): Promise<StoreRead<{ marks: Map<string, string>; rows: SessionDescriptor[]; removed: string[] }>>;
+export function readHermesStore(path: string, options?: { metrics?: IndexMetrics }): Promise<StoreRead<{ rows: SessionDescriptor[]; mirrors: NonNullable<MetadataProjectionOptions['hermesMirrors']> }>>;
+export function readOrchestratorStore(path: string, profile: string, options?: { after?: string; metrics?: IndexMetrics }): Promise<StoreRead<{ rows: Array<{ key: string; descriptor: SessionDescriptor | null }>; cursor: string; incremental: boolean; has_changes: boolean }>>;
+export function codexNamesPath(rollout: string): string | null;
+export function readCodexNames(path: string, options?: { previous?: unknown; metrics?: IndexMetrics }): Promise<unknown>;
+export function readCodexHistory(path: string, options?: { previous?: unknown; metrics?: IndexMetrics }): Promise<unknown>;
+export function readClaudeTitles(path: string, options?: { previous?: unknown; metrics?: IndexMetrics }): Promise<unknown>;
+export interface DiscoveryEnrichmentOptions extends MetadataProjectionOptions {
+  codexTopics?: Map<string, PreviewCandidate | PreviewCandidate[]>; metrics?: IndexMetrics;
+  previewFailure?: (locator: SessionLocator, error: Error) => void;
+  liveClaudeName?: (name: string) => Promise<{ id: string; name: string } | null>;
+  lateClaudeName?: (name: string) => Promise<string | null>;
+}
+export function enrichDescriptor(query: DiscoveryQuery, descriptor: SessionDescriptor, options?: DiscoveryEnrichmentOptions): Promise<SessionDescriptor>;
+export function enrichIndexPage(query: DiscoveryQuery, descriptors: SessionDescriptor[], options?: DiscoveryEnrichmentOptions): Promise<SessionDescriptor[]>;
+export function discoverFromIndex(query: DiscoveryQuery, descriptors: Iterable<SessionDescriptor>, options?: DiscoveryEnrichmentOptions): Promise<DiscoveryPage>;
+export function nativeTrim(value: string): string;
+export interface IndexMetadataRecord {
+  source: string; part: string; row_key: string; descriptor: SessionDescriptor;
+  mirror?: { harness: string | null; messages: number | null; continued: boolean; count: number } | null;
+}
+export class RetainedMetadataProjection {
+  constructor(query: DiscoveryQuery, sources: string[], records: Iterable<IndexMetadataRecord>, metrics?: IndexMetrics);
+  updatePart(source: string, part: string, records: Iterable<IndexMetadataRecord>): void;
+  partsFor(key: string): Set<string>;
+  page(query: DiscoveryQuery): DiscoveryPage;
+}
+/** Integer facts from readSourceJson, retaining native integer versus float tokens. */
+export function nativeInteger(value: unknown, key: string, options?: { signed?: boolean }): bigint | null;

package/index.mjs

@@ -0,0 +1,20 @@
+export { HARNESSES, resolveHarnessHomes, selectedHarnesses } from './homes.mjs';
+export { repositoryFamily, sameRepositoryFamily, workspaceScope } from './workspace.mjs';
+export {
+  descriptorKey, descriptorOrder, descriptorMatches, projectMetadata,
+  encodeDiscoveryCursor, decodeDiscoveryCursor, paginateDescriptors,
+  discoveryReceipt, projectMetadataPage,
+} from './query.mjs';
+export { FILE_HARNESSES, STORE_HARNESSES, normalizedSourcePath, pathUnder, fileRoot, sessionPartFor, listSessionParts, readFileMetadata } from './source-layout.mjs';
+export { sourceStat, sourceEntries, selectStoreFiles, storeRegistryDirectories } from './store-registry.mjs';
+export { fileFingerprint, sameFingerprint } from './file-io.mjs';
+export { verifySources, readGeminiProjects, readSourceJson } from './source-files.mjs';
+export { storeFingerprints } from './sqlite-reader.mjs';
+export { readForeignStore } from './foreign-store.mjs';
+export { readHermesStore } from './hermes-store.mjs';
+export { readOrchestratorStore } from './orchestrator-store.mjs';
+export { codexNamesPath, readCodexNames, readCodexHistory, readClaudeTitles } from './native-ledgers.mjs';
+export { enrichDescriptor, enrichIndexPage, discoverFromIndex } from './discovery.mjs';
+export { nativeInteger } from './native-json.mjs';
+export { nativeTrim } from './text.mjs';
+export { RetainedMetadataProjection } from './retained-projection.mjs';

package/jsonl.mjs

@@ -0,0 +1,124 @@
+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 { readCompressedCodexHeader } from './compressed.mjs';
+
+/** A cold suffix is kept only when the final line is unfinished. A partial
+ * line outside the native metadata budget requests a cold bounded rebuild on
+ * its next write; it never becomes a silently truncated JSON record. */
+export async function unfinishedSuffix(reader) {
+  if (!reader.size) return { trailing: '', appendable: true };
+  const last = await reader.read(reader.size - 1, 1);
+  if (last[0] === 10) return { trailing: '', appendable: true };
+  const bytes = await reader.read(Math.max(0, reader.size - 1024 * 1024), Math.min(reader.size, 1024 * 1024));
+  const newline = bytes.lastIndexOf(10);
+  if (newline < 0 && bytes.length < reader.size) return { trailing: '', appendable: false };
+  return { trailing: bytes.subarray(newline + 1).toString('base64'), appendable: true };
+}
+
+function checkHarness(path, harness) {
+  if (!['claude-code', 'codex', 'pi'].includes(harness)) throw new Error(`no generic JSONL reader for ${harness}`);
+  if (path.endsWith('.zst')) throw new Error('a compressed rollout requires the compressed header reader');
+}
+
+async function readHeader(reader, harness) {
+  const records = await readHeaderRecords(reader);
+  const header = headerFacts(records, harness);
+  // An unfinished record can become malformed on a later write; it cannot
+  // freeze the header simply because its current bytes parse successfully.
+  return { header, header_frozen: records.scan.terminated && (records.scan.exhausted || headerComplete(header, harness)) };
+}
+
+async function descriptor(path, harness, reader, header, facts, nativeTopic) {
+  const sessionId = header.session_id ?? basename(path, extname(path));
+  let title = 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);
+  }
+  const parent = header.parent_session_id ?? (harness === 'claude-code' && basename(dirname(path)) === 'subagents' ? basename(dirname(dirname(path))) : null);
+  return finalizeNouns({
+    locator: { harness, session_id: sessionId, storage: { kind: 'file', path } },
+    cwd: header.cwd, title, updated_at_ms: facts.last_turn_ms ?? reader.modified_ms,
+    message_count: null, model: facts.model ?? header.model,
+    ...(parent != null ? { parent_session_id: parent } : {}),
+    ...(header.trigger != null ? { trigger: header.trigger } : {}),
+  });
+}
+
+async function cold(reader, harness, nativeTopic) {
+  const head = await readHeader(reader, harness);
+  const tail = await readColdMetadataTail(reader, harness);
+  return {
+    descriptor: await descriptor(reader.path, harness, reader, head.header, tail.facts, nativeTopic),
+    state: { ...head, ...tail },
+  };
+}
+
+export async function readColdMetadataTail(reader, harness) {
+  return { facts: await readTailFacts(reader, harness), offset: reader.size, ...await unfinishedSuffix(reader) };
+}
+
+/** Claude, Codex and Pi metadata from one uncompressed transcript identity.
+ * The daemon supplies Codex's separately watched native thread-name index;
+ * this reader never launches native discovery or scans unrelated sessions. */
+export async function readUncompressedJsonl(path, harness, { nativeTopic, metrics } = {}) {
+  checkHarness(path, harness);
+  return withSessionFile(path, (reader) => cold(reader, harness, nativeTopic), metrics);
+}
+
+/** Native archived Codex rollouts decode their header, while the retained
+ * catalog's tail scan reads the packed file's bytes. Preserve that contract:
+ * compressed bytes normally supply no JSON clock, leaving mtime as recency. */
+export async function readCompressedCodex(path, { nativeTopic, metrics, previous } = {}) {
+  return withSessionFile(path, async (reader) => {
+    if (sameFingerprint(previous?.fingerprint, reader.fingerprint) && previous.result?.state) {
+      const old = previous.result.state;
+      return { ...previous.result, descriptor: await descriptor(path, 'codex', reader, old.header, old.facts, nativeTopic) };
+    }
+    const header = await readCompressedCodexHeader(reader);
+    const facts = await readTailFacts(reader, 'codex');
+    return {
+      descriptor: await descriptor(path, 'codex', reader, header, facts, nativeTopic),
+      state: { header, header_frozen: true, facts, offset: reader.size, trailing: '', appendable: false },
+    };
+  }, metrics);
+}
+
+/** A replacement, truncation or rewritten same-size file gets its own cold
+ * read. Offsets, header and row facts are returned under the same verified
+ * identity; the owner commits them together or retains the previous row. */
+export async function refreshUncompressedJsonl(path, harness, previous, { nativeTopic, metrics } = {}) {
+  checkHarness(path, harness);
+  return withSessionFile(path, async (reader) => {
+    if (sameFingerprint(previous?.fingerprint, reader.fingerprint)) {
+      const held = previous.result;
+      return { ...held, descriptor: await descriptor(path, harness, reader, held.state.header, held.state.facts, nativeTopic) };
+    }
+    const old = previous?.result?.state;
+    if (!old?.appendable || !appendableFingerprint(previous.fingerprint, reader.fingerprint)) return cold(reader, harness, nativeTopic);
+    const next = await advanceMetadataTail(reader, harness, old);
+    const head = old.header_frozen ? { header: old.header, header_frozen: true } : await readHeader(reader, harness);
+    return {
+      descriptor: await descriptor(path, harness, reader, head.header, next.facts, nativeTopic),
+      state: { ...head, ...next },
+    };
+  }, metrics);
+}
+
+export async function advanceMetadataTail(reader, harness, old) {
+  const facts = { ...old.facts };
+  const suffix = await visitAppendedLines(reader, old, (line, { start }) => {
+    if (line == null) return; // The line exceeds the native tail budget.
+    const record = parseJsonLine(line);
+    if (record != null) foldTailRecord(facts, record, harness, start);
+  }, { maxLineBytes: 1024 * 1024 });
+  if (suffix.trailing) {
+    const record = parseJsonLine(Buffer.from(suffix.trailing, 'base64'));
+    if (record != null) foldTailRecord(facts, record, harness, reader.size - Buffer.byteLength(suffix.trailing, 'base64'));
+  }
+  // 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);
+  return { facts: nextFacts, ...suffix };
+}

package/metadata.mjs

@@ -0,0 +1,168 @@
+import { tailRecords } from './file-io.mjs';
+import { nativeTrim } from './text.mjs';
+
+const string = (value) => typeof value === 'string' ? value : null;
+const fill = (result, key, value) => { if (result[key] == null && typeof value === 'string') result[key] = value; };
+
+/** Match sidecar::rfc3339_to_ms as used by the native catalog, including its
+ * existing fractional-digit and civil-date rules. Do not silently substitute
+ * Date.parse's broader formats or different offset interpretation. */
+export function catalogTimestamp(value) {
+  if (typeof value !== 'string') return null;
+  let text = nativeTrim(value);
+  if (text.endsWith('Z')) text = text.slice(0, -1);
+  const at = text.indexOf('T');
+  if (at < 0) return null;
+  const date = text.slice(0, at), time = text.slice(at + 1);
+  const dateParts = /^([+]?\d+)-([+]?\d+)-([+-]?\d+)$/.exec(date);
+  const dot = time.indexOf('.');
+  const clock = dot < 0 ? time : time.slice(0, dot);
+  const timeParts = /^([+-]?\d+):([+-]?\d+):([+-]?\d+)$/.exec(clock);
+  if (!dateParts || !timeParts) return null;
+  const digits = dot < 0 ? '' : /^\d+/.exec(time.slice(dot + 1))?.[0];
+  if (dot >= 0 && !digits) return null;
+  const minimum = -(1n << 63n), maximum = (1n << 63n) - 1n;
+  const values = [...dateParts.slice(1), ...timeParts.slice(1)].map((part) => BigInt(part));
+  if (values.some((part) => part < minimum || part > maximum)) return null;
+  let [year, month, day, hour, minute, second] = values;
+  if (month < 1n || month > 12n || day < 1n || day > 31n) return null;
+  if (month <= 2n) year--;
+  const numerator = year >= 0n ? year : year - 399n;
+  const era = numerator >= 0n ? numerator / 400n : (numerator - 399n) / 400n;
+  const yoe = year - era * 400n;
+  const mp = month > 2n ? month - 3n : month + 9n;
+  const doy = (153n * mp + 2n) / 5n + day - 1n;
+  const days = era * 146097n + yoe * 365n + yoe / 4n - yoe / 100n + doy - 719468n;
+  const milliseconds = dot < 0 ? 0n : BigInt(digits.slice(0, 3).padEnd(3, '0'));
+  const result = (days * 86400n + hour * 3600n + minute * 60n + second) * 1000n + milliseconds;
+  if (result < 0n || result > maximum || result > BigInt(Number.MAX_SAFE_INTEGER)) return null;
+  return Number(result);
+}
+
+export function recordModel(record, harness) {
+  if (harness === 'claude-code' || harness === 'pi') return string(record?.message?.model);
+  if (harness === 'codex' && record?.type === 'turn_context') return string(record?.payload?.model);
+  return null;
+}
+
+export function recordTimestamp(record, harness) {
+  return catalogTimestamp(record?.[harness === 'supercode' ? 'ts' : 'timestamp']);
+}
+
+/** Native bounded recency/model scan, with source offsets retained for the
+ * 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 };
+  let window = Math.min(16 * 1024, reader.size);
+  for (;;) {
+    const from = reader.size - window;
+    const bytes = await reader.read(from, window);
+    for (const { value, start } of tailRecords(bytes, window < reader.size)) {
+      if (facts.last_turn_ms == null) {
+        facts.last_turn_ms = recordTimestamp(value, harness);
+        if (facts.last_turn_ms != null) facts.clock_offset = from + start;
+      }
+      if (facts.model == null) {
+        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 (facts.last_turn_ms != null || window >= reader.size || window >= 1024 * 1024) return { ...facts, scan_from: from };
+    window = Math.min(window * 2, reader.size, 1024 * 1024);
+  }
+}
+
+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; }
+}
+
+/** Reuse known positions only while the new native tail window contains them.
+ * If that window exposes an uninspected prefix, read it before claiming there
+ * is no older model. Ordinary appended turns do not reread the old prefix. */
+export async function finishAppendedFacts(reader, harness, previous, facts) {
+  let window = Math.min(16 * 1024, reader.size);
+  const contains = (start, from) => start != null && (from === 0 || start > from);
+  for (;;) {
+    const from = reader.size - window;
+    if (contains(facts.clock_offset, from) || window >= reader.size || window >= 1024 * 1024) {
+      if (from < previous.scan_from && (!contains(facts.clock_offset, from) || !contains(facts.model_offset, from))) return readTailFacts(reader, harness);
+      if (!contains(facts.clock_offset, from)) { facts.last_turn_ms = null; facts.clock_offset = null; }
+      if (!contains(facts.model_offset, from)) { facts.model = null; facts.model_offset = null; }
+      return { ...facts, scan_from: from };
+    }
+    window = Math.min(window * 2, reader.size, 1024 * 1024);
+  }
+}
+
+export function codexStartTrigger(payload) {
+  if (payload?.source != null && Object.hasOwn(payload.source, 'subagent')) return 'parent';
+  const originator = payload?.originator;
+  return typeof originator === 'string' && (originator === 'codex_exec' || originator === 'supercode' || originator.startsWith('supercode_')) ? 'api' : null;
+}
+
+function humanize(value) {
+  const text = value.replace(/[_-]/g, ' ');
+  const [first, ...rest] = [...text];
+  return first == null ? text : first.toUpperCase() + rest.join('');
+}
+
+/** Only the three dialects read by native read_header; other file-backed
+ * harnesses have their own container/summary readers. */
+export function headerFacts(records, harness) {
+  if (!['claude-code', 'codex', 'pi'].includes(harness)) throw new Error(`no generic JSONL header reader for ${harness}`);
+  const result = { session_id: null, cwd: null, title: null, model: null, parent_session_id: null, trigger: null, topic: null };
+  for (const value of records) {
+    applyHeaderRecord(result, value, harness);
+    if (headerComplete(result, harness)) break;
+  }
+  if (result.session_id == null && result.cwd == null) throw new Error(`no recognizable ${harness} session header`);
+  return result;
+}
+
+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);
+    if (value?.type === 'ai-title') fill(result, 'topic', value.aiTitle);
+    fill(result, 'model', value?.message?.model);
+  } else if (harness === 'codex') {
+    const payload = value?.payload;
+    if (value?.type === 'session_meta') {
+      fill(result, 'session_id', payload?.id); fill(result, 'cwd', payload?.cwd);
+      result.trigger ??= codexStartTrigger(payload);
+      fill(result, 'title', payload?.thread_name); fill(result, 'title', payload?.title);
+      fill(result, 'parent_session_id', payload?.parent_thread_id);
+      const spawn = payload?.source?.subagent?.thread_spawn;
+      if (typeof spawn?.parent_thread_id === 'string') result.parent_session_id = spawn.parent_thread_id;
+      if (result.title == null && typeof spawn?.agent_path === 'string') {
+        const part = spawn.agent_path.split('/').filter(Boolean).at(-1);
+        if (part != null) result.title = humanize(part);
+      }
+    }
+    if (value?.type === 'turn_context') {
+      fill(result, 'cwd', payload?.cwd); fill(result, 'model', payload?.model);
+    }
+  } else if (harness === 'pi') {
+    if (value?.type === 'session') { fill(result, 'session_id', value.id); fill(result, 'cwd', value.cwd); }
+    fill(result, 'model', value?.message?.model);
+  }
+}
+
+export function headerComplete(header, harness) {
+  return header.session_id != null && header.cwd != null && header.model != null
+    && (harness !== 'claude-code' || header.title != null || header.topic != null);
+}
+
+/** Catalog finalization constructs metadata from these descriptor facts only;
+ * a parent id by itself does not add a trigger the native row never carried. */
+export function finalizeNouns(row) {
+  const surface = row.surface;
+  const workspace = row.cwd != null ? { kind: 'repo', value: row.cwd }
+    : surface?.platform != null ? { kind: 'channel', value: surface.chat_id != null ? `${surface.platform}:${surface.chat_id}` : surface.platform }
+      : { kind: 'none' };
+  return { ...row, trigger: row.trigger ?? 'human', workspace };
+}