@volter/supercode-interchange 0.1.8 → 0.1.10

package/README.md

@@ -123,6 +123,19 @@ record selected-home answers and null malformed metadata through npm and
 operator streams; concurrent path/record replacement and runtime writing remain
 unqualified.
 
+`sessions.resume_instructions` reads the complete selected transcript before
+returning a structured launch. An explicit cwd wins over the transcript's
+recorded cwd, then `.`; the locator supplies the harness and session id.
+Default and explicit `yolo` policy use the shared generated startup table.
+Grok receives its resolved default home only when that home is a symlink and
+no explicit `GROK_HOME` was supplied. This returns arguments and environment;
+it neither starts a harness nor writes a session or permission configuration.
+The separate `resume_instructions` capability marker refuses older services.
+The [private Mac/Windows record](../../docs/evidence/session-resume-instructions-2026-10-08.md)
+retains eight harnesses' specifications, cwd/environment cases and older-service
+refusal through npm and loopback operator streams. Installed sets, actual live
+resume and full-corpus qualification remain open.
+
 `sessions.usage` reads a complete lossless session in the load worker and groups
 recorded tokens by the native day prefix and model. Claude keeps the last usage
 record for each response id; Codex separates successive cumulative totals and

package/metadata.mjs

@@ -119,7 +119,7 @@ export function headerFacts(records, harness) {
     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`);
+  if (result.session_id == null && result.cwd == null) throw Object.assign(new Error(`no recognizable ${harness} session header`), { code: 'not_a_session' });
   return result;
 }
 

package/openclaw.mjs

@@ -44,7 +44,7 @@ async function scanCounts(reader, previous) {
     headerPieces = []; headerSize = 0;
     if (!nativeTrim(text)) return;
     const value = parseJsonLine(bytes, { strictUtf8: true });
-    if (value?.type !== 'session') throw new Error(`${reader.path} has no OpenClaw session header`);
+    if (value?.type !== 'session') throw Object.assign(new Error(`${reader.path} has no OpenClaw session header`), { code: 'not_a_session' });
     header = value; headerTerminated = terminated;
   };
   while (offset < reader.size) {
@@ -72,7 +72,7 @@ async function scanCounts(reader, previous) {
   }
   utf8.decode(); // A truncated multibyte sequence is a failed part, not none.
   if (header == null && headerSize) acceptHeader(false);
-  if (header == null) throw new Error(`${reader.path} has no OpenClaw session header`);
+  if (header == null) throw Object.assign(new Error(`${reader.path} has no OpenClaw session header`), { code: 'not_a_session' });
   count.match_tail = overlap.toString('base64');
   return { count, header, header_terminated: headerTerminated };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-interchange",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "type": "module",
   "description": "Read-only harness metadata, transcript codecs and session projections for Supercode",
   "license": "MIT OR Apache-2.0",

package/session-read.d.ts

@@ -3,7 +3,7 @@ import { SessionFollower } from './session-codecs.js';
 import type { ProjectedSessionResult, NormalizedSession, RecordedSessionProfile, RecordedSessionProfileChange } from './session-model.js';
 export const SESSION_READ_METHODS: readonly string[];
 export const SESSION_READ_EVENT: 'harness.v1.sessions.event';
-export const SESSION_READ_CAPABILITY: Readonly<{ version: 1; owner: 'caller'; language: 'typescript'; native_parser: false; recorded_config: true; launch_agent: true; usage: true; spend: true }>;
+export const SESSION_READ_CAPABILITY: Readonly<{ version: 1; owner: 'caller'; language: 'typescript'; native_parser: false; recorded_config: true; launch_agent: true; usage: true; spend: true; resume_instructions: true }>;
 export interface SessionReadContext { cwd?: string; env?: Record<string, string | undefined> }
 export function parseSessionWire(text: string): unknown;
 export function stringifySessionWire(value: unknown): string;
@@ -32,3 +32,5 @@ export interface MachineTokenSpend extends RecordedTokenSpend {
 }
 /** Recently modified Claude/Codex tails, including child use on the parent. */
 export function loadSessionSpend(params: unknown, context?: SessionReadContext): Promise<{ since: string; until: string; session_count: number; sessions: MachineTokenSpend[]; total: RecordedTokenSpend }>;
+/** Reads the complete source and returns a specification; starts no process. */
+export function loadSessionResumeInstructions(params: unknown, context?: SessionReadContext): Promise<{ launch: { cwd: string; program: string; arguments: string[]; env: Record<string, string> } }>;

package/session-read.mjs

@@ -12,11 +12,12 @@ import { recordedSessionConfiguration } from './session-recorded-config.mjs';
 import { recordedLaunchAgent } from './session-launch-agent.mjs';
 import { recordedSessionUsage } from './session-usage.mjs';
 import { loadMachineSpend } from './session-spend.mjs';
+import { sessionResumeLaunch } from './session-resume-instructions.mjs';
 import { parseUsageSince, usageMoment } from './session-usage-time.mjs';
 
-export const SESSION_READ_METHODS = Object.freeze(['harness.v1.sessions.load', 'harness.v1.sessions.follow', 'harness.v1.sessions.unfollow', 'harness.v1.sessions.recorded_config', 'harness.v1.sessions.launch_agent', 'harness.v1.sessions.usage', 'harness.v1.sessions.spend']);
+export const SESSION_READ_METHODS = Object.freeze(['harness.v1.sessions.load', 'harness.v1.sessions.follow', 'harness.v1.sessions.unfollow', 'harness.v1.sessions.recorded_config', 'harness.v1.sessions.launch_agent', 'harness.v1.sessions.usage', 'harness.v1.sessions.spend', 'harness.v1.sessions.resume_instructions']);
 export const SESSION_READ_EVENT = 'harness.v1.sessions.event';
-export const SESSION_READ_CAPABILITY = Object.freeze({ version: 1, owner: 'caller', language: 'typescript', native_parser: false, recorded_config: true, launch_agent: true, usage: true, spend: true });
+export const SESSION_READ_CAPABILITY = Object.freeze({ version: 1, owner: 'caller', language: 'typescript', native_parser: false, recorded_config: true, launch_agent: true, usage: true, spend: true, resume_instructions: true });
 export { loadMachineSpend as loadSessionSpend };
 export { parseNativeJson as parseSessionWire, stringifyNativeJson as stringifySessionWire };
 export { stringifyNativeJsonPretty as prettySessionWire };
@@ -138,3 +139,15 @@ export async function loadSessionUsage(params, context = {}) {
   if (since != null) answer.since = usageMoment(since);
   return answer;
 }
+
+export async function loadSessionResumeInstructions(params, context = {}) {
+  object(params, 'resume instructions params');
+  const { locator } = parseSessionReadParams({ locator: params.locator }, context);
+  const cwd = params.cwd == null ? null : string(params.cwd, 'cwd');
+  const policy = Object.hasOwn(params, 'policy') ? params.policy : 'default';
+  if (!['default', 'yolo'].includes(policy)) invalid(`unknown resume policy: ${String(policy)}`);
+  // Native admission loads the source even when cwd is explicit, and its
+  // launch identity comes from the locator rather than a transcript header.
+  const session = await loadSessionLocator(locator, { ...context, fidelity: 'byte_lossless', includeSubagents: true });
+  return { launch: sessionResumeLaunch(locator.harness, locator.session_id, cwd ?? session.meta.cwd ?? '.', policy, context) };
+}

package/session-resume-instructions.mjs

@@ -0,0 +1,54 @@
+// A launch specification only. The caller decides whether to run the harness.
+import { lstatSync, realpathSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { isAbsolute } from 'node:path';
+import { STARTUP_PROMPTS } from './startup-prompts.mjs';
+import { childPath } from './session-spend-files.mjs';
+
+function startupArguments(harness, cwd, unattended) {
+  const prompts = STARTUP_PROMPTS[harness];
+  if (!prompts) return [];
+  const where = JSON.stringify(cwd);
+  const arguments_ = prompts.startup.flatMap(pair => pair.map(flag => flag.replaceAll('{cwd}', where)));
+  if (unattended) arguments_.push(...prompts.unattended);
+  return arguments_;
+}
+
+function grokHomeEnvironment(env, cwd) {
+  if (env.GROK_HOME !== undefined) return {};
+  let home = env.HOME || (process.platform === 'win32' ? env.USERPROFILE : null);
+  if (!home) { try { home = userInfo().homedir; } catch { return {}; } }
+  if (!isAbsolute(home) && !(process.platform === 'win32' && /^[A-Za-z]:/.test(home))) home = childPath(cwd, home);
+  const path = childPath(home, '.grok');
+  try { if (lstatSync(path).isSymbolicLink()) return { GROK_HOME: realpathSync(path) }; }
+  catch { /* no recorded filesystem resolution to supply */ }
+  return {};
+}
+
+export function sessionResumeLaunch(harness, sessionId, cwd, policy, { env = process.env, cwd: readCwd = process.cwd() } = {}) {
+  const unattended = policy === 'yolo';
+  let program, arguments_;
+  switch (harness) {
+    case 'grok':
+      program = 'grok';
+      arguments_ = [...(unattended ? ['--sandbox', 'workspace', '--always-approve'] : []), '--resume', sessionId];
+      break;
+    case 'codex':
+      program = 'codex'; arguments_ = [...startupArguments(harness, cwd, unattended), 'resume', sessionId]; break;
+    case 'claude-code':
+      program = 'claude'; arguments_ = [...startupArguments(harness, cwd, unattended), '--resume', sessionId]; break;
+    case 'gemini':
+      program = 'gemini'; arguments_ = [...startupArguments(harness, cwd, unattended), '--resume', sessionId]; break;
+    case 'goose':
+      program = 'goose'; arguments_ = ['session', '--resume', '--session-id', sessionId]; break;
+    case 'pi':
+      program = 'pi'; arguments_ = [...startupArguments(harness, cwd, unattended), '--session', sessionId]; break;
+    case 'opencode':
+      program = 'opencode'; arguments_ = ['--session', sessionId]; break;
+    case 'supercode':
+      program = 'supercode'; arguments_ = [...(unattended ? ['--dangerous'] : []), 'resume', sessionId]; break;
+    default:
+      throw Object.assign(new Error(`no structured resume launch is registered for harness \`${harness}\``), { rpcCode: -32602 });
+  }
+  return { cwd, program, arguments: arguments_, env: program === 'grok' ? grokHomeEnvironment(env, readCwd) : {} };
+}

