blun-king-cli 9.1.567 → 9.1.569

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

@@ -0,0 +1,11 @@
+import { createHash } from "node:crypto";
+import { comparablePath } from "./paths.js";
+
+export function sessionTimelineRootPath(root) {
+  if (typeof root !== "string" || !root) throw new Error("session timeline root is invalid");
+  return comparablePath(root);
+}
+
+export function sessionTimelineRootDigest(root) {
+  return createHash("sha256").update(sessionTimelineRootPath(root)).digest("hex");
+}

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

@@ -0,0 +1,82 @@
+function parseEvents(buffer, start, eventFromLine) {
+  const events = [];
+  let cursor = 0;
+  while (cursor < buffer.byteLength) {
+    const newline = buffer.indexOf(0x0a, cursor);
+    const end = newline < 0 ? buffer.byteLength : newline + 1;
+    if (end > cursor) {
+      const event = eventFromLine(buffer.subarray(cursor, end).toString("utf8"), start + cursor);
+      if (event) events.push(event);
+    }
+    cursor = end;
+  }
+  return events;
+}
+
+async function timestampLineAt({ handle, position, size, last, readRange, extractTimestamp }) {
+  const start = Math.max(0, Math.min(position, Math.max(0, size - 1)));
+  const bytes = await readRange(handle, start, Math.min(128 * 1024, size - start));
+  let cursor = start === 0 ? 0 : bytes.indexOf(0x0a) + 1;
+  if (cursor >= bytes.byteLength || (start > 0 && cursor <= 0)) return null;
+  let result = null;
+  while (cursor < bytes.byteLength) {
+    const ending = bytes.indexOf(0x0a, cursor);
+    const end = ending < 0 ? bytes.byteLength : ending + 1;
+    if (end <= cursor) return null;
+    try {
+      const at = extractTimestamp(JSON.parse(bytes.subarray(cursor, end).toString("utf8")));
+      if (at) {
+        result = { at, offset: start + cursor };
+        if (!last) return result;
+      }
+    } catch {}
+    cursor = end;
+  }
+  return result;
+}
+
+async function seekTimestamp({ handle, size, target, readRange, extractTimestamp }) {
+  const lower = await timestampLineAt({ handle, position: 0, size, last: false, readRange, extractTimestamp });
+  const upper = await timestampLineAt({ handle, position: Math.max(0, size - 128 * 1024), size, last: true, readRange, extractTimestamp });
+  if (!lower || !upper) return { status: "unavailable", reason: "timeline-not-seekable" };
+  const lowerAt = new Date(lower.at).getTime();
+  const upperAt = new Date(upper.at).getTime();
+  const targetAt = target.getTime();
+  if (lowerAt > upperAt) return { status: "unavailable", reason: "timeline-not-monotonic" };
+  if (targetAt < lowerAt) return { status: "before-start", offset: lower.offset };
+  if (targetAt > upperAt) return { status: "out-of-range" };
+  let left = lower;
+  let right = upper;
+  for (let count = 0; count < 24 && right.offset - left.offset > 128 * 1024; count += 1) {
+    const probe = await timestampLineAt({ handle, position: Math.floor((left.offset + right.offset) / 2), size,
+      last: false, readRange, extractTimestamp });
+    if (!probe) return { status: "unavailable", reason: "timeline-not-seekable" };
+    const value = new Date(probe.at).getTime();
+    if (value < new Date(left.at).getTime() || value > new Date(right.at).getTime()) {
+      return { status: "unavailable", reason: "timeline-not-monotonic" };
+    }
+    if (value <= targetAt) left = probe;
+    else right = probe;
+  }
+  return { status: "found", offset: left.offset };
+}
+
+export async function seekTimelineEvidence({ handle, size, target, wanted, windowMs, readRange, eventFromLine,
+  extractTimestamp, matches, rank }) {
+  const start = await seekTimestamp({ handle, size, target: new Date(target.getTime() - windowMs), readRange, extractTimestamp });
+  if (!["found", "before-start"].includes(start.status)) return start;
+  const bytes = await readRange(handle, start.offset, Math.min(4 * 1024 * 1024, size - start.offset));
+  const ending = bytes.lastIndexOf(0x0a);
+  const selected = ending < 0 && start.offset + bytes.byteLength !== size ? -1 : ending < 0 ? bytes.byteLength : ending + 1;
+  if (selected < 0) return { status: "unavailable", reason: "timeline-not-seekable" };
+  const events = rank(parseEvents(bytes.subarray(0, selected), start.offset, eventFromLine)
+    .filter((event) => matches(event, wanted, target, windowMs)), wanted, target).slice(0, 8);
+  return { status: "searched", events, budgetExhausted: selected < size - start.offset };
+}
+
+export async function verifyTimelineEvent({ handle, event, readRange, digest, eventFromLine }) {
+  if (!Number.isSafeInteger(event.offset) || !Number.isSafeInteger(event.bytes) || event.bytes > 1024 * 1024) return null;
+  const raw = await readRange(handle, event.offset, event.bytes);
+  if (raw.byteLength !== event.bytes || digest(raw) !== event.sha256) return null;
+  return eventFromLine(raw.toString("utf8"), event.offset);
+}

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

