@volter/supercode-interchange 0.1.4 → 0.1.5

package/README.md

@@ -110,6 +110,19 @@ cover recorded posture/policies through npm and operator streams, including
 unknown posture for malformed records. The manifest's other branches,
 corpus/scale, concurrent reads and independent source review remain open.
 
+`sessions.launch_agent` reads `<harness home>/supercode/launches/<session id>.json`
+in the same caller-owned load lane. Claude `projects` and Codex `sessions`
+ancestors select the transcript's recorded home, independent of current vendor
+defaults; no transcript must exist. Unsupported locators, unsafe ids, absent,
+invalid UTF-8 or malformed records, and nonobject environments return null.
+The environment is recorded metadata, never caller authority. The new
+`launch_agent` capability marker refuses older read services explicitly.
+Native runtime launch-record writers remain for their separate replacement.
+[Private Mac/Windows conversations](../../docs/evidence/session-launch-metadata-2026-10-08.md)
+record selected-home answers and null malformed metadata through npm and
+operator streams; concurrent path/record replacement and runtime writing remain
+unqualified.
+
 `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.

package/package.json

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

package/session-launch-agent.mjs

@@ -0,0 +1,30 @@
+// Recorded launch metadata is a reading, never caller authority. The native
+// runtime writer remains until its own replacement boundary.
+import { readFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, sep } from 'node:path';
+import { parseNativeJson } from './native-json.mjs';
+
+export function recordedLaunchAgent(locator, { cwd = process.cwd() } = {}) {
+  if (locator.storage.kind !== 'file' || !locator.session_id.length
+    || /[^A-Za-z0-9_-]/.test(locator.session_id)) return null;
+  const store = locator.harness === 'codex' ? 'sessions' : locator.harness === 'claude-code' ? 'projects' : null;
+  if (store == null) return null;
+  // Walk the lexical path, starting with the path itself as Path::ancestors
+  // does. Resolving '..' first could choose a different recorded harness home.
+  let at = locator.storage.path, home = null;
+  for (;;) {
+    if (basename(at) === store) { home = dirname(at); break; }
+    const parent = dirname(at);
+    if (parent === at || at === '.') break;
+    at = parent;
+  }
+  if (home == null) return null;
+  // Leave '..' for the filesystem, including its symlink semantics.
+  const path = `${isAbsolute(home) ? '' : `${cwd}${sep}`}${home}${sep}supercode${sep}launches${sep}${locator.session_id}.json`;
+  try {
+    const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(readFileSync(path));
+    const record = parseNativeJson(text);
+    const environment = record && !Array.isArray(record) && typeof record === 'object' ? record.environment : null;
+    return environment && !Array.isArray(environment) && typeof environment === 'object' ? environment : null;
+  } catch { return null; }
+}

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 }>;
+export const SESSION_READ_CAPABILITY: Readonly<{ version: 1; owner: 'caller'; language: 'typescript'; native_parser: false; recorded_config: true; launch_agent: true }>;
 export interface SessionReadContext { cwd?: string; env?: Record<string, string | undefined> }
 export function parseSessionWire(text: string): unknown;
 export function stringifySessionWire(value: unknown): string;
@@ -12,3 +12,5 @@ export function loadSessionRead(params: unknown, context?: SessionReadContext):
 export function openSessionReadFollower(params: unknown, context?: SessionReadContext): Promise<SessionFollower>;
 /** Recorded values only; malformed complete Claude runtime state leaves mode unknown. */
 export function loadRecordedSessionConfiguration(params: unknown, context?: SessionReadContext): Promise<{ harness: string; session_id: string | null; cwd: unknown; model: unknown; approval_policy: unknown; sandbox_policy: unknown; permission_mode: string | null }>;
+/** Best-effort recorded environment only, independent of transcript existence or caller authority. */
+export function loadSessionLaunchAgent(params: unknown, context?: SessionReadContext): Promise<{ environment: Record<string, unknown> | null }>;

package/session-read.mjs

@@ -9,10 +9,11 @@ import { SessionFollower } from './session-follower.mjs';
 import { normalizedSessionJson } from './session-model.mjs';
 import { boundSessionView, projectedMessageWindow, projectedSessionJson, projectedSessionResult, projectedSessionSummary, recordedSessionProfile, recordedSessionProfileHistory } from './session-views.mjs';
 import { recordedSessionConfiguration } from './session-recorded-config.mjs';
+import { recordedLaunchAgent } from './session-launch-agent.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']);
+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']);
 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 });
+export const SESSION_READ_CAPABILITY = Object.freeze({ version: 1, owner: 'caller', language: 'typescript', native_parser: false, recorded_config: true, launch_agent: true });
 export { parseNativeJson as parseSessionWire, stringifyNativeJson as stringifySessionWire };
 const invalid = (message) => { throw Object.assign(new Error(message), { rpcCode: -32602 }); };
 const object = (value, name) => {
@@ -111,3 +112,12 @@ export async function loadRecordedSessionConfiguration(params, context = {}) {
   const { locator } = parseSessionReadParams({ locator: params.locator }, context);
   return recordedSessionConfiguration(await loadSessionLocator(locator, { ...context, fidelity: 'byte_lossless', includeSubagents: true }), locator.harness);
 }
+
+export async function loadSessionLaunchAgent(params, context = {}) {
+  object(params, 'launch metadata params');
+  const { locator } = parseSessionReadParams({ locator: params.locator }, context);
+  // This door needs no transcript or parser. Preserve the original lexical
+  // path for the harness-home lookup, rather than the normalized load path.
+  locator.storage.path = params.locator.storage.path;
+  return { environment: recordedLaunchAgent(locator, context) };
+}