@volter/supercode-interchange 0.0.0-stage → 0.1.1

package/LICENSE-APACHE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 supercode contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# Supercode interchange
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read-only metadata and discovery projection for the daemon-owned session index in
+[TypeScript architecture step 4](../../docs/plans/typescript-architecture.md#order).
+The port branch routes discovery and index windows through this library and the Teams owner.
+[Dated private Mac/Windows observations](../../docs/evidence/session-index-owner-2026-10-08.md)
+cover selected small homes; publication, all-format and large-home qualification remain open.
+Full session translation codecs remain at their later boundary.
+
+`resolveHarnessHomes` follows native HOME-first defaults and preserves explicitly empty harness-specific
+home values. `projectMetadata` applies workspace scope, native lineage, repository-family, profile, time and
+metadata-search filters with stable newest-first ordering. It clones raw rows before descendant roll-up.
+`projectMetadataPage` returns the existing hex JSON tuple pagination cursor and coverage receipt; a cursor
+whose row no longer matches is refused. These helpers neither read conversation previews nor imply that a
+metadata page is an enriched public discovery response.
+
+Workspace matching follows path components, includes directories linked directly into a subtree without
+widening it to an ancestor, and preserves Hermes/OpenClaw's literal exact-directory matching. Repository
+family matching reads Git common-directory and origin files without spawning Git.
+
+Internal readers cover the seven file-backed formats and the four native stores. File results keep verified
+fingerprints with their append offsets; compound rows also check auxiliary identities. Store snapshots are
+read-only and observe DB/WAL changes. OpenCode and Goose compare native row marks; Hermes retains mirror
+facts for query-time selection; orchestrator rows keep routing keys and the source change cursor. Codex names
+and history topics, and late Claude rename aliases, have separate append-aware ledgers.
+
+Bounded preview readers preserve source roles, provenance, native message cursors and Codex's adjacent
+event/response pairing. Preview search enriches eligible rows before pagination. These readers and discovery
+projection are connected to the owner; their presence is not a runtime or Windows qualification.
+
+This package requires Node 22.15 or newer. It does not start a native harness, change a vendor home or own
+a database. The machine daemon owns index state and subscriptions.

package/compressed.mjs

@@ -0,0 +1,58 @@
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import * as zlib from 'node:zlib';
+import { parseJsonLine } from './file-io.mjs';
+import { headerFacts, headerComplete } from './metadata.mjs';
+
+/** Decode only the native header budget, never a complete archived rollout.
+ * The compressed producer reads through the same verified handle as the row
+ * facts. Cancellation ends both streams before that handle can be released. */
+export async function readCompressedCodexHeader(reader) {
+  if (typeof zlib.createZstdDecompress !== 'function') throw new Error('compressed Codex metadata requires Node with createZstdDecompress (Node 22.15 or later)');
+  const source = Readable.from((async function* () {
+    for (let offset = 0; offset < reader.size;) {
+      const chunk = await reader.read(offset, Math.min(16 * 1024, reader.size - offset));
+      offset += chunk.length;
+      yield chunk;
+    }
+  })(), { objectMode: false });
+  const decoder = zlib.createZstdDecompress({ chunkSize: 16 * 1024 });
+  const abort = new AbortController();
+  // Install the rejection handler before consuming output; neither a failed
+  // producer nor an intentional prefix cancellation is an unhandled promise.
+  const completion = pipeline(source, decoder, { signal: abort.signal }).then(() => null, (error) => error);
+  const records = [];
+  let trailing = Buffer.alloc(0), consumed = 0, lines = 0, stopped = false;
+  const accept = (input) => {
+    const line = input.at(-1) === 13 ? input.subarray(0, -1) : input;
+    consumed += line.length; lines++;
+    if (consumed > 256 * 1024) return true;
+    const value = parseJsonLine(line, { strictUtf8: true });
+    if (value != null) records.push(value);
+    const recognizable = records.some((record) => (record?.type === 'session_meta'
+      && (typeof record.payload?.id === 'string' || typeof record.payload?.cwd === 'string'))
+      || (record?.type === 'turn_context' && typeof record.payload?.cwd === 'string'));
+    return lines >= 32 || (recognizable && headerComplete(headerFacts(records, 'codex'), 'codex'));
+  };
+  try {
+    for await (const chunk of decoder) {
+      const bytes = trailing.length ? Buffer.concat([trailing, chunk]) : chunk;
+      let from = 0, end;
+      while ((end = bytes.indexOf(10, from)) >= 0) {
+        if (accept(bytes.subarray(from, end))) { stopped = true; break; }
+        from = end + 1;
+      }
+      if (stopped) break;
+      trailing = bytes.subarray(from);
+      if (consumed + trailing.length > 256 * 1024 + 1) { stopped = true; break; }
+    }
+    if (!stopped && trailing.length) accept(trailing);
+    return headerFacts(records, 'codex');
+  } finally {
+    // Returning from for-await destroys its decoder. Abort also releases the
+    // upstream iterator, including any outstanding read of compressed bytes.
+    abort.abort();
+    const failure = await completion;
+    if (failure && !stopped && failure.code !== 'ABORT_ERR') throw failure;
+  }
+}

package/discovery.mjs

@@ -0,0 +1,110 @@
+import { descriptorMatches, projectMetadata, projectMetadataPage, decodeDiscoveryCursor, encodeDiscoveryCursor, discoveryReceipt } from './query.mjs';
+import { readLatestCandidates, readFileTopics } from './previews.mjs';
+import { nativeTrim } from './text.mjs';
+
+/** Preview refusal preserves the native metadata row. The owner can retain
+ * the exact failed source in diagnostics; it never invents message content. */
+export async function enrichDescriptor(query, descriptor, { codexTopics, metrics, previewFailure } = {}) {
+  const row = { ...descriptor };
+  const take = async (read) => {
+    try { return await read(); }
+    catch (error) { previewFailure?.(row.locator, error); return []; }
+  };
+  if (query.include_topic_candidates) {
+    const history = row.locator.harness === 'codex' ? codexTopics?.get(row.locator.session_id) : null;
+    const topics = history != null ? (Array.isArray(history) ? history : [history])
+      : row.locator.storage.kind === 'file' ? await take(() => readFileTopics(row.locator.storage.path, row.locator.harness, metrics)) : [];
+    if (topics.length) row.preview_candidates = topics;
+    else delete row.preview_candidates;
+  }
+  const latest = await take(() => readLatestCandidates(row.locator, metrics));
+  if (latest.length) row.latest_message_candidates = latest;
+  else delete row.latest_message_candidates;
+  return row;
+}
+
+/** Bounded enrichment belongs to returned/current-window rows. Metadata
+ * maintenance never invokes this function, including unchanged warm queries. */
+export async function enrichIndexPage(query, rows, options) {
+  const result = [];
+  for (const row of rows) result.push(await enrichDescriptor(query, row, options));
+  return result;
+}
+
+function queryName(query) { return query.query == null ? null : nativeTrim(query.query); }
+
+export function namesWholeSessionId(query) {
+  const id = queryName(query);
+  return query.cursor == null && id?.length >= 8 && id.includes('-') && /^[0-9a-f-]+$/i.test(id);
+}
+
+/** Name suppliers use the owner's watched registry/rename ledgers. The late
+ * title supplier chooses one id by source mtime, before applying the other
+ * query filters, as native claude_session_named does. Neither is caller proof. */
+export async function discoverFromIndex(query, descriptors, options = {}) {
+  const raw = [...descriptors];
+  if (query.search_previews) return previewPage(query, raw, options);
+  const page = projectMetadataPage(query, raw, options);
+  const name = queryName(query);
+  if (query.cursor == null && name) {
+    const selected = query.harnesses;
+    const canNameClaude = !selected?.length || selected.includes('claude-code');
+    const live = canNameClaude ? await options.liveClaudeName?.(name) : null;
+    if (live != null) {
+      const found = page.sessions.find((row) => row.locator.session_id === live.id);
+      if (found) {
+        if (found.title == null) found.title = live.name;
+        page.sessions = [found]; page.next_cursor = null;
+      }
+    }
+  }
+  // Native finish_discover_page restricts any exact returned id, rather than
+  // just the UUID-shaped optimization used before its cold scan.
+  if (name != null && page.sessions.some((row) => row.locator.session_id === name)) {
+    page.sessions = page.sessions.filter((row) => row.locator.session_id === name);
+    page.next_cursor = null;
+  }
+  if (!page.sessions.length && query.cursor == null && name && (!query.harnesses?.length || query.harnesses.includes('claude-code'))) {
+    const id = await options.lateClaudeName?.(name);
+    if (id != null) {
+      const rows = projectMetadata({ ...query, query: null, harnesses: ['claude-code'], limit: null }, raw, options);
+      const found = rows.find((row) => row.locator.session_id === id);
+      if (found) page.sessions.push({ ...found, title: name });
+    }
+  }
+  // Keep the native receipt from projection: its counts precede the exact-name
+  // post-filter and late-name fallback. Do not silently rewrite that contract.
+  page.sessions = await enrichIndexPage(query, page.sessions, options);
+  return page;
+}
+
+async function previewPage(query, raw, options) {
+  const search = queryName(query)?.toLowerCase();
+  if (!search) throw new Error('search_previews requires a nonempty query');
+  if (query.limit === 0) throw new Error('preview search limit must be positive');
+  if (query.limit != null && (!Number.isSafeInteger(query.limit) || query.limit < 0)) throw new Error('discovery limit must be a nonnegative integer');
+  const cursor = query.cursor == null ? null : JSON.stringify(decodeDiscoveryCursor(query.cursor));
+  const eligibleQuery = { ...query, query: null, search_previews: false, include_topic_candidates: true };
+  const eligible = projectMetadata(eligibleQuery, raw, options);
+  let cursorSeen = cursor == null, total = 0, more = false;
+  const sessions = [];
+  for (let row of eligible) {
+    const metadataMatch = descriptorMatches(row, search);
+    if (!metadataMatch) {
+      row = await enrichDescriptor(eligibleQuery, row, options);
+      if (![...(row.preview_candidates ?? []), ...(row.latest_message_candidates ?? [])].some((candidate) => candidate.content.toLowerCase().includes(search))) continue;
+    }
+    total++;
+    if (!cursorSeen) {
+      cursorSeen = cursor === JSON.stringify([row.updated_at_ms ?? null, row.locator.harness, row.locator.session_id]);
+      continue;
+    }
+    if (sessions.length < (query.limit ?? Infinity)) {
+      if (metadataMatch) row = await enrichDescriptor(eligibleQuery, row, options);
+      sessions.push(row);
+    } else more = true;
+  }
+  if (!cursorSeen) throw new Error('discovery cursor is stale or invalid');
+  return { sessions, next_cursor: more && sessions.length ? encodeDiscoveryCursor(sessions.at(-1)) : null,
+    receipt: discoveryReceipt(query, sessions, total, more, true) };
+}

package/file-io.mjs

@@ -0,0 +1,151 @@
+import { open, stat } from 'node:fs/promises';
+import { parseNativeJson } from './native-json.mjs';
+
+const stale = (path) => Object.assign(new Error(`${path} changed during its metadata read; previous index rows are retained`), { code: 'ESTALE' });
+const same = (a, b) => a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeNs === b.mtimeNs;
+
+export function fileFingerprint(info) {
+  return { device: String(info.dev), inode: String(info.ino), size: String(info.size), mtime_ns: String(info.mtimeNs) };
+}
+
+export function sameFingerprint(left, right) {
+  return left != null && right != null && ['device', 'inode', 'size', 'mtime_ns'].every((key) => left[key] === right[key]);
+}
+
+export function appendableFingerprint(previous, current) {
+  return previous != null && current != null && previous.device === current.device && previous.inode === current.inode
+    && BigInt(current.size) > BigInt(previous.size);
+}
+
+/** Read one open identity; verify both the handle and its current path before
+ * returning facts for a transaction. A changed path never commits new offsets
+ * beside facts read from its predecessor. The caller owns failure retry. */
+export async function withSessionFile(path, work, metrics = {}) {
+  const handle = await open(path, 'r');
+  metrics.files_opened = (metrics.files_opened ?? 0) + 1;
+  let countedRead = false;
+  try {
+    const before = await handle.stat({ bigint: true });
+    if (!before.isFile()) throw Object.assign(new Error(`${path} is not a session file`), { code: 'EINVAL' });
+    if (before.size > BigInt(Number.MAX_SAFE_INTEGER)) throw Object.assign(new Error(`${path} exceeds Node's exact file-offset range`), { code: 'EFBIG' });
+    const size = Number(before.size);
+    const reader = {
+      path, size, fingerprint: fileFingerprint(before), modified_ms: before.mtimeNs < 0n ? null : Number(before.mtimeNs / 1_000_000n),
+      async read(position, length, { appended = false } = {}) {
+        if (!Number.isSafeInteger(position) || position < 0 || !Number.isSafeInteger(length) || length < 0) throw new Error('invalid session-file range');
+        length = Math.min(length, Math.max(0, size - position));
+        const buffer = Buffer.alloc(length);
+        let received = 0;
+        while (received < length) {
+          const { bytesRead } = await handle.read(buffer, received, length - received, position + received);
+          if (!bytesRead) throw stale(path);
+          if (!countedRead) { metrics.files_read = (metrics.files_read ?? 0) + 1; countedRead = true; }
+          received += bytesRead;
+          metrics.bytes_read = (metrics.bytes_read ?? 0) + bytesRead;
+          if (appended) metrics.appended_bytes = (metrics.appended_bytes ?? 0) + bytesRead;
+        }
+        return buffer;
+      },
+    };
+    const result = await work(reader);
+    const after = await handle.stat({ bigint: true });
+    let current;
+    try { current = await stat(path, { bigint: true }); } catch { throw stale(path); }
+    if (!same(before, after) || !same(after, current)) throw stale(path);
+    return { result, fingerprint: reader.fingerprint, size, modified_ms: reader.modified_ms };
+  } finally { await handle.close(); }
+}
+
+export function parseJsonLine(buffer, { strictUtf8 = false } = {}) {
+  let text;
+  try { text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(buffer); }
+  catch (error) { if (strictUtf8) throw error; return null; }
+  try { return parseNativeJson(text); } catch { return null; }
+}
+
+/** A bounded head, with the native budget counted before parsing each line.
+ * A file's final unterminated line is visible to the cold header reader. */
+export async function readHeaderRecords(reader, { bytes = 256 * 1024, lines = 32 } = {}) {
+  const buffer = await reader.read(0, bytes + lines * 2);
+  const scan = { lines: 0, bytes: 0, terminated: true, exhausted: false };
+  // Decode lazily: once the format reader has its complete header, malformed
+  // bytes in an unused later body line cannot turn that header into a failure.
+  const records = (function* () {
+    let from = 0;
+    while (from < buffer.length && scan.lines < lines) {
+      let end = buffer.indexOf(10, from);
+      scan.terminated = end >= 0;
+      if (end < 0) {
+        if (buffer.length < reader.size) { scan.exhausted = true; break; }
+        end = buffer.length;
+      }
+      const line = buffer.subarray(from, end > from && buffer[end - 1] === 13 ? end - 1 : end);
+      scan.bytes += line.length; scan.lines++;
+      if (scan.bytes > bytes) { scan.exhausted = true; break; }
+      const value = parseJsonLine(line, { strictUtf8: true });
+      if (value != null) yield value;
+      from = end + 1;
+    }
+    if (scan.lines >= lines) scan.exhausted = true;
+  })();
+  records.scan = scan;
+  return records;
+}
+
+/** Visit newly appended complete lines without reading the old prefix. The
+ * returned trailing bytes are committed with the offset, not discarded. A
+ * format reader can inspect the unfinished tail separately without counting
+ * it twice as a complete stored message. */
+export async function visitAppendedLines(reader, previous, visit, { maxLineBytes = Infinity } = {}) {
+  let offset = previous?.offset ?? 0;
+  if (!Number.isSafeInteger(offset) || offset < 0 || offset > reader.size) throw stale(reader.path);
+  let pieces = previous?.trailing ? [Buffer.from(previous.trailing, 'base64')] : [];
+  let pendingBytes = pieces[0]?.length ?? 0;
+  let oversized = pendingBytes > maxLineBytes;
+  if (oversized) pieces = [];
+  let lineStart = offset - pendingBytes;
+  if (lineStart < 0) throw stale(reader.path);
+  while (offset < reader.size) {
+    const chunkStart = offset;
+    const chunk = await reader.read(offset, Math.min(64 * 1024, reader.size - offset), { appended: true });
+    offset += chunk.length;
+    let from = 0, end;
+    while ((end = chunk.indexOf(10, from)) >= 0) {
+      pendingBytes += end - from;
+      oversized ||= pendingBytes > maxLineBytes;
+      if (!oversized) pieces.push(chunk.subarray(from, end));
+      const input = oversized ? null : pieces.length === 1 ? pieces[0] : Buffer.concat(pieces, pendingBytes);
+      const line = input?.length && input.at(-1) === 13 ? input.subarray(0, -1) : input;
+      const lineEnd = chunkStart + end + 1;
+      await visit(line, { start: lineStart, end: lineEnd, oversized });
+      lineStart = lineEnd;
+      pieces = []; pendingBytes = 0; oversized = false;
+      from = end + 1;
+    }
+    if (from < chunk.length) {
+      pendingBytes += chunk.length - from;
+      oversized ||= pendingBytes > maxLineBytes;
+      if (oversized) pieces = [];
+      else pieces.push(chunk.subarray(from));
+    }
+  }
+  const trailing = oversized ? '' : Buffer.concat(pieces, pendingBytes).toString('base64');
+  return { offset, trailing, appendable: !oversized };
+}
+
+/** Visit complete tail boundaries newest-first; a partial first boundary is
+ * excluded when the range starts mid-file. The final boundary can lack LF. */
+export function* tailRecords(buffer, fromMidFile = false) {
+  const floor = fromMidFile ? buffer.indexOf(10) + 1 : 0;
+  if (fromMidFile && floor === 0) return;
+  let end = buffer.length;
+  while (end > floor) {
+    const newline = buffer.lastIndexOf(10, end - 1);
+    const start = newline >= floor ? newline + 1 : floor;
+    if (start < end) {
+      const value = parseJsonLine(buffer.subarray(start, end));
+      if (value != null) yield { value, start, end };
+    }
+    end = start - 1;
+  }
+}

package/foreign-store.mjs

@@ -0,0 +1,50 @@
+import { finalizeNouns, catalogTimestamp } from './metadata.mjs';
+import { readStore, statement, tableColumns, text, integer, unsigned, jsonColumn } from './sqlite-reader.mjs';
+import { nativeTrim } from './text.mjs';
+
+const MARKS = {
+  opencode: "SELECT id, title || char(31) || time_updated || char(31) || directory AS mark FROM session",
+  goose: "SELECT id, name || char(31) || updated_at || char(31) || working_dir AS mark FROM sessions WHERE archived_at IS NULL",
+};
+
+function marks(db, harness) {
+  return new Map(statement(db, MARKS[harness]).all().map((row) => [text(row.id), row.mark == null ? '' : text(row.mark)]));
+}
+
+function rows(db, path, harness, ids) {
+  if (ids?.size === 0) return [];
+  const params = ids == null ? [] : [JSON.stringify([...ids])];
+  const selected = ids == null ? '' : ' AND s.id IN (SELECT value FROM json_each(?))';
+  const sql = harness === 'opencode'
+    ? `SELECT s.id, s.directory AS cwd, s.title, s.time_updated AS updated, ${tableColumns(db, 'session').has('model') ? 's.model' : 'NULL'} AS model,
+         COUNT(m.id) AS message_count FROM session s LEFT JOIN message m ON m.session_id = s.id
+         WHERE 1=1${selected} GROUP BY s.id ORDER BY s.time_updated DESC`
+    : `SELECT s.id, s.working_dir AS cwd, s.name AS title, s.updated_at AS updated, s.model_config_json AS config,
+         COUNT(m.id) AS message_count FROM sessions s LEFT JOIN messages m ON m.session_id = s.id
+         WHERE s.archived_at IS NULL${selected} GROUP BY s.id ORDER BY s.updated_at DESC`;
+  return statement(db, sql).all(...params).map((row) => {
+    const id = text(row.id), title = text(row.title);
+    const config = harness === 'goose' ? jsonColumn(text(row.config, true)) : null;
+    const model = harness === 'opencode' ? text(row.model, true)
+      : config != null ? (Object.hasOwn(config, 'model_name') ? config.model_name : config.modelName) : null;
+    const updated = harness === 'opencode' ? unsigned(integer(row.updated))
+      : catalogTimestamp(text(row.updated)) ?? catalogTimestamp(`${row.updated.replaceAll(' ', 'T')}Z`);
+    return finalizeNouns({ locator: { harness, session_id: id, storage: { kind: 'sqlite', path, selector: id } },
+      cwd: text(row.cwd), title: (harness === 'opencode' ? title.length : nativeTrim(title).length) ? title : null,
+      updated_at_ms: updated, model: typeof model === 'string' ? model : null, message_count: unsigned(integer(row.message_count)) });
+  });
+}
+
+/** Marks and selected descriptors share a snapshot, so a changed/deleted id
+ * cannot be committed beside a mark read from a different store generation. */
+export async function readForeignStore(harness, path, { previousMarks, metrics = {} } = {}) {
+  if (!Object.hasOwn(MARKS, harness)) throw new Error(`no foreign row marks for ${harness}`);
+  return readStore(path, (db) => {
+    const current = marks(db, harness);
+    const ids = previousMarks == null ? null : new Set([...current].filter(([id, mark]) => previousMarks.get(id) !== mark).map(([id]) => id));
+    const removed = previousMarks == null ? [] : [...previousMarks.keys()].filter((id) => !current.has(id));
+    const changed = rows(db, path, harness, ids);
+    metrics.store_sessions_read = (metrics.store_sessions_read ?? 0) + changed.length;
+    return { marks: current, rows: changed, removed };
+  }, metrics);
+}

package/hermes-mirror.mjs

@@ -0,0 +1,9 @@
+export const hermesMirrorKey = (row) => JSON.stringify([row.locator.storage.path, row.locator.session_id]);
+
+/** The source retains all mirrors. Each query hides only the conversations
+ * represented by a selected worker, or explicitly carried to continued_as. */
+export function includeHermesMirror(mirror, selected) {
+  if (mirror == null) return true;
+  const unchanged = mirror.messages == null || mirror.count <= mirror.messages;
+  return !((selected.has(mirror.harness) || mirror.continued) && unchanged);
+}