@@ -0,0 +1,217 @@
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { lstat, mkdtemp, open, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Numeric FileSystemRights values and SDDL tokens are stable across Windows
+// display languages. Friendly account names never enter the authorization path.
+const FULL_CONTROL = 0x001f01ff;
+const WRITE_MASK = 0x000d0156;
+const GENERIC_WRITE_MASK = 0x50000000;
+const MAX_ACL_BYTES = 1024 * 1024;
+const SID = /^S-1-\d+(?:-\d+)+$/i;
+const DACL_FLAGS = /^(?:(?:P|AR|AI))*$/;
+const ACE_FLAGS = new Set(["CI", "OI", "NP", "IO", "ID"]);
+const RIGHT_TOKENS = new Set([
+  "GA", "GR", "GW", "GX", "RC", "SD", "WD", "WO",
+  "RP", "WP", "CC", "DC", "LC", "SW", "LO", "DT", "CR",
+  "FA", "FR", "FW", "FX", "KA", "KR", "KW", "KX",
+  "NR", "NW", "NX"
+]);
+const WRITE_TOKENS = new Set([
+  "GA", "GW", "SD", "WD", "WO", "WP", "CC", "DC", "SW", "DT", "CR",
+  "FA", "FW", "KA", "KW"
+]);
+const TRUSTEE_ALIASES = new Map([
+  ["SY", "s-1-5-18"],
+  ["BA", "s-1-5-32-544"],
+  ["CO", "s-1-3-0"],
+  ["LA", "sddl:la"]
+]);
+
+function splitTokens(value, allowed, label) {
+  if (value.length % 2 !== 0) {
+    throw new Error(`session timeline Windows SDDL ${label} is malformed`);
+  }
+  const tokens = value.match(/../g) || [];
+  if (tokens.some(token => !allowed.has(token))) {
+    throw new Error(`session timeline Windows SDDL ${label} is unsupported`);
+  }
+  return tokens;
+}
+
+function principalFromSddl(value, localAdministratorSid) {
+  if (SID.test(value)) return value.toLowerCase();
+  if (value === "LA" && SID.test(localAdministratorSid || "")
+    && localAdministratorSid.toLowerCase().endsWith("-500")) {
+    return localAdministratorSid.toLowerCase();
+  }
+  if (TRUSTEE_ALIASES.has(value)) return TRUSTEE_ALIASES.get(value);
+  if (/^[A-Z]{2}$/.test(value)) return `sddl:${value.toLowerCase()}`;
+  throw new Error("session timeline Windows SDDL trustee is malformed");
+}
+
+function numericRights(value) {
+  if (!/^0x[0-9a-f]{1,8}$/i.test(value)) return null;
+  return Number.parseInt(value.slice(2), 16) >>> 0;
+}
+
+function rightsFromSddl(value, type, flags) {
+  const rights = [];
+  if (flags.includes("ID")) rights.push("I");
+  if (flags.includes("IO")) rights.push("IO");
+  if (type === "D") return [...rights, "DENY"];
+  const mask = numericRights(value);
+  if (mask === null) {
+    const tokens = splitTokens(value, RIGHT_TOKENS, "rights");
+    if (tokens.includes("FA") || tokens.includes("GA")) rights.push("F");
+    if (tokens.some(token => WRITE_TOKENS.has(token))) rights.push("W");
+    return rights;
+  }
+  if ((mask & FULL_CONTROL) === FULL_CONTROL || (mask & 0x10000000) !== 0) rights.push("F");
+  if ((mask & WRITE_MASK) !== 0 || (mask & GENERIC_WRITE_MASK) !== 0) rights.push("W");
+  return rights;
+}
+
+export function parseWindowsSddlAcl(sddl, { localAdministratorSid = null } = {}) {
+  if (typeof sddl !== "string" || sddl.length > MAX_ACL_BYTES) {
+    throw new Error("session timeline Windows SDDL is unavailable");
+  }
+  const value = sddl.replace(/^\uFEFF/, "").trim();
+  if (!value.startsWith("D:")) throw new Error("session timeline Windows SDDL has no DACL");
+  const firstAce = value.indexOf("(", 2);
+  if (firstAce < 0 || !DACL_FLAGS.test(value.slice(2, firstAce))) {
+    throw new Error("session timeline Windows SDDL flags are malformed");
+  }
+  const entries = [];
+  let offset = firstAce;
+  while (offset < value.length) {
+    const match = /^\(([^()]*)\)/.exec(value.slice(offset));
+    if (!match) throw new Error("session timeline Windows SDDL ACE is malformed");
+    const fields = match[1].split(";");
+    if (fields.length !== 6 || !["A", "D"].includes(fields[0]) || fields[3] || fields[4]) {
+      throw new Error("session timeline Windows SDDL ACE is unsupported");
+    }
+    const flags = splitTokens(fields[1], ACE_FLAGS, "ACE flags");
+    const principal = principalFromSddl(fields[5], localAdministratorSid);
+    entries.push({ principal, rights: rightsFromSddl(fields[2], fields[0], flags) });
+    if (entries.length > 2048) throw new Error("session timeline Windows SDDL exceeds ACE limit");
+    offset += match[0].length;
+  }
+  if (!entries.length) throw new Error("session timeline Windows SDDL has no ACEs");
+  return entries;
+}
+
+export function parseWindowsAclSave(bytes, options = {}) {
+  if (!Buffer.isBuffer(bytes) || !bytes.length || bytes.length > MAX_ACL_BYTES || bytes.length % 2 !== 0) {
+    throw new Error("session timeline Windows ACL save is unavailable");
+  }
+  const lines = bytes.toString("utf16le").replace(/^\uFEFF/, "").split(/\r?\n/).filter(Boolean);
+  if (lines.length !== 2 || !lines[0].trim() || !lines[1].trim().startsWith("D:")) {
+    throw new Error("session timeline Windows ACL save is malformed");
+  }
+  return parseWindowsSddlAcl(lines[1].trim(), options);
+}
+
+export function windowsAclSaveCommand(path, outputPath) {
+  return [path, "/save", outputPath, "/q"];
+}
+
+async function readStableAclFile(path, options) {
+  const pathname = await lstat(path, { bigint: true });
+  if (!pathname.isFile() || pathname.isSymbolicLink() || pathname.nlink !== 1n
+    || pathname.size <= 0n || pathname.size > BigInt(MAX_ACL_BYTES)) {
+    throw new Error("session timeline Windows ACL save is unsafe");
+  }
+  const handle = await open(path, "r");
+  try {
+    const before = await handle.stat({ bigint: true });
+    const bytes = await handle.readFile();
+    const after = await handle.stat({ bigint: true });
+    const current = await lstat(path, { bigint: true });
+    if (!current.isFile() || current.isSymbolicLink() || current.nlink !== 1n) {
+      throw new Error("session timeline Windows ACL save changed while reading");
+    }
+    for (const field of ["dev", "ino", "size", "mtimeNs", "ctimeNs"]) {
+      if (before[field] !== after[field] || after[field] !== current[field]) {
+        throw new Error("session timeline Windows ACL save changed while reading");
+      }
+    }
+    return parseWindowsAclSave(bytes, options);
+  } finally {
+    await handle.close();
+  }
+}
+
+export function windowsLocalAdministratorSid(identity, env) {
+  if (!identity || !SID.test(identity.sid || "") || typeof identity.account !== "string") return null;
+  const computer = typeof env?.COMPUTERNAME === "string" ? env.COMPUTERNAME.trim().toLowerCase() : "";
+  const [domain] = identity.account.trim().toLowerCase().split("\\");
+  if (!computer || domain !== computer || !identity.sid.toLowerCase().endsWith("-500")) return null;
+  return identity.sid.toLowerCase();
+}
+
+async function readNativeWindowsAcl(path, env, runCommand, run, identity) {
+  const directory = await mkdtemp(join(tmpdir(), "agentspine-timeline-sddl-"));
+  const outputPath = join(directory, `${randomUUID()}.acl`);
+  try {
+    const claim = await open(outputPath, "wx", 0o600);
+    await claim.close();
+    const binary = join(env.SystemRoot, "System32", "icacls.exe");
+    runCommand(run, binary, windowsAclSaveCommand(path, outputPath), env);
+    return await readStableAclFile(outputPath, {
+      localAdministratorSid: windowsLocalAdministratorSid(identity, env)
+    });
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+// Retained only for dependency-injected compatibility tests. Production uses
+// icacls /save and parses its SID/SDDL export without starting PowerShell.
+export function windowsSidAclCommand(path) {
+  const encodedPath = Buffer.from(path, "utf8").toString("base64");
+  const script = [
+    "$ErrorActionPreference = 'Stop'",
+    `$target = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedPath}'))`,
+    "if ([IO.Directory]::Exists($target)) { $acl = [IO.Directory]::GetAccessControl($target) }",
+    "else { $acl = [IO.File]::GetAccessControl($target) }",
+    "$rules = @($acl.GetAccessRules($true, $true, [Security.Principal.SecurityIdentifier]) | ForEach-Object {",
+    "  [PSCustomObject]@{ sid=$_.IdentityReference.Value; mask=[int]$_.FileSystemRights; inherited=$_.IsInherited; propagation=[int]$_.PropagationFlags; inheritance=[int]$_.InheritanceFlags; type=[int]$_.AccessControlType }",
+    "})",
+    "$rules | ConvertTo-Json -Compress -AsArray"
+  ].join("\n");
+  return ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand",
+    Buffer.from(script, "utf16le").toString("base64")];
+}
+
+export async function readWindowsSidAcl(path, env, runCommand, run, identity = null) {
+  if (run === spawnSync) return readNativeWindowsAcl(path, env, runCommand, run, identity);
+  const binary = join(env.SystemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+  return parseWindowsSidAcl(runCommand(run, binary, windowsSidAclCommand(path), env));
+}
+
+export function parseWindowsSidAcl(output) {
+  const rows = JSON.parse(output);
+  if (!Array.isArray(rows) || !rows.length || rows.length > 2048) {
+    throw new Error("session timeline Windows SID ACL is unavailable");
+  }
+  return rows.map(row => {
+    if (!row || !SID.test(row.sid) || typeof row.inherited !== "boolean"
+      || !Number.isInteger(row.mask) || row.mask < 0 || row.mask > 0x1fffff
+      || ![0, 1].includes(row.type) || ![0, 1, 2, 3].includes(row.propagation)
+      || ![0, 1, 2, 3].includes(row.inheritance)) {
+      throw new Error("session timeline Windows SID ACL is malformed");
+    }
+    const rights = [];
+    if (row.inherited) rights.push("I");
+    if (row.propagation & 2) rights.push("IO");
+    if (row.type === 1) rights.push("DENY");
+    else {
+      if ((row.mask & FULL_CONTROL) === FULL_CONTROL) rights.push("F");
+      if (row.mask & WRITE_MASK) rights.push("W");
+    }
+    return { principal: row.sid.toLowerCase(), rights };
+  });
+}

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

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+import { lstat, realpath } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { comparablePath, isInside } from "./paths.js";
+import { validTimelineHost } from "./session-timeline-provider.js";
+
+function digest(value) { return createHash("sha256").update(value).digest("hex"); }
+
+function metadataValue(metadata, key) {
+  return String(metadata[key] ?? BigInt(Math.floor(Number(metadata[`${key.slice(0, -2)}Ms`]) * 1_000_000)));
+}
+
+function sourceIdentity(metadata) { return [metadata.dev, metadata.ino].join(":"); }
+
+const SOURCE_LOCATION_KEYS = ["path", "profileRoot", "projectsRoot", "pathDigest", "identity"];
+
+export function validSessionTimelineSourceMetadata(value) {
+  return value && typeof value.path === "string" && isAbsolute(value.path) && value.path.length <= 4096
+    && typeof value.profileRoot === "string" && isAbsolute(value.profileRoot) && value.profileRoot.length <= 4096
+    && typeof value.projectsRoot === "string" && isAbsolute(value.projectsRoot) && value.projectsRoot.length <= 4096
+    && value.pathDigest === digest(value.path) && typeof value.identity === "string" && value.identity.length > 0
+    && Number.isSafeInteger(value.size) && value.size >= 0
+    && /^[0-9]+$/.test(value.mtimeNs || "") && /^[0-9]+$/.test(value.ctimeNs || "");
+}
+
+export function sameSessionTimelineSourceLocation(left, right) {
+  return validSessionTimelineSourceMetadata(left) && validSessionTimelineSourceMetadata(right)
+    && SOURCE_LOCATION_KEYS.every((key) => left[key] === right[key]);
+}
+
+export async function sourcePath(value, hostHome, host = "claude") {
+  if (!validTimelineHost(host)) return { status: "unavailable", reason: "unknown-timeline-host" };
+  if (typeof value !== "string" || !isAbsolute(value)) return { status: "unavailable", reason: "no-validated-transcript" };
+  let profileRoot; let projectsRoot;
+  try {
+    if (!isAbsolute(hostHome || "")) throw new Error("invalid-host-root");
+    const profile = await lstat(hostHome);
+    if (!profile.isDirectory() || profile.isSymbolicLink()) throw new Error("invalid-host-root");
+    profileRoot = await realpath(hostHome);
+    const directory = ["codex", "king"].includes(host) ? "sessions" : "projects";
+    const projectsPath = join(profileRoot, directory);
+    const projects = await lstat(projectsPath);
+    if (!projects.isDirectory() || projects.isSymbolicLink()) throw new Error("invalid-host-root");
+    projectsRoot = await realpath(projectsPath);
+    if (!isInside(profileRoot, projectsRoot)) throw new Error("invalid-host-root");
+  }
+  catch (error) { return { status: "unavailable", reason: error.code === "ENOENT" ? "no-validated-transcript" : "transcript-root-unavailable" }; }
+  let metadata;
+  try { metadata = await lstat(value, { bigint: true }); }
+  catch (error) { return { status: "unavailable", reason: error.code === "ENOENT" ? "transcript-missing" : "transcript-unreadable" }; }
+  if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.nlink !== 1n) {
+    return { status: "unavailable", reason: "transcript-not-regular" };
+  }
+  let canonical;
+  try { canonical = await realpath(value); }
+  catch { return { status: "unavailable", reason: "transcript-unreadable" }; }
+  if (["codex", "king"].includes(host) && comparablePath(canonical) !== comparablePath(resolve(value))) {
+    return { status: "unavailable", reason: "transcript-symlink-path" };
+  }
+  if (!isInside(projectsRoot, canonical)) return { status: "unavailable", reason: "transcript-outside-host-projects" };
+  return { status: "registered", path: canonical, profileRoot, projectsRoot, pathDigest: digest(canonical),
+    identity: [metadata.dev, metadata.ino].join(":"), size: Number(metadata.size),
+    mtimeNs: metadataValue(metadata, "mtimeNs"), ctimeNs: metadataValue(metadata, "ctimeNs") };
+}
+
+export function matchesSourceMetadata(metadata, source) {
+  const identity = [metadata.dev, metadata.ino].join(":");
+  return metadata.isFile() && !metadata.isSymbolicLink() && metadata.nlink === 1n && identity === source.identity
+    && Number(metadata.size) === source.size && metadataValue(metadata, "mtimeNs") === source.mtimeNs
+    && metadataValue(metadata, "ctimeNs") === source.ctimeNs;
+}
+
+export async function pathMatchesSource(source, hostHome = null) {
+  // A post-compaction read may not have a fresh host root. The persisted
+  // enrollment root is the sealed authority in that case; ambient process
+  // configuration must never redirect a previously bound transcript.
+  const trustedHome = isAbsolute(hostHome || "") ? hostHome : source?.profileRoot;
+  if (!isAbsolute(trustedHome || "")) return false;
+  const current = await sourcePath(source.path, trustedHome, source.binding?.host || "claude");
+  return current.status === "registered" && current.profileRoot === source.profileRoot && current.projectsRoot === source.projectsRoot
+    && current.pathDigest === source.pathDigest && current.identity === source.identity
+    && current.size === source.size && current.mtimeNs === source.mtimeNs && current.ctimeNs === source.ctimeNs;
+}

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

@@ -0,0 +1,45 @@
+import { randomUUID } from "node:crypto";
+import { unlink, writeFile } from "node:fs/promises";
+import { replaceFileWithRetry } from "./filesystem-retry.js";
+import {
+  readAuthenticatedTimelineState, recordSessionTimelineHead, sealSessionTimelineState,
+  sessionTimelineHeadExists, verifySessionTimelineHead, verifySessionTimelineState
+} from "./session-timeline-auth.js";
+
+export async function readTimelineState({ path, root, maximumBytes, empty, validate, assertStable = null }) {
+  try {
+    const content = await readAuthenticatedTimelineState(path, maximumBytes, assertStable);
+    const state = await verifySessionTimelineState(validate(JSON.parse(content), root));
+    await verifySessionTimelineHead({ root, stateSignature: state.signature });
+    return state;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      if (await sessionTimelineHeadExists({ root })) throw new Error("session timeline state is missing after a signed head");
+      return empty(root);
+    }
+    throw error;
+  }
+}
+
+export async function saveTimelineState({ state, path, root, maximumBytes, assertOwned, assertStable = null }) {
+  const assertWritable = async () => {
+    await assertStable?.();
+    await assertOwned?.();
+  };
+  await assertWritable();
+  await sealSessionTimelineState(state);
+  const content = `${JSON.stringify(state, null, 2)}\n`;
+  if (Buffer.byteLength(content) > maximumBytes) throw new Error("session timeline state exceeds 16 MiB");
+  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;
+  }
+  await recordSessionTimelineHead({ root, stateSignature: state.signature, assertOwned: assertWritable });
+  await assertStable?.();
+}

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

