blun-king-cli 9.1.567 → 9.1.569

package/agent-spine-plugin/src/lib/session-timeline-auth.js

@@ -0,0 +1,316 @@
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { lstat, mkdir, open, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { replaceFileWithRetry } from "./filesystem-retry.js";
+import { stateRoot } from "./paths.js";
+import { sessionTimelineRootDigest } from "./session-timeline-root.js";
+import { verifyWindowsTimelineDirectoryAcl, verifyWindowsTimelineFileAcl } from "./session-timeline-windows-acl.js";
+
+const KEY_BYTES = 32;
+const SIGNATURE_RE = /^[a-f0-9]{64}$/;
+const HEAD_SCHEMA = "agentspine.session-timeline-head/v1";
+const HEAD_MAX_BYTES = 64 * 1024;
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function payload(state) {
+  const { signature: _signature, ...unsigned } = state;
+  return canonical(unsigned);
+}
+
+function privateMode(metadata) {
+  return process.platform !== "win32" && (metadata.mode & 0o077n) !== 0n;
+}
+
+function unsafeDirectory(metadata) {
+  return !metadata.isDirectory() || metadata.isSymbolicLink()
+    || (process.platform !== "win32" && (metadata.mode & 0o022n) !== 0n);
+}
+
+function ownerMatches(metadata) {
+  return typeof process.getuid !== "function" || metadata.uid === BigInt(process.getuid());
+}
+
+async function stateDirectory(create) {
+  const path = stateRoot();
+  if (create) await mkdir(path, { recursive: true, mode: 0o700 });
+  const metadata = await lstat(path, { bigint: true });
+  if (unsafeDirectory(metadata)) throw new Error("session timeline state root is invalid");
+  await verifyWindowsTimelineDirectoryAcl(path, { metadata, role: "parent" });
+  return { path, metadata };
+}
+
+async function integrityDirectory(create) {
+  const root = await stateDirectory(create);
+  const path = join(root.path, "integrity");
+  let created = false;
+  if (create) {
+    try { await mkdir(path, { mode: 0o700 }); created = true; }
+    catch (error) { if (error.code !== "EEXIST") throw error; }
+  }
+  let metadata = await lstat(path, { bigint: true });
+  await verifyWindowsTimelineDirectoryAcl(path, { created, metadata, role: "integrity" });
+  metadata = await lstat(path, { bigint: true });
+  if (unsafeDirectory(metadata) || privateMode(metadata) || !ownerMatches(metadata)) {
+    throw new Error("session timeline integrity directory is invalid");
+  }
+  return { path, metadata, parent: root };
+}
+
+function sameDirectory(left, right) {
+  return left.isDirectory() && right.isDirectory() && !left.isSymbolicLink() && !right.isSymbolicLink()
+    && left.dev === right.dev && left.ino === right.ino;
+}
+
+async function assertStateDirectory(anchor) {
+  const metadata = await lstat(anchor.path, { bigint: true });
+  if (unsafeDirectory(metadata) || !sameDirectory(anchor.metadata, metadata)) {
+    throw new Error("session timeline state root changed during operation");
+  }
+  await verifyWindowsTimelineDirectoryAcl(anchor.path, { metadata, role: "parent" });
+  return metadata;
+}
+
+async function assertIntegrityDirectory(anchor) {
+  await assertStateDirectory(anchor.parent);
+  const metadata = await lstat(anchor.path, { bigint: true });
+  if (unsafeDirectory(metadata) || privateMode(metadata) || !ownerMatches(metadata) || !sameDirectory(anchor.metadata, metadata)) {
+    throw new Error("session timeline integrity directory changed during operation");
+  }
+  await verifyWindowsTimelineDirectoryAcl(anchor.path, { metadata, role: "integrity" });
+  return metadata;
+}
+
+function keyPath(integrity) {
+  return join(integrity.path, "session-timeline-signing.key");
+}
+
+function safePrivateFile(metadata, maximumBytes = null) {
+  return metadata.isFile() && !metadata.isSymbolicLink() && metadata.nlink === 1n
+    && (maximumBytes === null || metadata.size <= BigInt(maximumBytes))
+    && !privateMode(metadata) && ownerMatches(metadata);
+}
+
+async function verifyPrivateTimelineFile(path, metadata, role = "private", { created = false } = {}) {
+  if (!safePrivateFile(metadata)) throw new Error("session timeline private file is invalid");
+  await verifyWindowsTimelineFileAcl(path, { created, metadata, role });
+}
+
+async function verifyExistingPrivateTimelineFile(path, role = "private", maximumBytes = null) {
+  try {
+    const metadata = await lstat(path, { bigint: true });
+    if (!safePrivateFile(metadata, maximumBytes)) throw new Error("session timeline private file is invalid");
+    await verifyWindowsTimelineFileAcl(path, { metadata, role });
+    return metadata;
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function existingKey(path, integrity) {
+  await assertIntegrityDirectory(integrity);
+  const metadata = await lstat(path, { bigint: true });
+  if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.nlink !== 1n || metadata.size !== BigInt(KEY_BYTES)
+    || privateMode(metadata) || !ownerMatches(metadata)) {
+    throw new Error("session timeline signing key is invalid");
+  }
+  await verifyWindowsTimelineFileAcl(path, { metadata, role: "key" });
+  const handle = await open(path, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0));
+  try {
+    const before = await handle.stat({ bigint: true });
+    if (!sameFile(metadata, before)) throw new Error("session timeline signing key is invalid");
+    await verifyWindowsTimelineFileAcl(path, { metadata: before, role: "key" });
+    const value = await handle.readFile();
+    const after = await handle.stat({ bigint: true });
+    if (!sameFile(before, after) || after.nlink !== 1n || value.byteLength !== KEY_BYTES) {
+      throw new Error("session timeline signing key is invalid");
+    }
+    await verifyWindowsTimelineFileAcl(path, { metadata: after, role: "key" });
+    await assertIntegrityDirectory(integrity);
+    return value;
+  } finally { await handle.close(); }
+}
+
+async function signingKey({ create }) {
+  const integrity = await integrityDirectory(create);
+  const path = keyPath(integrity);
+  try { return await existingKey(path, integrity); }
+  catch (error) {
+    if (!create || error.code !== "ENOENT") throw error;
+  }
+  const value = randomBytes(KEY_BYTES);
+  try {
+    await assertIntegrityDirectory(integrity);
+    const handle = await open(path, "wx", 0o600);
+    try {
+      await handle.writeFile(value);
+      const metadata = await handle.stat({ bigint: true });
+      if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.nlink !== 1n || metadata.size !== BigInt(KEY_BYTES)
+        || privateMode(metadata) || !ownerMatches(metadata)) throw new Error("session timeline signing key is invalid");
+    } finally { await handle.close(); }
+    const metadata = await lstat(path, { bigint: true });
+    await verifyPrivateTimelineFile(path, metadata, "key", { created: true });
+    await assertIntegrityDirectory(integrity);
+    return existingKey(path, integrity);
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    return existingKey(path, integrity);
+  }
+}
+
+export async function ensureSessionTimelineTrust({ create = false } = {}) {
+  const integrity = await integrityDirectory(create);
+  try { await existingKey(keyPath(integrity), integrity); }
+  catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    if (create) await signingKey({ create: true });
+  }
+}
+
+function timelineFileRole(namespace) {
+  if (namespace === "state") return "state";
+  return namespace.endsWith("head") ? "head" : "private";
+}
+
+export async function sessionTimelinePrivatePaths(root, namespace, { create = true } = {}) {
+  if (!/^[a-z-]{1,32}$/.test(namespace || "")) throw new Error("session timeline private namespace is invalid");
+  const integrity = await integrityDirectory(create);
+  const identifier = sessionTimelineRootDigest(root);
+  const assertStable = () => assertIntegrityDirectory(integrity);
+  const path = join(integrity.path, `session-timeline-${namespace}-${identifier}.json`);
+  await assertStable();
+  await verifyExistingPrivateTimelineFile(path, timelineFileRole(namespace));
+  return {
+    path,
+    lock: join(integrity.path, `session-timeline-${namespace}-${identifier}.lock`),
+    assertStable
+  };
+}
+
+export function sessionTimelineStatePaths(root, options = {}) {
+  return sessionTimelinePrivatePaths(root, "state", options);
+}
+
+function signature(value, key) {
+  return createHmac("sha256", key).update(payload(value)).digest("hex");
+}
+
+function digest(value) { return createHash("sha256").update(value).digest("hex"); }
+function sameFile(left, right) {
+  return left.isFile() && right.isFile() && !left.isSymbolicLink() && !right.isSymbolicLink()
+    && left.dev === right.dev && left.ino === right.ino && left.size === right.size
+    && left.nlink === right.nlink && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+
+export async function readAuthenticatedTimelineState(path, maximumBytes, assertStable = null) {
+  await assertStable?.();
+  const pathname = await lstat(path, { bigint: true });
+  if (!pathname.isFile() || pathname.isSymbolicLink() || pathname.nlink !== 1n || pathname.size > BigInt(maximumBytes)) {
+    throw new Error("session timeline state is invalid");
+  }
+  await verifyWindowsTimelineFileAcl(path, { metadata: pathname, role: "private" });
+  const handle = await open(path, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0));
+  try {
+    const before = await handle.stat({ bigint: true });
+    if (!sameFile(pathname, before) || before.nlink !== 1n) throw new Error("session timeline state is invalid");
+    await verifyWindowsTimelineFileAcl(path, { metadata: before, role: "private" });
+    const content = await handle.readFile();
+    const after = await handle.stat({ bigint: true });
+    if (!sameFile(before, after) || after.nlink !== 1n || content.byteLength !== Number(after.size)) {
+      throw new Error("session timeline state changed during read");
+    }
+    await verifyWindowsTimelineFileAcl(path, { metadata: after, role: "private" });
+    await assertStable?.();
+    return content.toString("utf8");
+  } finally { await handle.close(); }
+}
+
+function headPath(integrity, root) {
+  return join(integrity.path, `session-timeline-head-${sessionTimelineRootDigest(root)}.json`);
+}
+
+async function saveHead(integrity, root, stateSignature, assertOwned = null) {
+  const path = headPath(integrity, root);
+  await verifyExistingPrivateTimelineFile(path, "head", HEAD_MAX_BYTES);
+  const head = { schema: HEAD_SCHEMA, rootDigest: sessionTimelineRootDigest(root), stateSignature, authority: "state-integrity-only" };
+  head.signature = signature(head, await signingKey({ create: true }));
+  const content = `${JSON.stringify(head)}\n`;
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  await assertIntegrityDirectory(integrity);
+  await writeFile(temporary, content, { mode: 0o600 });
+  try {
+    await verifyPrivateTimelineFile(temporary, await lstat(temporary, { bigint: true }), "head", { created: true });
+    await replaceFileWithRetry(temporary, path, { beforeAttempt: async () => {
+      await assertIntegrityDirectory(integrity); await assertOwned?.();
+    } });
+    await verifyPrivateTimelineFile(path, await lstat(path, { bigint: true }), "head");
+    await assertIntegrityDirectory(integrity);
+  }
+  catch (error) {
+    await unlink(temporary).catch((cleanup) => { if (cleanup.code !== "ENOENT") error.cleanupError = cleanup; });
+    throw error;
+  }
+}
+
+export async function recordSessionTimelineHead({ root, stateSignature, assertOwned = null }) {
+  if (!SIGNATURE_RE.test(stateSignature || "")) throw new Error("session timeline state signature is invalid");
+  const integrity = await integrityDirectory(true);
+  await saveHead(integrity, root, stateSignature, assertOwned);
+}
+
+export async function sessionTimelineHeadExists({ root }) {
+  let integrity;
+  try { integrity = await integrityDirectory(false); }
+  catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+  try {
+    const path = headPath(integrity, root);
+    await verifyExistingPrivateTimelineFile(path, "head", HEAD_MAX_BYTES);
+    await lstat(path, { bigint: true });
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+export async function verifySessionTimelineHead({ root, stateSignature }) {
+  let integrity;
+  let head;
+  try {
+    integrity = await integrityDirectory(false);
+    head = JSON.parse(await readAuthenticatedTimelineState(headPath(integrity, root), HEAD_MAX_BYTES,
+      () => assertIntegrityDirectory(integrity)));
+  }
+  catch { throw new Error("session timeline state head is unavailable"); }
+  if (head?.schema !== HEAD_SCHEMA || head.rootDigest !== sessionTimelineRootDigest(root) || !SIGNATURE_RE.test(head.stateSignature || "")
+    || head.authority !== "state-integrity-only") throw new Error("session timeline state head is invalid");
+  await verifySessionTimelineState(head);
+  await assertIntegrityDirectory(integrity);
+  if (head.stateSignature !== stateSignature) throw new Error("session timeline state replay was rejected");
+}
+
+export async function sealSessionTimelineState(state) {
+  state.signature = signature(state, await signingKey({ create: true }));
+  return state;
+}
+
+export async function verifySessionTimelineState(state) {
+  if (!SIGNATURE_RE.test(state?.signature || "")) throw new Error("session timeline state authentication failed");
+  const expected = Buffer.from(signature(state, await signingKey({ create: false })), "hex");
+  const actual = Buffer.from(state.signature, "hex");
+  if (actual.byteLength !== expected.byteLength || !timingSafeEqual(actual, expected)) {
+    throw new Error("session timeline state authentication failed");
+  }
+  return state;
+}

package/agent-spine-plugin/src/lib/session-timeline-codex.js

@@ -0,0 +1,58 @@
+import { constants } from "node:fs";
+import { open, realpath } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { matchesSourceMetadata } from "./session-timeline-source.js";
+
+export const CODEX_HISTORY_ADAPTER = "codex-rollout-jsonl/v1";
+export const CODEX_HISTORY_CONTRACT_COMMIT = "6af345407d9c2a568da9d01b6c4b81a9e61495c0";
+const HEADER_BYTES = 64 * 1024;
+const ID = /^[A-Za-z0-9][A-Za-z0-9:_.@/-]{0,127}$/;
+const RECORDS = new Set(["session_meta", "response_item", "event_msg", "compacted", "turn_context",
+  "token_usage_record", "world_state", "retained_context", "security_risk_score", "realtime_item",
+  "inter_agent_communication", "inter_agent_communication_metadata"]);
+
+// Read only the explicitly supplied native source. No directory discovery,
+// decompression, inherited-history traversal or source rewriting is allowed.
+export async function validateCodexTimelineHeader({ source, root, sessionId }) {
+  let handle;
+  try {
+    handle = await open(source.path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+    if (!matchesSourceMetadata(await handle.stat({ bigint: true }), source)) return false;
+    const bytes = Buffer.alloc(Math.min(source.size, HEADER_BYTES));
+    const read = await handle.read(bytes, 0, bytes.length, 0);
+    const end = bytes.indexOf(0x0a);
+    if (read.bytesRead !== bytes.length || end < 0) return false;
+    const line = JSON.parse(bytes.subarray(0, end).toString("utf8"));
+    const meta = line?.payload;
+    if (line.type !== "session_meta" || !meta || meta.id !== sessionId
+      || (meta.session_id !== undefined && meta.session_id !== sessionId)
+      || !ID.test(meta.id) || !isAbsolute(meta.cwd || "")
+      || typeof meta.cli_version !== "string" || !/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(meta.cli_version)
+      || (meta.history_mode !== undefined && meta.history_mode !== "legacy")
+      || meta.history_base || meta.parent_thread_id || meta.forked_from_id
+      || meta.schema_version !== undefined || line.schema_version !== undefined) return false;
+    if (await realpath(meta.cwd) !== root) return false;
+    return matchesSourceMetadata(await handle.stat({ bigint: true }), source);
+  } catch { return false; }
+  finally { await handle?.close(); }
+}
+
+// Whitelist actual Responses output records, never assistant/user assertions.
+// The caller applies the common secret/injection filter to the original line.
+export function codexTimelineToolResult(line) {
+  if (!RECORDS.has(line?.type) || line.schema_version !== undefined) {
+    throw new Error("codex-history-format-mismatch");
+  }
+  if (line.type !== "response_item") return null;
+  const item = line.payload;
+  if (!item || !["function_call_output", "custom_tool_call_output", "mcp_tool_call_output"].includes(item.type)) return null;
+  if (!ID.test(item.call_id || "")) return null;
+  let output = item.output;
+  if (item.type === "mcp_tool_call_output") output = output?.content;
+  if (Array.isArray(output)) {
+    if (output.length > 12 || output.some(part => !["text", "input_text"].includes(part?.type)
+      || typeof part.text !== "string")) return null;
+    output = output.map(part => part.text).join("\n");
+  }
+  return typeof output === "string" ? { role: "tool", content: output, nativeMessageId: item.call_id } : null;
+}

package/agent-spine-plugin/src/lib/session-timeline-contract.js

@@ -0,0 +1,48 @@
+import { validTimelineHost } from "./session-timeline-provider.js";
+
+export const TIMELINE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9:_.@/-]{0,127}$/;
+
+export function safeTimelineId(value) {
+  return typeof value === "string" && TIMELINE_ID_RE.test(value) ? value : null;
+}
+
+export function sessionTimelineBinding({ host, sessionId, scope }) {
+  return {
+    host: validTimelineHost(host) ? host : null,
+    sessionId: safeTimelineId(sessionId),
+    entityId: safeTimelineId(scope?.entityId),
+    userId: safeTimelineId(scope?.userId),
+    tenantId: safeTimelineId(scope?.tenantId),
+    projectId: safeTimelineId(scope?.projectId),
+    groupId: safeTimelineId(scope?.groupId),
+    taskId: safeTimelineId(scope?.currentTaskId),
+    goalId: safeTimelineId(scope?.goalId),
+    goalStepId: safeTimelineId(scope?.goalStepId)
+  };
+}
+
+export function hasTimelineGroupScope(scope) {
+  return scope?.groupId !== undefined && scope.groupId !== null && scope.groupId !== "";
+}
+
+export function hasVerifiedTimelinePrivateScope(scope) {
+  return scope?.timelineVisibility === "private-verified";
+}
+
+export function completeTimelineBinding(value) {
+  return validTimelineHost(value.host) && !value.groupId
+    && ["sessionId", "entityId", "userId", "tenantId", "projectId", "taskId"].every((key) => value[key]);
+}
+
+export function sameTimelineBinding(left, right) {
+  return ["host", "sessionId", "entityId", "userId", "tenantId", "projectId", "groupId", "taskId", "goalId", "goalStepId"]
+    .every((key) => left[key] === right[key]);
+}
+
+export function validTimelineBinding(value) {
+  return value && validTimelineHost(value.host)
+    && [value.sessionId, value.entityId, value.userId, value.tenantId, value.projectId, value.taskId]
+      .every((item) => typeof item === "string" && TIMELINE_ID_RE.test(item))
+    && [value.groupId, value.goalId, value.goalStepId]
+      .every((item) => item === null || (typeof item === "string" && TIMELINE_ID_RE.test(item)));
+}

package/agent-spine-plugin/src/lib/session-timeline-enrollment-source.js

@@ -0,0 +1,41 @@
+import { createHash } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { open } from "node:fs/promises";
+import { matchesSourceMetadata } from "./session-timeline-source.js";
+
+export const PRIVATE_TIMELINE_PREFIX_BYTES = 4096;
+
+function digest(value) { return createHash("sha256").update(value).digest("hex"); }
+
+// A receipt and enrollment never read a complete host transcript.  A small
+// stable prefix makes later replacement detectable while append verification
+// establishes the bounded full commitment separately.
+export async function privateTimelinePrefixDigest(source, bytes = Math.min(source?.size, PRIVATE_TIMELINE_PREFIX_BYTES)) {
+  if (!Number.isSafeInteger(bytes) || bytes < 0 || bytes > PRIVATE_TIMELINE_PREFIX_BYTES) return null;
+  let handle;
+  try {
+    handle = await open(source.path, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0));
+    const before = await handle.stat({ bigint: true });
+    if (!matchesSourceMetadata(before, source) || before.size < BigInt(bytes)) return null;
+    const buffer = Buffer.alloc(bytes);
+    const { bytesRead } = bytes ? await handle.read(buffer, 0, bytes, 0) : { bytesRead: 0 };
+    const after = await handle.stat({ bigint: true });
+    if (bytesRead !== bytes || !matchesSourceMetadata(after, source) || after.size < BigInt(bytes)) return null;
+    return digest(buffer);
+  } catch {
+    return null;
+  } finally {
+    await handle?.close();
+  }
+}
+
+export async function normalizePrivateTimelineSource(source) {
+  const prefixBytes = Math.min(source.size, PRIVATE_TIMELINE_PREFIX_BYTES);
+  const prefixDigest = await privateTimelinePrefixDigest(source, prefixBytes);
+  if (!prefixDigest) return null;
+  return {
+    path: source.path, profileRoot: source.profileRoot, projectsRoot: source.projectsRoot,
+    pathDigest: source.pathDigest, identity: source.identity, size: source.size,
+    mtimeNs: source.mtimeNs, ctimeNs: source.ctimeNs, prefixBytes, prefixDigest, commitment: null
+  };
+}

package/agent-spine-plugin/src/lib/session-timeline-enrollment-storage.js

@@ -0,0 +1,132 @@
+import { randomUUID } from "node:crypto";
+import { unlink, writeFile } from "node:fs/promises";
+import { replaceFileWithRetry } from "./filesystem-retry.js";
+import {
+  readAuthenticatedTimelineState, sealSessionTimelineState, sessionTimelinePrivatePaths,
+  verifySessionTimelineState
+} from "./session-timeline-auth.js";
+
+export async function privateEnrollmentPaths(root, { create = true } = {}) {
+  const state = await sessionTimelinePrivatePaths(root, "enrollment", { create });
+  const head = await sessionTimelinePrivatePaths(root, "enrollment-head", { create });
+  return {
+    ...state,
+    headPath: head.path,
+    assertStable: async () => { await state.assertStable(); await head.assertStable(); }
+  };
+}
+
+function validHead(value, root, headSchema, headAuthority) {
+  return value && value.schema === headSchema && value.rootDigest === root.digest
+    && validGeneration(value.generation) && validSignature(value.signature)
+    && validSignature(value.stateSignature)
+    && (value.generation === 1 ? value.previousSignature === null : validSignature(value.previousSignature))
+    && value.authority === headAuthority;
+}
+
+function validSignature(value) { return /^[a-f0-9]{64}$/.test(value || ""); }
+function validGeneration(value) { return Number.isSafeInteger(value) && value > 0; }
+
+async function readHead(path, root, assertStable, headSchema, headAuthority, maximumBytes) {
+  const text = await readAuthenticatedTimelineState(path, maximumBytes, assertStable);
+  const head = await verifySessionTimelineState(JSON.parse(text));
+  if (!validHead(head, root, headSchema, headAuthority)) throw new Error("private timeline enrollment head is invalid");
+  return head;
+}
+
+export async function readPrivateEnrollmentState({
+  path, headPath, root, assertStable, assertOwned = null, empty, validate, headSchema, headAuthority, maximumBytes
+}) {
+  let text;
+  try {
+    text = await readAuthenticatedTimelineState(path, maximumBytes, assertStable);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    try { await readHead(headPath, root, assertStable, headSchema, headAuthority, maximumBytes); }
+    catch (headError) {
+      if (headError.code === "ENOENT") return empty(root.value);
+      throw headError;
+    }
+    throw new Error("private timeline enrollment state is missing");
+  }
+  const state = await verifySessionTimelineState(validate(JSON.parse(text), root.value));
+  const head = await readHead(headPath, root, assertStable, headSchema, headAuthority, maximumBytes);
+  if (matchesHead(state, head)) return state;
+  if (typeof assertOwned !== "function" || !recoverableForwardCommit(state, head)) {
+    throw new Error("private timeline enrollment state replay was rejected");
+  }
+  // A state replacement can survive a crash before its paired head replacement.
+  // Repair is allowed only while holding the owned lock and only for the exact
+  // authenticated one-generation successor of the retained head.  Re-read both
+  // records after writing so a path swap cannot produce usable content.
+  const freshState = await readAuthenticatedTimelineState(path, maximumBytes, assertStable);
+  const checkedState = await verifySessionTimelineState(validate(JSON.parse(freshState), root.value));
+  const checkedHead = await readHead(headPath, root, assertStable, headSchema, headAuthority, maximumBytes);
+  if (!sameState(state, checkedState) || !recoverableForwardCommit(checkedState, checkedHead)) {
+    throw new Error("private timeline enrollment state replay was rejected");
+  }
+  await savePrivateEnrollmentHead({ state: checkedState, path: headPath, root, assertOwned, assertStable,
+    headSchema, headAuthority, maximumBytes });
+  const finalStateText = await readAuthenticatedTimelineState(path, maximumBytes, assertStable);
+  const finalState = await verifySessionTimelineState(validate(JSON.parse(finalStateText), root.value));
+  const finalHead = await readHead(headPath, root, assertStable, headSchema, headAuthority, maximumBytes);
+  if (!matchesHead(finalState, finalHead)) throw new Error("private timeline enrollment state replay was rejected");
+  return finalState;
+}
+
+function matchesHead(state, head) {
+  return state.generation === head.generation && state.signature === head.stateSignature
+    && state.previousSignature === head.previousSignature;
+}
+
+function sameState(left, right) {
+  return left.generation === right.generation && left.previousSignature === right.previousSignature
+    && left.signature === right.signature;
+}
+
+function recoverableForwardCommit(state, head) {
+  return state.generation === head.generation + 1 && state.previousSignature === head.stateSignature;
+}
+
+async function saveSigned(value, path, maximumBytes, label, assertOwned, assertStable) {
+  const assertWritable = async () => { await assertStable(); await assertOwned(); };
+  await assertWritable();
+  await sealSessionTimelineState(value);
+  const content = `${JSON.stringify(value)}\n`;
+  if (Buffer.byteLength(content) > maximumBytes) throw new Error(`${label} exceeds its byte budget`);
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(temporary, content, { mode: 0o600 });
+  try {
+    await replaceFileWithRetry(temporary, path, { beforeAttempt: assertWritable });
+    await assertWritable();
+  } catch (error) {
+    await unlink(temporary).catch((cleanup) => { if (cleanup.code !== "ENOENT") error.cleanupError = cleanup; });
+    throw error;
+  }
+}
+
+export async function savePrivateEnrollmentState({
+  state, path, headPath, root, assertOwned, assertStable, headSchema, headAuthority, maximumBytes
+}) {
+  if (!Number.isSafeInteger(state.generation) || state.generation < 0 || state.generation >= Number.MAX_SAFE_INTEGER
+    || (state.generation > 0 && !validSignature(state.signature))) {
+    throw new Error("private timeline enrollment generation is invalid");
+  }
+  state.previousSignature = state.generation === 0 ? null : state.signature;
+  state.generation += 1;
+  delete state.signature;
+  await saveSigned(state, path, maximumBytes, "private timeline enrollment state", assertOwned, assertStable);
+  await savePrivateEnrollmentHead({ state, path: headPath, root, assertOwned, assertStable,
+    headSchema, headAuthority, maximumBytes });
+}
+
+export async function savePrivateEnrollmentHead({
+  state, path, root, assertOwned, assertStable, headSchema, headAuthority, maximumBytes
+}) {
+  const head = {
+    schema: headSchema, rootDigest: root.digest, generation: state.generation,
+    stateSignature: state.signature, previousSignature: state.previousSignature,
+    authority: headAuthority
+  };
+  await saveSigned(head, path, maximumBytes, "private timeline enrollment head", assertOwned, assertStable);
+}

package/agent-spine-plugin/src/lib/session-timeline-enrollment-transport.js

@@ -0,0 +1,17 @@
+import { sameTimelineBinding } from "./session-timeline-contract.js";
+import { resolvePrivateSessionTimelineEnrollment } from "./session-timeline-enrollment.js";
+import { validTimelineTransportDigest } from "./session-timeline-transport.js";
+
+// Keep the digest inside the signed enrollment record. This verifier returns
+// only a boolean so neither the transport value nor its digest reaches cards.
+export async function timelineTransportEnrollmentMatches({
+  root, binding, enrollmentDigest, transportDigest, hostHome = null
+}) {
+  if (!validTimelineTransportDigest(transportDigest) || !/^[a-f0-9]{64}$/.test(enrollmentDigest || "")) return false;
+  const enrollment = await resolvePrivateSessionTimelineEnrollment({
+    root, host: binding?.host, sessionId: binding?.sessionId, hostHome,
+    expectedTransportDigest: transportDigest
+  });
+  return enrollment.status === "enrolled" && enrollment.enrollmentDigest === enrollmentDigest
+    && sameTimelineBinding(enrollment.binding, binding);
+}