package/source-files.mjs

@@ -46,7 +46,7 @@ async function geminiHeader(reader) {
   const bytes = await reader.read(0, Math.min(64 * 1024, reader.size));
   const newline = bytes.indexOf(10), end = newline < 0 ? bytes.length : newline;
   const header = parseJsonLine(bytes.subarray(0, end), { strictUtf8: true });
-  if (typeof header?.sessionId !== 'string') throw new Error(`${reader.path} has no Gemini sessionId header`);
+  if (typeof header?.sessionId !== 'string') throw Object.assign(new Error(`${reader.path} has no Gemini sessionId header`), { code: 'not_a_session' });
   const after = newline < 0 ? bytes.length : newline + 1;
   const decoration = bytes.subarray(after, Math.min(bytes.length, after + 4 * 1024));
   let model = null, modelTerminated = false;

package/source-layout.mjs

@@ -37,7 +37,13 @@ export async function sessionPartFor(harness, root, path) {
   const name = basename(path);
   if (harness === 'claude-code' || harness === 'pi') return name.endsWith('.jsonl') ? path : null;
   if (harness === 'codex') return name.endsWith('.jsonl') || name.endsWith('.jsonl.zst') ? path : null;
-  if (harness === 'openclaw') return name.endsWith('.jsonl') && !name.endsWith('.trajectory.jsonl') ? path : null;
+  // OpenClaw keeps its sessions in `agents/<id>/sessions/` only (native discover_openclaw); the rest of its state
+  // folder (logs, cron, workspace) holds JSONL that is not a session.
+  if (harness === 'openclaw') {
+    const part = relative(root, path).split(sep);
+    return part.length === 4 && part[0] === 'agents' && part[2] === 'sessions'
+      && name.endsWith('.jsonl') && !name.endsWith('.trajectory.jsonl') ? path : null;
+  }
   if (harness === 'gemini') return name.endsWith('.jsonl') && pathUnder(join(root, 'tmp'), path) ? path : null;
   if (harness === 'grok') {
     const part = relative(root, path).split(sep);

package/startup-prompts.mjs

@@ -0,0 +1,64 @@
+// Generated from crates/harness/src/startup_prompts.json by scripts/startup-prompts.mjs (the pre-commit hook runs it):
+// edit that table, not this file.
+export const STARTUP_PROMPTS = Object.freeze({
+  "claude-code": {
+    "startup": [],
+    "unattended": [
+      "--dangerously-skip-permissions"
+    ],
+    "unattended_chosen_by": [
+      "--permission-mode",
+      "--permission-prompts",
+      "--dangerously-skip-permissions",
+      "--allow-dangerously-skip-permissions"
+    ]
+  },
+  "codex": {
+    "startup": [
+      [
+        "-c",
+        "check_for_update_on_startup=false"
+      ],
+      [
+        "-c",
+        "projects={{cwd}={trust_level=\"trusted\"}}"
+      ],
+      [
+        "--no-alt-screen"
+      ],
+      [
+        "--dangerously-bypass-hook-trust"
+      ]
+    ],
+    "unattended": [
+      "--dangerously-bypass-approvals-and-sandbox"
+    ],
+    "unattended_chosen_by": [
+      "-a",
+      "--ask-for-approval",
+      "-s",
+      "--sandbox",
+      "--approve-for-me",
+      "--dangerously-bypass-approvals-and-sandbox"
+    ]
+  },
+  "gemini": {
+    "startup": [],
+    "unattended": [
+      "--yolo"
+    ],
+    "unattended_chosen_by": [
+      "--yolo",
+      "--approval-mode"
+    ]
+  },
+  "pi": {
+    "startup": [],
+    "unattended": [
+      "--approve"
+    ],
+    "unattended_chosen_by": [
+      "--approve"
+    ]
+  }
+});