@@ -0,0 +1,50 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { completeTimelineBinding, safeTimelineId } from "./session-timeline-contract.js";
+import { sessionTimelineRootDigest } from "./session-timeline-root.js";
+
+// This capability is deliberately supplied only by a locally configured host
+// transport. It is never a MCP argument, stored value, hook output, or card.
+export const TIMELINE_TRANSPORT_CAPABILITY_ENV = "AGENTSPINE_TIMELINE_SESSION_CAPABILITY";
+export const TIMELINE_TRANSPORT_SESSION_ENV = "AGENTSPINE_TIMELINE_TRANSPORT_SESSION_ID";
+
+const CAPABILITY_RE = /^astc_[A-Za-z0-9_-]{43}$/;
+const DIGEST_RE = /^[a-f0-9]{64}$/;
+function validDigest(value) { return typeof value === "string" && DIGEST_RE.test(value); }
+
+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 digest(value) { return createHash("sha256").update(value).digest("hex"); }
+
+function capability(environment) {
+  const value = environment?.[TIMELINE_TRANSPORT_CAPABILITY_ENV];
+  const sessionId = safeTimelineId(environment?.[TIMELINE_TRANSPORT_SESSION_ENV]);
+  return typeof value === "string" && CAPABILITY_RE.test(value) && sessionId ? { value, sessionId } : null;
+}
+
+// The environment must carry a freshly generated 32-byte capability for the
+// exact host session. A global or argument-supplied fallback is intentionally
+// absent: standard MCP stdio does not authenticate callers by itself.
+export function timelineTransportDigest({ root, binding, environment = process.env }) {
+  const current = capability(environment);
+  if (typeof root !== "string" || !root || !completeTimelineBinding(binding) || !current
+    || current.sessionId !== binding.sessionId) return null;
+  return digest(`agentspine.timeline-transport/v1\0${current.value}\0${sessionTimelineRootDigest(root)}\0${canonical(binding)}`);
+}
+
+export function validTimelineTransportDigest(value) {
+  return validDigest(value);
+}
+
+export function sameTimelineTransportDigest(left, right) {
+  if (!validTimelineTransportDigest(left) || !validTimelineTransportDigest(right)) return false;
+  return timingSafeEqual(Buffer.from(left, "hex"), Buffer.from(right, "hex"));
+}
+
+// The one-use record is valid only while the exact local enrollment that
+// produced it is still active. This check occurs before the record is removed.

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

@@ -0,0 +1,148 @@
+import { spawnSync } from "node:child_process";
+import { isAbsolute, join } from "node:path";
+import { readWindowsSidAcl } from "./session-timeline-sid-acl.js";
+
+const SID_RE = /\bS-\d+(?:-\d+)+\b/i;
+const WRITE_RIGHTS = new Set(["AD", "D", "DC", "DE", "F", "GA", "GW", "M", "W", "WA", "WD", "WDAC", "WEA", "WO"]);
+const SYSTEM_PRINCIPALS = new Set([
+  "s-1-5-18", "s-1-5-32-544", "sddl:la"
+]);
+const MANDATORY_LABEL_PREFIX = "mandatory label\\";
+const FILE_ROLES = new Set(["key", "state", "head", "private"]);
+
+function failure(message, result = null) {
+  const detail = result?.error?.message || result?.stderr || result?.stdout || "no diagnostic";
+  throw new Error(`session timeline Windows ACL ${message}: ${String(detail).trim().slice(0, 240)}`);
+}
+
+function executable(name, env) {
+  const root = env.SystemRoot;
+  if (typeof root !== "string" || !isAbsolute(root)) throw new Error("session timeline Windows system root is unavailable");
+  return join(root, "System32", name);
+}
+
+function runCommand(run, binary, args, env) {
+  const result = run(binary, args, { encoding: "utf8", env, shell: false, timeout: 1_500, windowsHide: true });
+  if (!result || result.status !== 0 || result.error || result.signal) failure(`${binary} failed`, result);
+  return `${result.stdout || ""}\n${result.stderr || ""}`;
+}
+
+function identityFrom(output) {
+  const sid = output.match(SID_RE)?.[0]?.toLowerCase();
+  const account = output.match(/^\s*"((?:[^"]|"")*)"\s*,/m)?.[1]?.replaceAll('""', '"').toLowerCase();
+  if (!sid || !account) throw new Error("session timeline Windows identity is unavailable");
+  return { sid, account };
+}
+
+function normalizedPrincipal(value) {
+  return value.trim().replace(/^\*/, "").replaceAll("/", "\\").toLowerCase();
+}
+
+function entriesFrom(output, path) {
+  const values = [];
+  let first = true;
+  for (const source of output.split(/\r?\n/)) {
+    let line = source.trim();
+    if (!line) continue;
+    if (first && line.toLowerCase().startsWith(path.toLowerCase())) line = line.slice(path.length).trim();
+    first = false;
+    const match = line.match(/^(.+?):((?:\([^)]*\))+)/);
+    if (!match) continue;
+    values.push({ principal: normalizedPrincipal(match[1]), rights: [...match[2].matchAll(/\(([^)]*)\)/g)].map((item) => item[1].toUpperCase()) });
+  }
+  return values;
+}
+
+function canWrite(entry) { return entry.rights.some((right) => WRITE_RIGHTS.has(right)); }
+function isSelf(principal, identity) { return principal === identity.sid; }
+export function isTrustedWindowsWriter(principal, identity) {
+  return isSelf(principal, identity) || SYSTEM_PRINCIPALS.has(principal);
+}
+function isMandatoryLabel(entry) {
+  return entry.principal.startsWith(MANDATORY_LABEL_PREFIX)
+    && entry.rights.every((right) => new Set(["I", "IO", "OI", "CI", "NW"]).has(right));
+}
+function isPrivatePrincipal(entry, identity) {
+  return isTrustedWindowsWriter(entry.principal, identity) || isMandatoryLabel(entry);
+}
+function isTrustedParentWriter(entry, identity) {
+  return isTrustedWindowsWriter(entry.principal, identity)
+    || (entry.principal === "s-1-3-0" && entry.rights.includes("IO"));
+}
+
+function verifyParent(entries, identity) {
+  if (!entries.length) throw new Error("session timeline Windows parent ACL has no readable entries");
+  const unsafe = entries.find((entry) => canWrite(entry) && !isTrustedParentWriter(entry, identity));
+  if (unsafe) throw new Error(`session timeline Windows parent ACL grants write access to ${unsafe.principal}`);
+}
+
+function verifyIntegrity(entries, identity) {
+  const owner = entries.find((entry) => isSelf(entry.principal, identity)
+    && entry.rights.includes("F") && !entry.rights.includes("I") && !entry.rights.includes("IO"));
+  if (!owner || entries.some((entry) => !isPrivatePrincipal(entry, identity))) {
+    throw new Error("session timeline Windows integrity ACL is not private to the current SID");
+  }
+}
+
+function verifyFile(entries, identity, role) {
+  const owner = entries.find((entry) => isSelf(entry.principal, identity)
+    && entry.rights.includes("F") && !entry.rights.includes("IO"));
+  if (!owner || entries.some((entry) => !isPrivatePrincipal(entry, identity))) {
+    throw new Error(`session timeline Windows ${role} ACL is not private to the current SID`);
+  }
+}
+
+function fingerprint(metadata) {
+  if (!metadata) return null;
+  return [metadata.dev, metadata.ino, metadata.mtimeNs, metadata.ctimeNs].map(String).join(":");
+}
+
+export function createWindowsTimelineAclVerifier({ platform = process.platform, env = process.env, run = spawnSync } = {}) {
+  const cache = new Map();
+  let identity = null;
+  return async function verifyWindowsTimelineDirectoryAcl(path, { created = false, metadata = null, role = "integrity" } = {}) {
+    if (platform !== "win32") return;
+    if (!isAbsolute(path) || !["integrity", "parent"].includes(role)) {
+      throw new Error("session timeline Windows ACL request is invalid");
+    }
+    const cached = `${role}:${path.toLowerCase()}:${fingerprint(metadata)}`;
+    if (!created && fingerprint(metadata) && cache.has(cached)) return;
+    const whoami = executable("whoami.exe", env);
+    const icacls = executable("icacls.exe", env);
+    identity ||= identityFrom(runCommand(run, whoami, ["/user", "/fo", "csv", "/nh"], env));
+    if (role === "integrity" && created) {
+      runCommand(run, icacls, [path, "/inheritance:r", "/grant:r", `*${identity.sid}:(OI)(CI)(F)`], env);
+    }
+    const entries = await readWindowsSidAcl(path, env, runCommand, run, identity);
+    if (role === "integrity") verifyIntegrity(entries, identity); else verifyParent(entries, identity);
+    if (!created && fingerprint(metadata)) cache.set(cached, true);
+  };
+}
+
+// Every boundary supplies fresh file metadata. On Windows, changing a security
+// descriptor changes ctime, so only an identical file identity/change-time can
+// reuse a parsed ACL. A changed DACL therefore misses this cache and is denied.
+export function createWindowsTimelineFileAclVerifier({ platform = process.platform, env = process.env, run = spawnSync } = {}) {
+  const cache = new Map();
+  let identity = null;
+  return async function verifyWindowsTimelineFileAcl(path, { created = false, metadata = null, role = "private" } = {}) {
+    if (platform !== "win32") return;
+    if (!isAbsolute(path) || !FILE_ROLES.has(role)) {
+      throw new Error("session timeline Windows file ACL request is invalid");
+    }
+    const cached = `${role}:${path.toLowerCase()}:${fingerprint(metadata)}`;
+    if (!created && fingerprint(metadata) && cache.has(cached)) return;
+    const whoami = executable("whoami.exe", env);
+    const icacls = executable("icacls.exe", env);
+    identity ||= identityFrom(runCommand(run, whoami, ["/user", "/fo", "csv", "/nh"], env));
+    if (created) runCommand(run, icacls, [path, "/inheritance:r", "/grant:r", `*${identity.sid}:(F)`], env);
+    verifyFile(await readWindowsSidAcl(path, env, runCommand, run, identity), identity, role);
+    if (!created && fingerprint(metadata)) cache.set(cached, true);
+  };
+}
+
+const verifyWindowsTimelineDirectoryAcl = createWindowsTimelineAclVerifier();
+const verifyWindowsTimelineFileAcl = createWindowsTimelineFileAclVerifier();
+
+export { entriesFrom as parseWindowsIcaclsEntries };
+export { verifyWindowsTimelineDirectoryAcl, verifyWindowsTimelineFileAcl };