blun-king-cli 9.1.563 → 9.1.565

package/agent-spine-plugin/src/lib/preflight.js

@@ -1,702 +1,702 @@
-import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
-import { constants as fsConstants } from "node:fs";
-import { spawn } from "node:child_process";
-import { lstat, mkdir, open, readFile, realpath, stat, unlink, writeFile } from "node:fs/promises";
-import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { isFileLockContention, replaceFileWithRetry } from "./filesystem-retry.js";
-import { ancestorsBetween, isInside, stateRoot } from "./paths.js";
-import { resolveHostSourceCatalog } from "./source-roots.js";
-
-export const PREFLIGHT_SCHEMA = "agentspine.preflight/v2";
-export const PREFLIGHT_POLICY_SCHEMA = "agentspine.preflight-policy/v1";
-export const RETRIEVAL_QUERY_SCHEMA = "agentspine.retrieval-query/v1";
-export const RETRIEVAL_RESULT_SCHEMA = "agentspine.retrieval-result/v1";
-export const MUST_REMEMBER_SCHEMA = "agentspine.must-remember/v1";
-
-const CONFIRM_POLICY = "local-owner-confirmed";
-const CONFIRM_MEMORY = "local-user-confirmed";
-const ID_RE = /^[A-Za-z0-9][A-Za-z0-9:_.@/+~-]{0,255}$/;
-const DIGEST_RE = /^[a-f0-9]{64}$/;
-const ENV_RE = /^[A-Z_][A-Z0-9_]{0,127}$/;
-const MAX_POLICY_BYTES = 1024 * 1024;
-const MAX_STATE_BYTES = 8 * 1024 * 1024;
-const MAX_PROVIDER_BYTES = 1024 * 1024;
-const STANDARD_REQUIRED_INSTRUCTIONS_BYTES = 8 * 1024;
-const MAX_CLAUDE_REQUIRED_INSTRUCTIONS_BYTES = 16 * 1024;
-const MAX_REQUIRED_MEMORY_BYTES = 6 * 1024;
-const RECEIPT_TTL_MS = 60_000;
-const FORBIDDEN_MEMORY = /-----BEGIN [A-Z ]*PRIVATE KEY-----|\b(?:sk|gh[opusu])_[A-Za-z0-9_-]{20,}\b|\b(?:password|passwort|secret|token|api[-_ ]?key|credential|permission|rights?|roles?|delegat|authoriz|berechtig|freigabe|approval|tool access|file access|network|production|payment|zahlung|policy)\b/i;
-
-function sha256(value) { return createHash("sha256").update(value).digest("hex"); }
-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 digestObject(value) { return sha256(canonical(value)); }
-function timestamp(value = new Date()) {
-  const date = value instanceof Date ? value : new Date(value);
-  if (!Number.isFinite(date.getTime())) throw new Error("preflight timestamp is invalid");
-  return date.toISOString();
-}
-function exactId(value, field, fallback = null) {
-  const selected = value === null || value === undefined || value === "" ? fallback : value;
-  if (typeof selected !== "string" || !ID_RE.test(selected) || selected.includes("*")) throw new Error(`${field} must be one exact ID`);
-  return selected;
-}
-function nullableId(value, field) { return value === null || value === undefined || value === "" ? null : exactId(value, field); }
-function storagePaths(env = process.env) {
-  const root = stateRoot(env);
-  return {
-    directory: join(root, "preflight"), policy: join(root, "policy", "preflight-policy.json"),
-    state: join(root, "preflight", "preflight-state.json"), memories: join(root, "context", "must-remember.json"),
-    key: join(root, "policy", "preflight-signing.key"), lock: join(root, "preflight", "preflight.lock")
-  };
-}
-function emptyPolicy() { return { schema: PREFLIGHT_POLICY_SCHEMA, revision: 0, profiles: [], history: [] }; }
-function emptyState() { return { schema: PREFLIGHT_SCHEMA, revision: 0, receipts: [], history: [], lastTurn: null }; }
-function emptyMemories() { return { schema: MUST_REMEMBER_SCHEMA, revision: 0, candidates: [], entries: [], history: [] }; }
-
-async function readJson(path, maximum, fallback) {
-  try {
-    const metadata = await stat(path);
-    if (!metadata.isFile() || metadata.size > maximum) throw new Error(`${basename(path)} is invalid or too large`);
-    return JSON.parse(await readFile(path, "utf8"));
-  } catch (error) {
-    if (error.code === "ENOENT") return fallback();
-    throw error;
-  }
-}
-async function writeJson(path, value, maximum = MAX_STATE_BYTES) {
-  const body = `${JSON.stringify(value, null, 2)}\n`;
-  if (Buffer.byteLength(body) > maximum) throw new Error(`${basename(path)} exceeds its state limit`);
-  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
-  try {
-    await writeFile(temporary, body, { mode: 0o600 });
-    await replaceFileWithRetry(temporary, path);
-  } finally {
-    await unlink(temporary).catch((error) => { if (error.code !== "ENOENT") throw error; });
-  }
-}
-async function withLock(paths, task) {
-  await mkdir(paths.directory, { recursive: true, mode: 0o700 });
-  let handle;
-  for (let attempt = 0; attempt < 120; attempt += 1) {
-    try { handle = await open(paths.lock, "wx", 0o600); break; } catch (error) {
-      if (!isFileLockContention(error)) throw error;
-      try {
-        const metadata = await stat(paths.lock);
-        if (Date.now() - metadata.mtimeMs > 90_000) await unlink(paths.lock);
-      } catch (lockError) { if (lockError.code !== "ENOENT") throw lockError; }
-      await new Promise((resolvePromise) => setTimeout(resolvePromise, 25));
-    }
-  }
-  if (!handle) throw new Error("preflight state is busy; turn blocked");
-  try { return await task(); } finally {
-    await handle.close();
-    await unlink(paths.lock).catch((error) => { if (error.code !== "ENOENT") throw error; });
-  }
-}
-
-function normalizeProvider(provider) {
-  if (!provider || provider.schema !== "agentspine.retrieval-provider/v1") throw new Error("retrieval provider schema is invalid");
-  const value = {
-    schema: provider.schema, id: exactId(provider.id, "providerId"), adapter: provider.adapter,
-    required: provider.required === true, failClosed: provider.failClosed === true,
-    timeoutMs: Number(provider.timeoutMs ?? 5000), command: provider.command, args: provider.args || [],
-    credentialEnv: provider.credentialEnv || []
-  };
-  if (value.adapter !== "mnemo-command/v1" || !isAbsolute(value.command || "") || !Array.isArray(value.args)
-    || value.args.some((item) => typeof item !== "string" || item.length > 500)
-    || !Number.isInteger(value.timeoutMs) || value.timeoutMs < 100 || value.timeoutMs > 10_000
-    || !Array.isArray(value.credentialEnv) || value.credentialEnv.some((item) => !ENV_RE.test(item))) {
-    throw new Error("retrieval provider configuration is unsafe");
-  }
-  if (value.required && !value.failClosed) throw new Error("required retrieval providers must fail closed");
-  return value;
-}
-function normalizeProfile(profile) {
-  return {
-    id: exactId(profile.id, "profilePolicyId"), agentId: exactId(profile.agentId, "agentId"),
-    host: exactId(profile.host, "host"), profileId: exactId(profile.profileId, "profileId"),
-    tenantId: exactId(profile.tenantId, "tenantId"), enabled: profile.enabled === true,
-    providers: (profile.providers || []).map(normalizeProvider), authority: "authenticated-local-policy"
-  };
-}
-function validatePolicy(value) {
-  if (!value || value.schema !== PREFLIGHT_POLICY_SCHEMA || !Number.isInteger(value.revision)
-    || !Array.isArray(value.profiles) || !Array.isArray(value.history)
-    || value.history.some((item) => item?.authority !== "authenticated-local-policy")) throw new Error("preflight policy is corrupt; required turns are blocked");
-  value.profiles = value.profiles.map(normalizeProfile);
-  if (new Set(value.profiles.map((item) => item.id)).size !== value.profiles.length) throw new Error("preflight policy contains duplicate profiles");
-  return value;
-}
-function validateMemories(value) {
-  if (!value || value.schema !== MUST_REMEMBER_SCHEMA || !Number.isInteger(value.revision)
-    || !Array.isArray(value.candidates) || !Array.isArray(value.entries) || !Array.isArray(value.history)
-    || value.history.some((item) => item?.authority !== "context-only")
-    || [...value.candidates, ...value.entries].some((item) => !item || !ID_RE.test(item.id || "")
-      || typeof item.claim !== "string" || !item.claim || FORBIDDEN_MEMORY.test(item.claim)
-      || item.authority !== "context-only" || !ID_RE.test(item.userId || "") || !ID_RE.test(item.tenantId || ""))
-    || value.entries.some((item) => !DIGEST_RE.test(item.checksum || "") || item.checksum !== sha256(item.claim)
-      || !["active", "superseded"].includes(item.status) || !Number.isInteger(item.version) || item.version < 1)) {
-    throw new Error("must-remember state is corrupt; required recall is blocked");
-  }
-  return value;
-}
-function validateState(value) {
-  if (!value || value.schema !== PREFLIGHT_SCHEMA || !Number.isInteger(value.revision)
-    || !Array.isArray(value.receipts) || !Array.isArray(value.history)
-    || value.receipts.some((envelope) => {
-      const receipt = envelope?.receipt;
-      if (!receipt || receipt.schema !== PREFLIGHT_SCHEMA || receipt.status !== "ready"
-        || !ID_RE.test(receipt.id || "") || !DIGEST_RE.test(receipt.bodyDigest || "") || !DIGEST_RE.test(receipt.signature || "")
-        || !DIGEST_RE.test(envelope.stateSignature || "")
-        || (envelope.consumedAt !== null && !Number.isFinite(new Date(envelope.consumedAt).getTime()))
-        || (envelope.invalidatedAt !== null && envelope.invalidatedAt !== undefined
-          && !Number.isFinite(new Date(envelope.invalidatedAt).getTime()))) return true;
-      const { id, bodyDigest, signature: _signature, ...body } = receipt;
-      return id !== `preflight:${bodyDigest.slice(0, 32)}` || digestObject(body) !== bodyDigest;
-    })) throw new Error("preflight receipt state is corrupt; turn blocked");
-  return value;
-}
-function envelopeBody(envelope) {
-  return canonical({ bodyDigest: envelope.receipt.bodyDigest, consumedAt: envelope.consumedAt,
-    invalidatedAt: envelope.invalidatedAt ?? null });
-}
-async function signingKey(paths) {
-  await mkdir(dirname(paths.key), { recursive: true, mode: 0o700 });
-  try {
-    const value = await readFile(paths.key);
-    if (value.byteLength !== 32) throw new Error("preflight signing key is corrupt; turn blocked");
-    return value;
-  } catch (error) {
-    if (error.code !== "ENOENT") throw error;
-    const value = randomBytes(32);
-    const handle = await open(paths.key, "wx", 0o600);
-    try { await handle.writeFile(value); } finally { await handle.close(); }
-    return value;
-  }
-}
-
-async function readVerifiedState(paths) {
-  const state = validateState(await readJson(paths.state, MAX_STATE_BYTES, emptyState));
-  if (!state.receipts.length) return state;
-  const key = await signingKey(paths);
-  for (const envelope of state.receipts) {
-    const expected = createHmac("sha256", key).update(envelope.receipt.bodyDigest).digest();
-    const actual = Buffer.from(envelope.receipt.signature, "hex");
-    if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
-      throw new Error("preflight receipt authentication failed; turn blocked");
-    }
-    const expectedState = createHmac("sha256", key).update(envelopeBody(envelope)).digest();
-    const actualState = Buffer.from(envelope.stateSignature, "hex");
-    if (actualState.length !== expectedState.length || !timingSafeEqual(actualState, expectedState)) {
-      throw new Error("preflight receipt lifecycle authentication failed; turn blocked");
-    }
-  }
-  return state;
-}
-
-export async function configurePreflightPolicy({ profile, confirmation, env = process.env }) {
-  if (confirmation !== CONFIRM_POLICY) throw new Error("preflight policy changes require explicit local owner confirmation");
-  const paths = storagePaths(env);
-  return withLock(paths, async () => {
-    const policy = validatePolicy(await readJson(paths.policy, MAX_POLICY_BYTES, emptyPolicy));
-    const normalized = normalizeProfile(profile);
-    policy.profiles = [...policy.profiles.filter((item) => item.id !== normalized.id), normalized];
-    policy.revision += 1;
-    policy.history.push({ event: "profile-configured", profileId: normalized.id, at: timestamp(), authority: "authenticated-local-policy" });
-    await writeJson(paths.policy, policy, MAX_POLICY_BYTES);
-    return { profile: normalized, revision: policy.revision, policyPath: paths.policy };
-  });
-}
-
-function memoryScope(input) {
-  return {
-    userId: exactId(input.userId, "userId"), tenantId: exactId(input.tenantId, "tenantId"),
-    projectId: nullableId(input.projectId, "projectId"), groupId: nullableId(input.groupId, "groupId"),
-    taskId: nullableId(input.taskId, "taskId")
-  };
-}
-function safeClaim(value) {
-  if (typeof value !== "string" || !value.trim() || Buffer.byteLength(value) > 4096 || FORBIDDEN_MEMORY.test(value)) {
-    throw new Error("must-remember claim is empty, too large, secret-shaped, or authority-shaped");
-  }
-  return value.trim().replace(/\s+/g, " ");
-}
-export async function proposeMustRemember({ claim, kind = "critical", sourceDigest, ...scope }, env = process.env) {
-  const paths = storagePaths(env);
-  const exactScope = memoryScope(scope);
-  const normalized = safeClaim(claim);
-  const id = `remember-candidate:${sha256(canonical({ claim: normalized, ...exactScope })).slice(0, 32)}`;
-  return withLock(paths, async () => {
-    const state = validateMemories(await readJson(paths.memories, MAX_STATE_BYTES, emptyMemories));
-    const existing = state.candidates.find((item) => item.id === id);
-    if (existing) return { candidate: existing, duplicate: true };
-    const candidate = { id, kind, claim: normalized, ...exactScope, sourceDigest: DIGEST_RE.test(sourceDigest || "") ? sourceDigest : null,
-      status: "pending-confirmation", observedAt: timestamp(), authority: "context-only" };
-    state.candidates.push(candidate); state.revision += 1;
-    state.history.push({ event: "proposed", id, at: candidate.observedAt, authority: "context-only" });
-    await writeJson(paths.memories, state);
-    return { candidate, duplicate: false };
-  });
-}
-export async function captureMustRememberPrompt({ prompt, receipt, env = process.env }) {
-  if (typeof prompt !== "string" || Buffer.byteLength(prompt) > 64 * 1024 || !receipt || receipt.schema !== PREFLIGHT_SCHEMA) return null;
-  const match = prompt.trim().match(/^(?:merk dir(?: bitte)?(?: dauerhaft)?(?: das)?|das ist wichtig|vergiss das niemals|remember (?:this|that)(?: permanently)?|never forget this)\s*[:,-]?\s*(.+)$/i);
-  if (!match?.[1]?.trim()) return null;
-  try {
-    return await proposeMustRemember({ claim: match[1], kind: "critical", userId: receipt.userId,
-      tenantId: receipt.tenantId, projectId: receipt.projectId, groupId: receipt.groupId,
-      taskId: receipt.taskId, sourceDigest: receipt.promptDigest }, env);
-  } catch (error) {
-    return { rejected: true, reason: error.message };
-  }
-}
-export async function confirmMustRemember({ candidateId, confirmation, supersedes = null }, env = process.env) {
-  if (confirmation !== CONFIRM_MEMORY) throw new Error("must-remember activation requires explicit local user confirmation");
-  const paths = storagePaths(env);
-  return withLock(paths, async () => {
-    const state = validateMemories(await readJson(paths.memories, MAX_STATE_BYTES, emptyMemories));
-    const candidate = state.candidates.find((item) => item.id === candidateId && item.status === "pending-confirmation");
-    if (!candidate) throw new Error("pending must-remember candidate not found");
-    const previous = supersedes ? state.entries.find((item) => item.id === supersedes && item.status === "active") : null;
-    if (supersedes && !previous) throw new Error("active must-remember entry to supersede was not found");
-    if (previous && ["userId", "tenantId", "projectId", "groupId", "taskId"].some((key) => previous[key] !== candidate[key])) {
-      throw new Error("must-remember supersession cannot cross scope");
-    }
-    const version = previous ? previous.version + 1 : 1;
-    const id = `remember:${sha256(`${candidate.id}\0${version}\0${timestamp()}`).slice(0, 32)}`;
-    const entry = { ...candidate, id, candidateId: candidate.id, version, supersedes: previous?.id || null,
-      checksum: sha256(candidate.claim), status: "active", confirmedAt: timestamp(), retention: "until-local-user-deletes",
-      confirmation: "explicit-local-user", authority: "context-only" };
-    delete entry.observedAt;
-    candidate.status = "confirmed";
-    if (previous) previous.status = "superseded";
-    state.entries.push(entry); state.revision += 1;
-    state.history.push({ event: "confirmed", id, supersedes: entry.supersedes, at: entry.confirmedAt, authority: "context-only" });
-    await writeJson(paths.memories, state);
-    return { entry, revision: state.revision };
-  });
-}
-export async function rollbackMustRemember({ id, confirmation }, env = process.env) {
-  if (confirmation !== CONFIRM_MEMORY) throw new Error("must-remember rollback requires explicit local user confirmation");
-  const paths = storagePaths(env);
-  return withLock(paths, async () => {
-    const state = validateMemories(await readJson(paths.memories, MAX_STATE_BYTES, emptyMemories));
-    const target = state.entries.find((item) => item.id === id);
-    if (!target) throw new Error("must-remember entry not found");
-    for (const item of state.entries) if (item.userId === target.userId && item.tenantId === target.tenantId
-      && item.projectId === target.projectId && item.groupId === target.groupId && item.taskId === target.taskId
-      && item.kind === target.kind && item.status === "active") item.status = "superseded";
-    target.status = "active"; state.revision += 1;
-    state.history.push({ event: "rolled-back", id, at: timestamp(), authority: "context-only" });
-    await writeJson(paths.memories, state);
-    return { entry: target, revision: state.revision };
-  });
-}
-export async function purgeMustRemember({ id, confirmation }, env = process.env) {
-  if (confirmation !== "local-user-purge-confirmed") throw new Error("permanent must-remember deletion requires explicit local user purge confirmation");
-  const paths = storagePaths(env);
-  return withLock(paths, async () => {
-    const state = validateMemories(await readJson(paths.memories, MAX_STATE_BYTES, emptyMemories));
-    const removed = state.entries.find((item) => item.id === id);
-    if (!removed) throw new Error("must-remember entry not found");
-    state.entries = state.entries.filter((item) => item.id !== id);
-    state.candidates = state.candidates.filter((item) => item.id !== removed.candidateId);
-    state.revision += 1; state.history.push({ event: "purged", idDigest: sha256(id), at: timestamp(), authority: "context-only" });
-    await writeJson(paths.memories, state);
-    return { purged: true, idDigest: sha256(id), revision: state.revision };
-  });
-}
-
-async function assertNoSymlinkParents(path, allowedRoot) {
-  const root = await realpath(allowedRoot);
-  const target = resolve(path);
-  if (!isInside(root, target)) throw new Error("required instruction escaped its allowed scope");
-  let cursor = target;
-  const chain = [];
-  while (cursor !== root) { chain.push(cursor); cursor = dirname(cursor); if (!isInside(root, cursor)) throw new Error("required instruction escaped its allowed scope"); }
-  chain.reverse();
-  for (const item of chain) {
-    const metadata = await lstat(item);
-    if (metadata.isSymbolicLink()) throw new Error("required instruction path contains a symlink");
-  }
-  return { root, target };
-}
-async function safeReadRequired(path, allowedRoot, maximum = STANDARD_REQUIRED_INSTRUCTIONS_BYTES, fileHooks = null) {
-  const checked = await assertNoSymlinkParents(path, allowedRoot);
-  const flags = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0);
-  const handle = await open(checked.target, flags);
-  try {
-    const before = await handle.stat();
-    if (!before.isFile()) throw new Error(`required instruction ${basename(path)} is not a regular file`);
-    if (before.size > maximum) {
-      throw new Error(`required instruction ${basename(path)} is ${before.size} bytes; mandatory limit is ${maximum} bytes`);
-    }
-    const buffer = Buffer.alloc(Number(before.size));
-    let offset = 0;
-    while (offset < buffer.length) {
-      const result = await handle.read(buffer, offset, buffer.length - offset, offset);
-      if (!result.bytesRead) break;
-      offset += result.bytesRead;
-    }
-    if (fileHooks?.afterRead) await fileHooks.afterRead(checked.target);
-    const after = await handle.stat();
-    if (offset !== buffer.length || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size
-      || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error(`required instruction ${basename(path)} changed during preflight`);
-    const finalPath = await assertNoSymlinkParents(checked.target, checked.root);
-    const current = await lstat(finalPath.target);
-    if (!current.isFile() || current.isSymbolicLink() || current.dev !== before.dev || current.ino !== before.ino
-      || current.size !== before.size || current.mtimeMs !== before.mtimeMs || current.ctimeMs !== before.ctimeMs) {
-      throw new Error(`required instruction ${basename(path)} was replaced during preflight`);
-    }
-    return { content: buffer.toString("utf8"), bytes: buffer.length, sha256: sha256(buffer),
-      identity: sha256(`${before.dev}\0${before.ino}\0${before.size}\0${before.mtimeMs}\0${before.ctimeMs}`) };
-  } finally { await handle.close(); }
-}
-
-function scopeFromInput({ input, scope, resolvedSources, env = process.env }) {
-  const supplied = input.agent_spine_scope && typeof input.agent_spine_scope === "object" ? input.agent_spine_scope : input;
-  return {
-    agentId: exactId(supplied.agent_id ?? supplied.agentId ?? scope.entityId, "agentId", "host-agent:default"),
-    personaId: nullableId(supplied.persona_id ?? supplied.personaId, "personaId"),
-    userId: exactId(supplied.user_id ?? supplied.userId ?? env.AGENTSPINE_USER_ID, "userId", "local-user"),
-    tenantId: exactId(supplied.tenant_id ?? supplied.tenantId ?? env.AGENTSPINE_TENANT_ID, "tenantId", "local-tenant"),
-    profileId: exactId(supplied.profile_id ?? supplied.profileId ?? env.AGENTSPINE_PROFILE_ID, "profileId", "default"),
-    sessionId: exactId(input.session_id ?? input.sessionId, "sessionId"), host: scope.host,
-    projectId: exactId(scope.projectId, "projectId", `project:${sha256(resolvedSources.projectRoot).slice(0, 20)}`),
-    groupId: nullableId(scope.groupId, "groupId"), taskId: nullableId(scope.currentTaskId, "taskId"),
-    cwd: resolvedSources.cwd, projectRoot: resolvedSources.projectRoot
-  };
-}
-function instructionDocuments(catalog, host) {
-  const pattern = host === "claude" ? /(?:^|\/)CLAUDE(?:\.local)?\.md$/ : /(?:^|\/)AGENTS(?:\.override)?\.md$/;
-  return catalog.documents.filter((item) => item.layer === "constitution" && pattern.test(item.relativePath))
-    .sort((left, right) => left.precedence - right.precedence || left.relativePath.localeCompare(right.relativePath));
-}
-function instructionBudget(host, usedBytes = 0) {
-  const hardLimitBytes = host === "claude"
-    ? MAX_CLAUDE_REQUIRED_INSTRUCTIONS_BYTES
-    : STANDARD_REQUIRED_INSTRUCTIONS_BYTES;
-  const overflowBytes = Math.max(0, usedBytes - STANDARD_REQUIRED_INSTRUCTIONS_BYTES);
-  return {
-    mode: overflowBytes ? "claude-required-overflow" : "standard",
-    standardBytes: STANDARD_REQUIRED_INSTRUCTIONS_BYTES,
-    hardLimitBytes,
-    usedBytes,
-    overflowBytes
-  };
-}
-async function rejectKnownInstructionSymlinks(resolvedSources, host) {
-  const candidates = host === "claude"
-    ? [join(resolvedSources.hostHome, "CLAUDE.md"), ...ancestorsBetween(resolvedSources.projectRoot, resolvedSources.cwd)
-      .flatMap((directory) => [join(directory, "CLAUDE.md"), join(directory, "CLAUDE.local.md"), join(directory, ".claude", "CLAUDE.md")])]
-    : [join(resolvedSources.hostHome, "AGENTS.override.md"), join(resolvedSources.hostHome, "AGENTS.md"),
-      ...ancestorsBetween(resolvedSources.projectRoot, resolvedSources.cwd)
-        .flatMap((directory) => [join(directory, "AGENTS.override.md"), join(directory, "AGENTS.md")])];
-  for (const path of candidates) {
-    try {
-      if ((await lstat(path)).isSymbolicLink()) throw new Error(`host instruction path is a symlink: ${basename(path)}`);
-    } catch (error) { if (error.code !== "ENOENT") throw error; }
-  }
-}
-function memoryMatches(entry, scope) {
-  return entry.status === "active" && entry.userId === scope.userId && entry.tenantId === scope.tenantId
-    && (entry.projectId === null || entry.projectId === scope.projectId)
-    && (entry.groupId === null || entry.groupId === scope.groupId)
-    && (entry.taskId === null || entry.taskId === scope.taskId);
-}
-function memoryProofs(entries) {
-  return entries.map((entry) => ({ id: entry.id, version: entry.version, checksum: entry.checksum }))
-    .sort((left, right) => left.id.localeCompare(right.id));
-}
-function retrievalQuery(scope, promptDigest, providerId) {
-  const body = { schema: RETRIEVAL_QUERY_SCHEMA, providerId, agentId: scope.agentId, personaId: scope.personaId,
-    userId: scope.userId, tenantId: scope.tenantId, host: scope.host, profileId: scope.profileId,
-    sessionId: scope.sessionId, projectId: scope.projectId, groupId: scope.groupId, taskId: scope.taskId,
-    cwdDigest: sha256(scope.cwd), promptDigest, requested: "current-effective-truth" };
-  return { ...body, queryDigest: digestObject(body) };
-}
-function normalizeResult(value, providerId, query) {
-  if (!value || value.schema !== RETRIEVAL_RESULT_SCHEMA || value.providerId !== providerId
-    || value.queryDigest !== query.queryDigest || value.status !== "ok" || !Array.isArray(value.items)
-    || value.items.length > 128) throw new Error(`retrieval provider ${providerId} returned an invalid or mismatched result`);
-  const items = value.items.map((item) => {
-    const itemScope = item?.scope;
-    const scopeKeys = ["agentId", "personaId", "userId", "tenantId", "profileId", "sessionId", "projectId", "groupId", "taskId"];
-    const exactScope = itemScope && typeof itemScope === "object" && !Array.isArray(itemScope)
-      && Object.keys(itemScope).every((key) => scopeKeys.includes(key))
-      && ["agentId", "userId", "tenantId"].every((key) => itemScope[key] === query[key])
-      && scopeKeys.every((key) => itemScope[key] === undefined || itemScope[key] === null || itemScope[key] === query[key]);
-    if (!item || !ID_RE.test(item.id || "") || !ID_RE.test(String(item.revision || ""))
-      || typeof item.claim !== "string" || !item.claim.trim() || Buffer.byteLength(item.claim) > 4096
-      || FORBIDDEN_MEMORY.test(item.claim) || !["current", "effective"].includes(item.validity)
-      || !Number.isFinite(Number(item.confidence)) || Number(item.confidence) < 0 || Number(item.confidence) > 1
-      || typeof item.source !== "string" || !ID_RE.test(item.source) || typeof item.whyLoaded !== "string"
-      || !item.whyLoaded.trim() || Buffer.byteLength(item.whyLoaded) > 512 || FORBIDDEN_MEMORY.test(item.whyLoaded)
-      || !exactScope) throw new Error(`retrieval provider ${providerId} returned an unsafe item`);
-    return { id: item.id, revision: String(item.revision), claim: item.claim.trim(), source: item.source,
-      scope: itemScope, validity: item.validity, confidence: Number(item.confidence), whyLoaded: item.whyLoaded.trim(), authority: "context-only" };
-  });
-  return { items, rejected: Number.isInteger(value.rejected) && value.rejected >= 0 ? value.rejected : 0 };
-}
-function providerInputError(provider, error) {
-  const wrapped = new Error(`retrieval adapter ${provider.id} input failed (${error.code || "stream-error"})`);
-  wrapped.code = error.code;
-  return wrapped;
-}
-function commandProviderAttempt(provider, query, env, executable) {
-  return new Promise((resolvePromise, rejectPromise) => {
-    const childEnv = { PATH: env.PATH || "" };
-    for (const name of provider.credentialEnv) {
-      if (typeof env[name] !== "string" || !env[name]) return rejectPromise(new Error(`retrieval adapter credential is missing: ${name}`));
-      childEnv[name] = env[name];
-    }
-    const child = spawn(executable, provider.args, { stdio: ["pipe", "pipe", "pipe"], env: childEnv, shell: false });
-    let stdout = ""; let stderrBytes = 0; let bytes = 0; let settled = false;
-    const finish = (error, value) => { if (settled) return; settled = true; clearTimeout(timer); error ? rejectPromise(error) : resolvePromise(value); };
-    const timer = setTimeout(() => { child.kill("SIGKILL"); finish(new Error(`retrieval adapter ${provider.id} timed out`)); }, provider.timeoutMs);
-    child.stdout.on("data", (chunk) => { bytes += chunk.length; if (bytes > MAX_PROVIDER_BYTES) { child.kill("SIGKILL"); finish(new Error("retrieval response exceeds 1 MiB")); } else stdout += chunk; });
-    child.stderr.on("data", (chunk) => { stderrBytes = Math.min(2048, stderrBytes + chunk.length); });
-    child.once("error", (error) => finish(error));
-    child.stdin.once("error", (error) => {
-      if (settled) return;
-      child.kill("SIGKILL");
-      finish(providerInputError(provider, error));
-    });
-    child.once("close", (code) => {
-      if (settled) return;
-      if (code !== 0) return finish(new Error(`retrieval adapter ${provider.id} failed (${code}; stderr-bytes<=${stderrBytes})`));
-      try { finish(null, JSON.parse(stdout)); } catch { finish(new Error(`retrieval adapter ${provider.id} returned invalid JSON`)); }
-    });
-    try { child.stdin.end(JSON.stringify(query)); }
-    catch (error) { child.kill("SIGKILL"); finish(providerInputError(provider, error)); }
-  });
-}
-async function commandProvider(provider, query, env, runner = null) {
-  if (runner) return runner(provider, query);
-  const executable = await realpath(provider.command);
-  const metadata = await lstat(executable);
-  if (!metadata.isFile() || metadata.isSymbolicLink()) throw new Error(`retrieval adapter ${provider.id} is not a regular executable`);
-  try { return await commandProviderAttempt(provider, query, env, executable); }
-  catch (error) {
-    if (error.code !== "EPIPE") throw error;
-    return commandProviderAttempt(provider, query, env, executable);
-  }
-}
-
-export async function runPreflight({ input, scope, resolvedSources, prompt, now = new Date(), env = process.env,
-  providerRunner = null, fileHooks = null }) {
-  if (typeof prompt !== "string" || !prompt.length || Buffer.byteLength(prompt) > 64 * 1024) throw new Error("preflight requires one bounded prompt");
-  const exactScope = scopeFromInput({ input, scope, resolvedSources, env });
-  const promptDigest = sha256(prompt);
-  const deliveryId = exactId(input.event_id ?? input.hook_event_id, "hookEventId",
-    `prompt:${sha256(`${exactScope.sessionId}\0${promptDigest}`).slice(0, 32)}`);
-  const paths = storagePaths(env);
-  const policy = validatePolicy(await readJson(paths.policy, MAX_POLICY_BYTES, emptyPolicy));
-  const profile = policy.profiles.find((item) => item.enabled && item.agentId === exactScope.agentId && item.host === exactScope.host
-    && item.profileId === exactScope.profileId && item.tenantId === exactScope.tenantId) || null;
-  const instructionHost = resolvedSources.host;
-  await rejectKnownInstructionSymlinks(resolvedSources, instructionHost);
-  const documents = instructionDocuments(resolvedSources.catalog, instructionHost);
-  const requiredInstructions = [];
-  let instructionBytes = 0;
-  const maximumInstructionBytes = instructionBudget(instructionHost).hardLimitBytes;
-  for (const document of documents) {
-    const allowedRoot = document.sourceScope === "user" ? resolvedSources.hostHome : resolvedSources.projectRoot;
-    const snapshot = await safeReadRequired(document.path, allowedRoot, maximumInstructionBytes, fileHooks);
-    if (snapshot.sha256 !== document.sha256 || snapshot.bytes !== document.bytes) throw new Error(`required instruction changed after source resolution: ${document.relativePath}`);
-    instructionBytes += snapshot.bytes;
-    if (instructionBytes > maximumInstructionBytes) {
-      throw new Error(`required host instructions total ${instructionBytes} bytes; mandatory limit is ${maximumInstructionBytes} bytes`);
-    }
-    requiredInstructions.push({ path: document.path, displayPath: document.relativePath, scope: document.sourceScope,
-      bytes: snapshot.bytes, sha256: snapshot.sha256, identity: snapshot.identity, content: snapshot.content });
-  }
-  const appliedInstructionBudget = instructionBudget(instructionHost, instructionBytes);
-  const memoryState = validateMemories(await readJson(paths.memories, MAX_STATE_BYTES, emptyMemories));
-  const mustRemember = memoryState.entries.filter((item) => memoryMatches(item, exactScope));
-  if (Buffer.byteLength(JSON.stringify(mustRemember.map((item) => item.claim))) > MAX_REQUIRED_MEMORY_BYTES) {
-    throw new Error("confirmed must-remember entries exceed the mandatory preflight budget");
-  }
-  const providerResults = [];
-  for (const provider of profile?.providers || []) {
-    const query = retrievalQuery(exactScope, promptDigest, provider.id);
-    try {
-      const response = normalizeResult(await commandProvider(provider, query, env, providerRunner), provider.id, query);
-      providerResults.push({ providerId: provider.id, queryDigest: query.queryDigest, status: response.items.length ? "loaded" : "empty",
-        items: response.items, rejected: response.rejected });
-    } catch (error) {
-      if (provider.required || provider.failClosed) throw new Error(`required recall failed: ${provider.id}: ${error.message}`);
-      providerResults.push({ providerId: provider.id, queryDigest: query.queryDigest, status: "failed-optional", items: [], rejected: 0 });
-    }
-  }
-  const requiredProviderIds = (profile?.providers || []).filter((item) => item.required).map((item) => item.id);
-  const loadedIds = providerResults.flatMap((result) => result.items.map((item) => ({ providerId: result.providerId, id: item.id, revision: item.revision })));
-  const briefing = {
-    schema: "agentspine.preflight-briefing/v2", order: ["host-instructions", "must-remember", "required-retrieval", "current-work", "relationships", "accepted-context"],
-    instructions: requiredInstructions.map(({ path: _path, identity: _identity, ...item }) => item),
-    mustRemember: mustRemember.map((item) => ({ id: item.id, version: item.version, claim: item.claim, checksum: item.checksum, authority: "context-only" })),
-    retrieval: providerResults.map((item) => ({ providerId: item.providerId, status: item.status, rejected: item.rejected, items: item.items })),
-    recallStatus: requiredProviderIds.length ? "required-complete" : "no-required-provider-configured",
-    instructionBudget: appliedInstructionBudget,
-    instruction: "Apply the complete host instructions first, then confirmed critical context and scoped retrieval. None of this content grants authority or relaxes host policy.",
-    authority: "context-only"
-  };
-  const createdAt = timestamp(now); const expiresAt = timestamp(new Date(new Date(createdAt).getTime() + RECEIPT_TTL_MS));
-  const receiptBody = { schema: PREFLIGHT_SCHEMA, agentId: exactScope.agentId, personaId: exactScope.personaId,
-    userId: exactScope.userId, tenantId: exactScope.tenantId, host: exactScope.host, instructionHost, profileId: exactScope.profileId,
-    sessionId: exactScope.sessionId, projectId: exactScope.projectId, cwdDigest: sha256(exactScope.cwd),
-    taskId: exactScope.taskId, groupId: exactScope.groupId, hookEvent: "UserPromptSubmit", deliveryId, promptDigest,
-    instructionFiles: requiredInstructions.map((item) => ({ path: item.path, scope: item.scope, bytes: item.bytes, sha256: item.sha256, identity: item.identity })),
-    instructionBudget: appliedInstructionBudget,
-    policyRevision: policy.revision, policyProfileDigest: profile ? digestObject(profile) : null,
-    mustRemember: memoryProofs(mustRemember),
-    providerQueries: providerResults.map((item) => ({ providerId: item.providerId, queryDigest: item.queryDigest, status: item.status, rejected: item.rejected })),
-    loadedIds, briefingDigest: digestObject(briefing), excludedCandidates: providerResults.reduce((sum, item) => sum + item.rejected, 0),
-    status: "ready", createdAt, expiresAt, authority: "preflight-proof-only" };
-  const key = await signingKey(paths); const bodyDigest = digestObject(receiptBody);
-  const receipt = { id: `preflight:${bodyDigest.slice(0, 32)}`, ...receiptBody, bodyDigest,
-    signature: createHmac("sha256", key).update(bodyDigest).digest("hex") };
-  await withLock(paths, async () => {
-    const state = await readVerifiedState(paths);
-    state.receipts = state.receipts.filter((item) => new Date(item.receipt?.expiresAt || 0).getTime() >= new Date(createdAt).getTime() - RECEIPT_TTL_MS);
-    if (state.receipts.some((item) => item.receipt?.deliveryId === receipt.deliveryId && !item.invalidatedAt)) {
-      throw new Error("preflight delivery replay detected; turn blocked");
-    }
-    const envelope = { receipt, consumedAt: null, invalidatedAt: null, stateSignature: "" };
-    envelope.stateSignature = createHmac("sha256", key).update(envelopeBody(envelope)).digest("hex");
-    state.receipts.push(envelope); state.revision += 1;
-    state.lastTurn = { status: "ready", receiptId: receipt.id, at: createdAt, host: exactScope.host,
-      instructionHost, instructionFiles: receipt.instructionFiles.length, recall: receipt.providerQueries.map((item) => ({
-        providerId: item.providerId, status: item.status, rejected: item.rejected
-      })), cwdDigest: receipt.cwdDigest, authority: "diagnostic-only" };
-    state.history.push({ event: "ready", receiptId: receipt.id, at: createdAt, authority: "preflight-proof-only" });
-    await writeJson(paths.state, state);
-  });
-  return { receipt, briefing, policy: { configured: Boolean(profile), requiredProviderIds } };
-}
-
-export async function verifyPreflightReceipt({ receipt, input, scope, resolvedSources, prompt, now = new Date(), env = process.env, consume = false }) {
-  const exactScope = scopeFromInput({ input, scope, resolvedSources, env });
-  const current = new Date(now).getTime();
-  if (!receipt || receipt.schema !== PREFLIGHT_SCHEMA || receipt.status !== "ready" || !DIGEST_RE.test(receipt.bodyDigest || "")
-    || !DIGEST_RE.test(receipt.signature || "") || new Date(receipt.expiresAt).getTime() < current
-    || receipt.promptDigest !== sha256(prompt) || receipt.agentId !== exactScope.agentId || receipt.personaId !== exactScope.personaId
-    || receipt.userId !== exactScope.userId
-    || receipt.tenantId !== exactScope.tenantId || receipt.host !== exactScope.host || receipt.profileId !== exactScope.profileId
-    || receipt.sessionId !== exactScope.sessionId || receipt.projectId !== exactScope.projectId || receipt.cwdDigest !== sha256(exactScope.cwd)
-    || receipt.taskId !== exactScope.taskId || receipt.groupId !== exactScope.groupId) return false;
-  const deliveryId = exactId(input.event_id ?? input.hook_event_id, "hookEventId",
-    `prompt:${sha256(`${exactScope.sessionId}\0${sha256(prompt)}`).slice(0, 32)}`);
-  if (receipt.deliveryId !== deliveryId) return false;
-  const { id: _id, bodyDigest, signature, ...body } = receipt;
-  if (digestObject(body) !== bodyDigest) return false;
-  const key = await signingKey(storagePaths(env));
-  const expected = createHmac("sha256", key).update(bodyDigest).digest();
-  const actual = Buffer.from(signature, "hex");
-  if (!(actual.length === expected.length && timingSafeEqual(actual, expected))) return false;
-  try {
-    const paths = storagePaths(env);
-    const [policy, memories, freshSources, receiptState] = await Promise.all([
-      readJson(paths.policy, MAX_POLICY_BYTES, emptyPolicy).then(validatePolicy),
-      readJson(paths.memories, MAX_STATE_BYTES, emptyMemories).then(validateMemories),
-      resolveHostSourceCatalog({ host: receipt.instructionHost, cwd: exactScope.cwd, input, env }),
-      readVerifiedState(paths)
-    ]);
-    const storedEnvelope = receiptState.receipts.find((item) => item.receipt?.id === receipt.id
-      && item.receipt?.bodyDigest === receipt.bodyDigest);
-    if (!storedEnvelope || storedEnvelope.consumedAt !== null || storedEnvelope.invalidatedAt) return false;
-    const profile = policy.profiles.find((item) => item.enabled && item.agentId === exactScope.agentId && item.host === exactScope.host
-      && item.profileId === exactScope.profileId && item.tenantId === exactScope.tenantId) || null;
-    if (receipt.policyRevision !== policy.revision || receipt.policyProfileDigest !== (profile ? digestObject(profile) : null)) return false;
-    if (canonical(receipt.mustRemember) !== canonical(memoryProofs(memories.entries.filter((item) => memoryMatches(item, exactScope))))) return false;
-    if (receipt.instructionHost !== freshSources.host) return false;
-    await rejectKnownInstructionSymlinks(freshSources, freshSources.host);
-    const currentDocuments = instructionDocuments(freshSources.catalog, freshSources.host);
-    if (currentDocuments.length !== receipt.instructionFiles.length
-      || currentDocuments.some((document, index) => document.path !== receipt.instructionFiles[index]?.path)) return false;
-    let instructionBytes = 0;
-    const maximumInstructionBytes = instructionBudget(receipt.instructionHost).hardLimitBytes;
-    for (const instruction of receipt.instructionFiles) {
-      const allowedRoot = instruction.scope === "user" ? freshSources.hostHome : freshSources.projectRoot;
-      const currentSnapshot = await safeReadRequired(instruction.path, allowedRoot, maximumInstructionBytes);
-      if (currentSnapshot.sha256 !== instruction.sha256 || currentSnapshot.bytes !== instruction.bytes
-        || currentSnapshot.identity !== instruction.identity) return false;
-      instructionBytes += currentSnapshot.bytes;
-    }
-    if (instructionBytes > maximumInstructionBytes
-      || canonical(receipt.instructionBudget) !== canonical(instructionBudget(receipt.instructionHost, instructionBytes))) return false;
-  } catch { return false; }
-  if (consume) {
-    const paths = storagePaths(env);
-    const consumed = await withLock(paths, async () => {
-      const state = await readVerifiedState(paths);
-      const stored = state.receipts.find((item) => item.receipt?.id === receipt.id && item.receipt?.bodyDigest === receipt.bodyDigest);
-      if (!stored || stored.consumedAt !== null || stored.invalidatedAt) return false;
-      stored.consumedAt = timestamp(now); state.revision += 1;
-      stored.stateSignature = createHmac("sha256", key).update(envelopeBody(stored)).digest("hex");
-      state.lastTurn = { ...(state.lastTurn || {}), status: "consumed", receiptId: receipt.id,
-        at: stored.consumedAt, authority: "diagnostic-only" };
-      state.history.push({ event: "consumed", receiptId: receipt.id, at: stored.consumedAt, authority: "preflight-proof-only" });
-      await writeJson(paths.state, state);
-      return true;
-    });
-    if (!consumed) return false;
-  }
-  return true;
-}
-
-function failureCode(error) {
-  const message = String(error?.message || error || "");
-  if (/source resolution|required instruction|host instruction/i.test(message)) return "instructions-failed";
-  if (/required recall|retrieval provider|adapter/i.test(message)) return "provider-failed";
-  if (/budget|injection limit|too large|cannot fit/i.test(message)) return "budget-failed";
-  if (/receipt|replay|delivery/i.test(message)) return "receipt-failed";
-  return "preflight-failed";
-}
-
-export async function recordPreflightFailure({ receiptId = null, input = {}, host = null, error,
-  now = new Date(), env = process.env }) {
-  const paths = storagePaths(env);
-  return withLock(paths, async () => {
-    const state = await readVerifiedState(paths);
-    const at = timestamp(now);
-    if (receiptId) {
-      const stored = state.receipts.find((item) => item.receipt?.id === receiptId
-        && item.consumedAt === null && !item.invalidatedAt);
-      if (stored) {
-        stored.invalidatedAt = at;
-        const key = await signingKey(paths);
-        stored.stateSignature = createHmac("sha256", key).update(envelopeBody(stored)).digest("hex");
-      }
-    }
-    const code = failureCode(error);
-    state.lastTurn = { status: "blocked", code, receiptId, at, host: host || null,
-      deliveryDigest: sha256(String(input.event_id ?? input.hook_event_id ?? "missing")), authority: "diagnostic-only" };
-    state.revision += 1;
-    state.history.push({ event: "blocked", code, receiptId, at, authority: "preflight-proof-only" });
-    await writeJson(paths.state, state);
-    return state.lastTurn;
-  });
-}
-
-export async function preflightStatus(env = process.env) {
-  const paths = storagePaths(env);
-  const [policy, memories, state] = await Promise.all([
-    readJson(paths.policy, MAX_POLICY_BYTES, emptyPolicy).then(validatePolicy),
-    readJson(paths.memories, MAX_STATE_BYTES, emptyMemories).then(validateMemories),
-    readVerifiedState(paths)
-  ]);
-  return { schema: PREFLIGHT_SCHEMA, policies: policy.profiles.length, requiredProviders: policy.profiles.flatMap((item) => item.providers).filter((item) => item.required).length,
-    pendingMemories: memories.candidates.filter((item) => item.status === "pending-confirmation").length,
-    activeMustRemember: memories.entries.filter((item) => item.status === "active").length,
-    readyReceipts: state.receipts.filter((item) => item.consumedAt === null && !item.invalidatedAt && item.receipt?.status === "ready"
-      && new Date(item.receipt.expiresAt).getTime() >= Date.now()).length,
-    status: policy.profiles.some((item) => item.providers.some((provider) => provider.required)) ? "wrapper-hard-required" : "instructions-only-no-required-provider",
-    lastTurn: state.lastTurn,
-    authority: "diagnostic-only" };
-}
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { spawn } from "node:child_process";
+import { lstat, mkdir, open, readFile, realpath, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { isFileLockContention, replaceFileWithRetry } from "./filesystem-retry.js";
+import { ancestorsBetween, isInside, stateRoot } from "./paths.js";
+import { resolveHostSourceCatalog } from "./source-roots.js";
+
+export const PREFLIGHT_SCHEMA = "agentspine.preflight/v2";
+export const PREFLIGHT_POLICY_SCHEMA = "agentspine.preflight-policy/v1";
+export const RETRIEVAL_QUERY_SCHEMA = "agentspine.retrieval-query/v1";
+export const RETRIEVAL_RESULT_SCHEMA = "agentspine.retrieval-result/v1";
+export const MUST_REMEMBER_SCHEMA = "agentspine.must-remember/v1";
+
+const CONFIRM_POLICY = "local-owner-confirmed";
+const CONFIRM_MEMORY = "local-user-confirmed";
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9:_.@/+~-]{0,255}$/;
+const DIGEST_RE = /^[a-f0-9]{64}$/;
+const ENV_RE = /^[A-Z_][A-Z0-9_]{0,127}$/;
+const MAX_POLICY_BYTES = 1024 * 1024;
+const MAX_STATE_BYTES = 8 * 1024 * 1024;
+const MAX_PROVIDER_BYTES = 1024 * 1024;
+const STANDARD_REQUIRED_INSTRUCTIONS_BYTES = 8 * 1024;
+const MAX_CLAUDE_REQUIRED_INSTRUCTIONS_BYTES = 16 * 1024;
+const MAX_REQUIRED_MEMORY_BYTES = 6 * 1024;
+const RECEIPT_TTL_MS = 60_000;
+const FORBIDDEN_MEMORY = /-----BEGIN [A-Z ]*PRIVATE KEY-----|\b(?:sk|gh[opusu])_[A-Za-z0-9_-]{20,}\b|\b(?:password|passwort|secret|token|api[-_ ]?key|credential|permission|rights?|roles?|delegat|authoriz|berechtig|freigabe|approval|tool access|file access|network|production|payment|zahlung|policy)\b/i;
+
+function sha256(value) { return createHash("sha256").update(value).digest("hex"); }
+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 digestObject(value) { return sha256(canonical(value)); }
+function timestamp(value = new Date()) {
+  const date = value instanceof Date ? value : new Date(value);
+  if (!Number.isFinite(date.getTime())) throw new Error("preflight timestamp is invalid");
+  return date.toISOString();
+}
+function exactId(value, field, fallback = null) {
+  const selected = value === null || value === undefined || value === "" ? fallback : value;
+  if (typeof selected !== "string" || !ID_RE.test(selected) || selected.includes("*")) throw new Error(`${field} must be one exact ID`);
+  return selected;
+}
+function nullableId(value, field) { return value === null || value === undefined || value === "" ? null : exactId(value, field); }
+function storagePaths(env = process.env) {
+  const root = stateRoot(env);
+  return {
+    directory: join(root, "preflight"), policy: join(root, "policy", "preflight-policy.json"),
+    state: join(root, "preflight", "preflight-state.json"), memories: join(root, "context", "must-remember.json"),
+    key: join(root, "policy", "preflight-signing.key"), lock: join(root, "preflight", "preflight.lock")
+  };
+}
+function emptyPolicy() { return { schema: PREFLIGHT_POLICY_SCHEMA, revision: 0, profiles: [], history: [] }; }
+function emptyState() { return { schema: PREFLIGHT_SCHEMA, revision: 0, receipts: [], history: [], lastTurn: null }; }
+function emptyMemories() { return { schema: MUST_REMEMBER_SCHEMA, revision: 0, candidates: [], entries: [], history: [] }; }
+
+async function readJson(path, maximum, fallback) {
+  try {
+    const metadata = await stat(path);
+    if (!metadata.isFile() || metadata.size > maximum) throw new Error(`${basename(path)} is invalid or too large`);
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return fallback();
+    throw error;
+  }
+}
+async function writeJson(path, value, maximum = MAX_STATE_BYTES) {
+  const body = `${JSON.stringify(value, null, 2)}\n`;
+  if (Buffer.byteLength(body) > maximum) throw new Error(`${basename(path)} exceeds its state limit`);
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, body, { mode: 0o600 });
+    await replaceFileWithRetry(temporary, path);
+  } finally {
+    await unlink(temporary).catch((error) => { if (error.code !== "ENOENT") throw error; });
+  }
+}
+async function withLock(paths, task) {
+  await mkdir(paths.directory, { recursive: true, mode: 0o700 });
+  let handle;
+  for (let attempt = 0; attempt < 120; attempt += 1) {
+    try { handle = await open(paths.lock, "wx", 0o600); break; } catch (error) {
+      if (!isFileLockContention(error)) throw error;
+      try {
+        const metadata = await stat(paths.lock);
+        if (Date.now() - metadata.mtimeMs > 90_000) await unlink(paths.lock);
+      } catch (lockError) { if (lockError.code !== "ENOENT") throw lockError; }
+      await new Promise((resolvePromise) => setTimeout(resolvePromise, 25));
+    }
+  }
+  if (!handle) throw new Error("preflight state is busy; turn blocked");
+  try { return await task(); } finally {
+    await handle.close();
+    await unlink(paths.lock).catch((error) => { if (error.code !== "ENOENT") throw error; });
+  }
+}
+
+function normalizeProvider(provider) {
+  if (!provider || provider.schema !== "agentspine.retrieval-provider/v1") throw new Error("retrieval provider schema is invalid");
+  const value = {
+    schema: provider.schema, id: exactId(provider.id, "providerId"), adapter: provider.adapter,
+    required: provider.required === true, failClosed: provider.failClosed === true,
+    timeoutMs: Number(provider.timeoutMs ?? 5000), command: provider.command, args: provider.args || [],
+    credentialEnv: provider.credentialEnv || []
+  };
+  if (value.adapter !== "mnemo-command/v1" || !isAbsolute(value.command || "") || !Array.isArray(value.args)
+    || value.args.some((item) => typeof item !== "string" || item.length > 500)
+    || !Number.isInteger(value.timeoutMs) || value.timeoutMs < 100 || value.timeoutMs > 10_000
+    || !Array.isArray(value.credentialEnv) || value.credentialEnv.some((item) => !ENV_RE.test(item))) {
+    throw new Error("retrieval provider configuration is unsafe");
+  }
+  if (value.required && !value.failClosed) throw new Error("required retrieval providers must fail closed");
+  return value;
+}
+function normalizeProfile(profile) {
+  return {
+    id: exactId(profile.id, "profilePolicyId"), agentId: exactId(profile.agentId, "agentId"),
+    host: exactId(profile.host, "host"), profileId: exactId(profile.profileId, "profileId"),
+    tenantId: exactId(profile.tenantId, "tenantId"), enabled: profile.enabled === true,
+    providers: (profile.providers || []).map(normalizeProvider), authority: "authenticated-local-policy"
+  };
+}
+function validatePolicy(value) {
+  if (!value || value.schema !== PREFLIGHT_POLICY_SCHEMA || !Number.isInteger(value.revision)
+    || !Array.isArray(value.profiles) || !Array.isArray(value.history)
+    || value.history.some((item) => item?.authority !== "authenticated-local-policy")) throw new Error("preflight policy is corrupt; required turns are blocked");
+  value.profiles = value.profiles.map(normalizeProfile);
+  if (new Set(value.profiles.map((item) => item.id)).size !== value.profiles.length) throw new Error("preflight policy contains duplicate profiles");
+  return value;
+}
+function validateMemories(value) {
+  if (!value || value.schema !== MUST_REMEMBER_SCHEMA || !Number.isInteger(value.revision)
+    || !Array.isArray(value.candidates) || !Array.isArray(value.entries) || !Array.isArray(value.history)
+    || value.history.some((item) => item?.authority !== "context-only")
+    || [...value.candidates, ...value.entries].some((item) => !item || !ID_RE.test(item.id || "")
+      || typeof item.claim !== "string" || !item.claim || FORBIDDEN_MEMORY.test(item.claim)
+      || item.authority !== "context-only" || !ID_RE.test(item.userId || "") || !ID_RE.test(item.tenantId || ""))
+    || value.entries.some((item) => !DIGEST_RE.test(item.checksum || "") || item.checksum !== sha256(item.claim)
+      || !["active", "superseded"].includes(item.status) || !Number.isInteger(item.version) || item.version < 1)) {
+    throw new Error("must-remember state is corrupt; required recall is blocked");
+  }
+  return value;
+}
+function validateState(value) {
+  if (!value || value.schema !== PREFLIGHT_SCHEMA || !Number.isInteger(value.revision)
+    || !Array.isArray(value.receipts) || !Array.isArray(value.history)
+    || value.receipts.some((envelope) => {
+      const receipt = envelope?.receipt;
+      if (!receipt || receipt.schema !== PREFLIGHT_SCHEMA || receipt.status !== "ready"
+        || !ID_RE.test(receipt.id || "") || !DIGEST_RE.test(receipt.bodyDigest || "") || !DIGEST_RE.test(receipt.signature || "")
+        || !DIGEST_RE.test(envelope.stateSignature || "")
+        || (envelope.consumedAt !== null && !Number.isFinite(new Date(envelope.consumedAt).getTime()))
+        || (envelope.invalidatedAt !== null && envelope.invalidatedAt !== undefined
+          && !Number.isFinite(new Date(envelope.invalidatedAt).getTime()))) return true;
+      const { id, bodyDigest, signature: _signature, ...body } = receipt;
+      return id !== `preflight:${bodyDigest.slice(0, 32)}` || digestObject(body) !== bodyDigest;
+    })) throw new Error("preflight receipt state is corrupt; turn blocked");
+  return value;
+}
+function envelopeBody(envelope) {
+  return canonical({ bodyDigest: envelope.receipt.bodyDigest, consumedAt: envelope.consumedAt,
+    invalidatedAt: envelope.invalidatedAt ?? null });
+}
+async function signingKey(paths) {
+  await mkdir(dirname(paths.key), { recursive: true, mode: 0o700 });
+  try {
+    const value = await readFile(paths.key);
+    if (value.byteLength !== 32) throw new Error("preflight signing key is corrupt; turn blocked");
+    return value;
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    const value = randomBytes(32);
+    const handle = await open(paths.key, "wx", 0o600);
+    try { await handle.writeFile(value); } finally { await handle.close(); }
+    return value;
+  }
+}
+
+async function readVerifiedState(paths) {
+  const state = validateState(await readJson(paths.state, MAX_STATE_BYTES, emptyState));
+  if (!state.receipts.length) return state;
+  const key = await signingKey(paths);
+  for (const envelope of state.receipts) {
+    const expected = createHmac("sha256", key).update(envelope.receipt.bodyDigest).digest();
+    const actual = Buffer.from(envelope.receipt.signature, "hex");
+    if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
+      throw new Error("preflight receipt authentication failed; turn blocked");
+    }
+    const expectedState = createHmac("sha256", key).update(envelopeBody(envelope)).digest();
+    const actualState = Buffer.from(envelope.stateSignature, "hex");
+    if (actualState.length !== expectedState.length || !timingSafeEqual(actualState, expectedState)) {
+      throw new Error("preflight receipt lifecycle authentication failed; turn blocked");
+    }
+  }
+  return state;
+}
+
+export async function configurePreflightPolicy({ profile, confirmation, env = process.env }) {
+  if (confirmation !== CONFIRM_POLICY) throw new Error("preflight policy changes require explicit local owner confirmation");
+  const paths = storagePaths(env);
+  return withLock(paths, async () => {
+    const policy = validatePolicy(await readJson(paths.policy, MAX_POLICY_BYTES, emptyPolicy));
+    const normalized = normalizeProfile(profile);
+    policy.profiles = [...policy.profiles.filter((item) => item.id !== normalized.id), normalized];
+    policy.revision += 1;
+    policy.history.push({ event: "profile-configured", profileId: normalized.id, at: timestamp(), authority: "authenticated-local-policy" });
+    await writeJson(paths.policy, policy, MAX_POLICY_BYTES);
+    return { profile: normalized, revision: policy.revision, policyPath: paths.policy };
+  });
+}
+
+function memoryScope(input) {
+  return {
+    userId: exactId(input.userId, "userId"), tenantId: exactId(input.tenantId, "tenantId"),
+    projectId: nullableId(input.projectId, "projectId"), groupId: nullableId(input.groupId, "groupId"),
+    taskId: nullableId(input.taskId, "taskId")
+  };
+}
+function safeClaim(value) {
+  if (typeof value !== "string" || !value.trim() || Buffer.byteLength(value) > 4096 || FORBIDDEN_MEMORY.test(value)) {
+    throw new Error("must-remember claim is empty, too large, secret-shaped, or authority-shaped");
+  }
+  return value.trim().replace(/\s+/g, " ");
+}
+export async function proposeMustRemember({ claim, kind = "critical", sourceDigest, ...scope }, env = process.env) {
+  const paths = storagePaths(env);
+  const exactScope = memoryScope(scope);
+  const normalized = safeClaim(claim);
+  const id = `remember-candidate:${sha256(canonical({ claim: normalized, ...exactScope })).slice(0, 32)}`;
+  return withLock(paths, async () => {
+    const state = validateMemories(await readJson(paths.memories, MAX_STATE_BYTES, emptyMemories));
+    const existing = state.candidates.find((item) => item.id === id);
+    if (existing) return { candidate: existing, duplicate: true };
+    const candidate = { id, kind, claim: normalized, ...exactScope, sourceDigest: DIGEST_RE.test(sourceDigest || "") ? sourceDigest : null,
+      status: "pending-confirmation", observedAt: timestamp(), authority: "context-only" };
+    state.candidates.push(candidate); state.revision += 1;
+    state.history.push({ event: "proposed", id, at: candidate.observedAt, authority: "context-only" });
+    await writeJson(paths.memories, state);
+    return { candidate, duplicate: false };
+  });
+}
+export async function captureMustRememberPrompt({ prompt, receipt, env = process.env }) {
+  if (typeof prompt !== "string" || Buffer.byteLength(prompt) > 64 * 1024 || !receipt || receipt.schema !== PREFLIGHT_SCHEMA) return null;
+  const match = prompt.trim().match(/^(?:merk dir(?: bitte)?(?: dauerhaft)?(?: das)?|das ist wichtig|vergiss das niemals|remember (?:this|that)(?: permanently)?|never forget this)\s*[:,-]?\s*(.+)$/i);
+  if (!match?.[1]?.trim()) return null;
+  try {
+    return await proposeMustRemember({ claim: match[1], kind: "critical", userId: receipt.userId,
+      tenantId: receipt.tenantId, projectId: receipt.projectId, groupId: receipt.groupId,
+      taskId: receipt.taskId, sourceDigest: receipt.promptDigest }, env);
+  } catch (error) {
+    return { rejected: true, reason: error.message };
+  }
+}
+export async function confirmMustRemember({ candidateId, confirmation, supersedes = null }, env = process.env) {
+  if (confirmation !== CONFIRM_MEMORY) throw new Error("must-remember activation requires explicit local user confirmation");
+  const paths = storagePaths(env);
+  return withLock(paths, async () => {
+    const state = validateMemories(await readJson(paths.memories, MAX_STATE_BYTES, emptyMemories));
+    const candidate = state.candidates.find((item) => item.id === candidateId && item.status === "pending-confirmation");
+    if (!candidate) throw new Error("pending must-remember candidate not found");
+    const previous = supersedes ? state.entries.find((item) => item.id === supersedes && item.status === "active") : null;
+    if (supersedes && !previous) throw new Error("active must-remember entry to supersede was not found");
+    if (previous && ["userId", "tenantId", "projectId", "groupId", "taskId"].some((key) => previous[key] !== candidate[key])) {
+      throw new Error("must-remember supersession cannot cross scope");
+    }
+    const version = previous ? previous.version + 1 : 1;
+    const id = `remember:${sha256(`${candidate.id}\0${version}\0${timestamp()}`).slice(0, 32)}`;
+    const entry = { ...candidate, id, candidateId: candidate.id, version, supersedes: previous?.id || null,
+      checksum: sha256(candidate.claim), status: "active", confirmedAt: timestamp(), retention: "until-local-user-deletes",
+      confirmation: "explicit-local-user", authority: "context-only" };
+    delete entry.observedAt;
+    candidate.status = "confirmed";
+    if (previous) previous.status = "superseded";
+    state.entries.push(entry); state.revision += 1;
+    state.history.push({ event: "confirmed", id, supersedes: entry.supersedes, at: entry.confirmedAt, authority: "context-only" });
+    await writeJson(paths.memories, state);
+    return { entry, revision: state.revision };
+  });
+}
+export async function rollbackMustRemember({ id, confirmation }, env = process.env) {
+  if (confirmation !== CONFIRM_MEMORY) throw new Error("must-remember rollback requires explicit local user confirmation");
+  const paths = storagePaths(env);
+  return withLock(paths, async () => {
+    const state = validateMemories(await readJson(paths.memories, MAX_STATE_BYTES, emptyMemories));
+    const target = state.entries.find((item) => item.id === id);
+    if (!target) throw new Error("must-remember entry not found");
+    for (const item of state.entries) if (item.userId === target.userId && item.tenantId === target.tenantId
+      && item.projectId === target.projectId && item.groupId === target.groupId && item.taskId === target.taskId
+      && item.kind === target.kind && item.status === "active") item.status = "superseded";
+    target.status = "active"; state.revision += 1;
+    state.history.push({ event: "rolled-back", id, at: timestamp(), authority: "context-only" });
+    await writeJson(paths.memories, state);
+    return { entry: target, revision: state.revision };
+  });
+}
+export async function purgeMustRemember({ id, confirmation }, env = process.env) {
+  if (confirmation !== "local-user-purge-confirmed") throw new Error("permanent must-remember deletion requires explicit local user purge confirmation");
+  const paths = storagePaths(env);
+  return withLock(paths, async () => {
+    const state = validateMemories(await readJson(paths.memories, MAX_STATE_BYTES, emptyMemories));
+    const removed = state.entries.find((item) => item.id === id);
+    if (!removed) throw new Error("must-remember entry not found");
+    state.entries = state.entries.filter((item) => item.id !== id);
+    state.candidates = state.candidates.filter((item) => item.id !== removed.candidateId);
+    state.revision += 1; state.history.push({ event: "purged", idDigest: sha256(id), at: timestamp(), authority: "context-only" });
+    await writeJson(paths.memories, state);
+    return { purged: true, idDigest: sha256(id), revision: state.revision };
+  });
+}
+
+async function assertNoSymlinkParents(path, allowedRoot) {
+  const root = await realpath(allowedRoot);
+  const target = resolve(path);
+  if (!isInside(root, target)) throw new Error("required instruction escaped its allowed scope");
+  let cursor = target;
+  const chain = [];
+  while (cursor !== root) { chain.push(cursor); cursor = dirname(cursor); if (!isInside(root, cursor)) throw new Error("required instruction escaped its allowed scope"); }
+  chain.reverse();
+  for (const item of chain) {
+    const metadata = await lstat(item);
+    if (metadata.isSymbolicLink()) throw new Error("required instruction path contains a symlink");
+  }
+  return { root, target };
+}
+async function safeReadRequired(path, allowedRoot, maximum = STANDARD_REQUIRED_INSTRUCTIONS_BYTES, fileHooks = null) {
+  const checked = await assertNoSymlinkParents(path, allowedRoot);
+  const flags = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0);
+  const handle = await open(checked.target, flags);
+  try {
+    const before = await handle.stat();
+    if (!before.isFile()) throw new Error(`required instruction ${basename(path)} is not a regular file`);
+    if (before.size > maximum) {
+      throw new Error(`required instruction ${basename(path)} is ${before.size} bytes; mandatory limit is ${maximum} bytes`);
+    }
+    const buffer = Buffer.alloc(Number(before.size));
+    let offset = 0;
+    while (offset < buffer.length) {
+      const result = await handle.read(buffer, offset, buffer.length - offset, offset);
+      if (!result.bytesRead) break;
+      offset += result.bytesRead;
+    }
+    if (fileHooks?.afterRead) await fileHooks.afterRead(checked.target);
+    const after = await handle.stat();
+    if (offset !== buffer.length || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size
+      || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error(`required instruction ${basename(path)} changed during preflight`);
+    const finalPath = await assertNoSymlinkParents(checked.target, checked.root);
+    const current = await lstat(finalPath.target);
+    if (!current.isFile() || current.isSymbolicLink() || current.dev !== before.dev || current.ino !== before.ino
+      || current.size !== before.size || current.mtimeMs !== before.mtimeMs || current.ctimeMs !== before.ctimeMs) {
+      throw new Error(`required instruction ${basename(path)} was replaced during preflight`);
+    }
+    return { content: buffer.toString("utf8"), bytes: buffer.length, sha256: sha256(buffer),
+      identity: sha256(`${before.dev}\0${before.ino}\0${before.size}\0${before.mtimeMs}\0${before.ctimeMs}`) };
+  } finally { await handle.close(); }
+}
+
+function scopeFromInput({ input, scope, resolvedSources, env = process.env }) {
+  const supplied = input.agent_spine_scope && typeof input.agent_spine_scope === "object" ? input.agent_spine_scope : input;
+  return {
+    agentId: exactId(supplied.agent_id ?? supplied.agentId ?? scope.entityId, "agentId", "host-agent:default"),
+    personaId: nullableId(supplied.persona_id ?? supplied.personaId, "personaId"),
+    userId: exactId(supplied.user_id ?? supplied.userId ?? env.AGENTSPINE_USER_ID, "userId", "local-user"),
+    tenantId: exactId(supplied.tenant_id ?? supplied.tenantId ?? env.AGENTSPINE_TENANT_ID, "tenantId", "local-tenant"),
+    profileId: exactId(supplied.profile_id ?? supplied.profileId ?? env.AGENTSPINE_PROFILE_ID, "profileId", "default"),
+    sessionId: exactId(input.session_id ?? input.sessionId, "sessionId"), host: scope.host,
+    projectId: exactId(scope.projectId, "projectId", `project:${sha256(resolvedSources.projectRoot).slice(0, 20)}`),
+    groupId: nullableId(scope.groupId, "groupId"), taskId: nullableId(scope.currentTaskId, "taskId"),
+    cwd: resolvedSources.cwd, projectRoot: resolvedSources.projectRoot
+  };
+}
+function instructionDocuments(catalog, host) {
+  const pattern = host === "claude" ? /(?:^|\/)CLAUDE(?:\.local)?\.md$/ : /(?:^|\/)AGENTS(?:\.override)?\.md$/;
+  return catalog.documents.filter((item) => item.layer === "constitution" && pattern.test(item.relativePath))
+    .sort((left, right) => left.precedence - right.precedence || left.relativePath.localeCompare(right.relativePath));
+}
+function instructionBudget(host, usedBytes = 0) {
+  const hardLimitBytes = host === "claude"
+    ? MAX_CLAUDE_REQUIRED_INSTRUCTIONS_BYTES
+    : STANDARD_REQUIRED_INSTRUCTIONS_BYTES;
+  const overflowBytes = Math.max(0, usedBytes - STANDARD_REQUIRED_INSTRUCTIONS_BYTES);
+  return {
+    mode: overflowBytes ? "claude-required-overflow" : "standard",
+    standardBytes: STANDARD_REQUIRED_INSTRUCTIONS_BYTES,
+    hardLimitBytes,
+    usedBytes,
+    overflowBytes
+  };
+}
+async function rejectKnownInstructionSymlinks(resolvedSources, host) {
+  const candidates = host === "claude"
+    ? [join(resolvedSources.hostHome, "CLAUDE.md"), ...ancestorsBetween(resolvedSources.projectRoot, resolvedSources.cwd)
+      .flatMap((directory) => [join(directory, "CLAUDE.md"), join(directory, "CLAUDE.local.md"), join(directory, ".claude", "CLAUDE.md")])]
+    : [join(resolvedSources.hostHome, "AGENTS.override.md"), join(resolvedSources.hostHome, "AGENTS.md"),
+      ...ancestorsBetween(resolvedSources.projectRoot, resolvedSources.cwd)
+        .flatMap((directory) => [join(directory, "AGENTS.override.md"), join(directory, "AGENTS.md")])];
+  for (const path of candidates) {
+    try {
+      if ((await lstat(path)).isSymbolicLink()) throw new Error(`host instruction path is a symlink: ${basename(path)}`);
+    } catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+}
+function memoryMatches(entry, scope) {
+  return entry.status === "active" && entry.userId === scope.userId && entry.tenantId === scope.tenantId
+    && (entry.projectId === null || entry.projectId === scope.projectId)
+    && (entry.groupId === null || entry.groupId === scope.groupId)
+    && (entry.taskId === null || entry.taskId === scope.taskId);
+}
+function memoryProofs(entries) {
+  return entries.map((entry) => ({ id: entry.id, version: entry.version, checksum: entry.checksum }))
+    .sort((left, right) => left.id.localeCompare(right.id));
+}
+function retrievalQuery(scope, promptDigest, providerId) {
+  const body = { schema: RETRIEVAL_QUERY_SCHEMA, providerId, agentId: scope.agentId, personaId: scope.personaId,
+    userId: scope.userId, tenantId: scope.tenantId, host: scope.host, profileId: scope.profileId,
+    sessionId: scope.sessionId, projectId: scope.projectId, groupId: scope.groupId, taskId: scope.taskId,
+    cwdDigest: sha256(scope.cwd), promptDigest, requested: "current-effective-truth" };
+  return { ...body, queryDigest: digestObject(body) };
+}
+function normalizeResult(value, providerId, query) {
+  if (!value || value.schema !== RETRIEVAL_RESULT_SCHEMA || value.providerId !== providerId
+    || value.queryDigest !== query.queryDigest || value.status !== "ok" || !Array.isArray(value.items)
+    || value.items.length > 128) throw new Error(`retrieval provider ${providerId} returned an invalid or mismatched result`);
+  const items = value.items.map((item) => {
+    const itemScope = item?.scope;
+    const scopeKeys = ["agentId", "personaId", "userId", "tenantId", "profileId", "sessionId", "projectId", "groupId", "taskId"];
+    const exactScope = itemScope && typeof itemScope === "object" && !Array.isArray(itemScope)
+      && Object.keys(itemScope).every((key) => scopeKeys.includes(key))
+      && ["agentId", "userId", "tenantId"].every((key) => itemScope[key] === query[key])
+      && scopeKeys.every((key) => itemScope[key] === undefined || itemScope[key] === null || itemScope[key] === query[key]);
+    if (!item || !ID_RE.test(item.id || "") || !ID_RE.test(String(item.revision || ""))
+      || typeof item.claim !== "string" || !item.claim.trim() || Buffer.byteLength(item.claim) > 4096
+      || FORBIDDEN_MEMORY.test(item.claim) || !["current", "effective"].includes(item.validity)
+      || !Number.isFinite(Number(item.confidence)) || Number(item.confidence) < 0 || Number(item.confidence) > 1
+      || typeof item.source !== "string" || !ID_RE.test(item.source) || typeof item.whyLoaded !== "string"
+      || !item.whyLoaded.trim() || Buffer.byteLength(item.whyLoaded) > 512 || FORBIDDEN_MEMORY.test(item.whyLoaded)
+      || !exactScope) throw new Error(`retrieval provider ${providerId} returned an unsafe item`);
+    return { id: item.id, revision: String(item.revision), claim: item.claim.trim(), source: item.source,
+      scope: itemScope, validity: item.validity, confidence: Number(item.confidence), whyLoaded: item.whyLoaded.trim(), authority: "context-only" };
+  });
+  return { items, rejected: Number.isInteger(value.rejected) && value.rejected >= 0 ? value.rejected : 0 };
+}
+function providerInputError(provider, error) {
+  const wrapped = new Error(`retrieval adapter ${provider.id} input failed (${error.code || "stream-error"})`);
+  wrapped.code = error.code;
+  return wrapped;
+}
+function commandProviderAttempt(provider, query, env, executable) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const childEnv = { PATH: env.PATH || "" };
+    for (const name of provider.credentialEnv) {
+      if (typeof env[name] !== "string" || !env[name]) return rejectPromise(new Error(`retrieval adapter credential is missing: ${name}`));
+      childEnv[name] = env[name];
+    }
+    const child = spawn(executable, provider.args, { stdio: ["pipe", "pipe", "pipe"], env: childEnv, shell: false });
+    let stdout = ""; let stderrBytes = 0; let bytes = 0; let settled = false;
+    const finish = (error, value) => { if (settled) return; settled = true; clearTimeout(timer); error ? rejectPromise(error) : resolvePromise(value); };
+    const timer = setTimeout(() => { child.kill("SIGKILL"); finish(new Error(`retrieval adapter ${provider.id} timed out`)); }, provider.timeoutMs);
+    child.stdout.on("data", (chunk) => { bytes += chunk.length; if (bytes > MAX_PROVIDER_BYTES) { child.kill("SIGKILL"); finish(new Error("retrieval response exceeds 1 MiB")); } else stdout += chunk; });
+    child.stderr.on("data", (chunk) => { stderrBytes = Math.min(2048, stderrBytes + chunk.length); });
+    child.once("error", (error) => finish(error));
+    child.stdin.once("error", (error) => {
+      if (settled) return;
+      child.kill("SIGKILL");
+      finish(providerInputError(provider, error));
+    });
+    child.once("close", (code) => {
+      if (settled) return;
+      if (code !== 0) return finish(new Error(`retrieval adapter ${provider.id} failed (${code}; stderr-bytes<=${stderrBytes})`));
+      try { finish(null, JSON.parse(stdout)); } catch { finish(new Error(`retrieval adapter ${provider.id} returned invalid JSON`)); }
+    });
+    try { child.stdin.end(JSON.stringify(query)); }
+    catch (error) { child.kill("SIGKILL"); finish(providerInputError(provider, error)); }
+  });
+}
+async function commandProvider(provider, query, env, runner = null) {
+  if (runner) return runner(provider, query);
+  const executable = await realpath(provider.command);
+  const metadata = await lstat(executable);
+  if (!metadata.isFile() || metadata.isSymbolicLink()) throw new Error(`retrieval adapter ${provider.id} is not a regular executable`);
+  try { return await commandProviderAttempt(provider, query, env, executable); }
+  catch (error) {
+    if (error.code !== "EPIPE") throw error;
+    return commandProviderAttempt(provider, query, env, executable);
+  }
+}
+
+export async function runPreflight({ input, scope, resolvedSources, prompt, now = new Date(), env = process.env,
+  providerRunner = null, fileHooks = null }) {
+  if (typeof prompt !== "string" || !prompt.length || Buffer.byteLength(prompt) > 64 * 1024) throw new Error("preflight requires one bounded prompt");
+  const exactScope = scopeFromInput({ input, scope, resolvedSources, env });
+  const promptDigest = sha256(prompt);
+  const deliveryId = exactId(input.event_id ?? input.hook_event_id, "hookEventId",
+    `prompt:${sha256(`${exactScope.sessionId}\0${promptDigest}`).slice(0, 32)}`);
+  const paths = storagePaths(env);
+  const policy = validatePolicy(await readJson(paths.policy, MAX_POLICY_BYTES, emptyPolicy));
+  const profile = policy.profiles.find((item) => item.enabled && item.agentId === exactScope.agentId && item.host === exactScope.host
+    && item.profileId === exactScope.profileId && item.tenantId === exactScope.tenantId) || null;
+  const instructionHost = resolvedSources.host;
+  await rejectKnownInstructionSymlinks(resolvedSources, instructionHost);
+  const documents = instructionDocuments(resolvedSources.catalog, instructionHost);
+  const requiredInstructions = [];
+  let instructionBytes = 0;
+  const maximumInstructionBytes = instructionBudget(instructionHost).hardLimitBytes;
+  for (const document of documents) {
+    const allowedRoot = document.sourceScope === "user" ? resolvedSources.hostHome : resolvedSources.projectRoot;
+    const snapshot = await safeReadRequired(document.path, allowedRoot, maximumInstructionBytes, fileHooks);
+    if (snapshot.sha256 !== document.sha256 || snapshot.bytes !== document.bytes) throw new Error(`required instruction changed after source resolution: ${document.relativePath}`);
+    instructionBytes += snapshot.bytes;
+    if (instructionBytes > maximumInstructionBytes) {
+      throw new Error(`required host instructions total ${instructionBytes} bytes; mandatory limit is ${maximumInstructionBytes} bytes`);
+    }
+    requiredInstructions.push({ path: document.path, displayPath: document.relativePath, scope: document.sourceScope,
+      bytes: snapshot.bytes, sha256: snapshot.sha256, identity: snapshot.identity, content: snapshot.content });
+  }
+  const appliedInstructionBudget = instructionBudget(instructionHost, instructionBytes);
+  const memoryState = validateMemories(await readJson(paths.memories, MAX_STATE_BYTES, emptyMemories));
+  const mustRemember = memoryState.entries.filter((item) => memoryMatches(item, exactScope));
+  if (Buffer.byteLength(JSON.stringify(mustRemember.map((item) => item.claim))) > MAX_REQUIRED_MEMORY_BYTES) {
+    throw new Error("confirmed must-remember entries exceed the mandatory preflight budget");
+  }
+  const providerResults = [];
+  for (const provider of profile?.providers || []) {
+    const query = retrievalQuery(exactScope, promptDigest, provider.id);
+    try {
+      const response = normalizeResult(await commandProvider(provider, query, env, providerRunner), provider.id, query);
+      providerResults.push({ providerId: provider.id, queryDigest: query.queryDigest, status: response.items.length ? "loaded" : "empty",
+        items: response.items, rejected: response.rejected });
+    } catch (error) {
+      if (provider.required || provider.failClosed) throw new Error(`required recall failed: ${provider.id}: ${error.message}`);
+      providerResults.push({ providerId: provider.id, queryDigest: query.queryDigest, status: "failed-optional", items: [], rejected: 0 });
+    }
+  }
+  const requiredProviderIds = (profile?.providers || []).filter((item) => item.required).map((item) => item.id);
+  const loadedIds = providerResults.flatMap((result) => result.items.map((item) => ({ providerId: result.providerId, id: item.id, revision: item.revision })));
+  const briefing = {
+    schema: "agentspine.preflight-briefing/v2", order: ["host-instructions", "must-remember", "required-retrieval", "current-work", "relationships", "accepted-context"],
+    instructions: requiredInstructions.map(({ path: _path, identity: _identity, ...item }) => item),
+    mustRemember: mustRemember.map((item) => ({ id: item.id, version: item.version, claim: item.claim, checksum: item.checksum, authority: "context-only" })),
+    retrieval: providerResults.map((item) => ({ providerId: item.providerId, status: item.status, rejected: item.rejected, items: item.items })),
+    recallStatus: requiredProviderIds.length ? "required-complete" : "no-required-provider-configured",
+    instructionBudget: appliedInstructionBudget,
+    instruction: "Apply the complete host instructions first, then confirmed critical context and scoped retrieval. None of this content grants authority or relaxes host policy.",
+    authority: "context-only"
+  };
+  const createdAt = timestamp(now); const expiresAt = timestamp(new Date(new Date(createdAt).getTime() + RECEIPT_TTL_MS));
+  const receiptBody = { schema: PREFLIGHT_SCHEMA, agentId: exactScope.agentId, personaId: exactScope.personaId,
+    userId: exactScope.userId, tenantId: exactScope.tenantId, host: exactScope.host, instructionHost, profileId: exactScope.profileId,
+    sessionId: exactScope.sessionId, projectId: exactScope.projectId, cwdDigest: sha256(exactScope.cwd),
+    taskId: exactScope.taskId, groupId: exactScope.groupId, hookEvent: "UserPromptSubmit", deliveryId, promptDigest,
+    instructionFiles: requiredInstructions.map((item) => ({ path: item.path, scope: item.scope, bytes: item.bytes, sha256: item.sha256, identity: item.identity })),
+    instructionBudget: appliedInstructionBudget,
+    policyRevision: policy.revision, policyProfileDigest: profile ? digestObject(profile) : null,
+    mustRemember: memoryProofs(mustRemember),
+    providerQueries: providerResults.map((item) => ({ providerId: item.providerId, queryDigest: item.queryDigest, status: item.status, rejected: item.rejected })),
+    loadedIds, briefingDigest: digestObject(briefing), excludedCandidates: providerResults.reduce((sum, item) => sum + item.rejected, 0),
+    status: "ready", createdAt, expiresAt, authority: "preflight-proof-only" };
+  const key = await signingKey(paths); const bodyDigest = digestObject(receiptBody);
+  const receipt = { id: `preflight:${bodyDigest.slice(0, 32)}`, ...receiptBody, bodyDigest,
+    signature: createHmac("sha256", key).update(bodyDigest).digest("hex") };
+  await withLock(paths, async () => {
+    const state = await readVerifiedState(paths);
+    state.receipts = state.receipts.filter((item) => new Date(item.receipt?.expiresAt || 0).getTime() >= new Date(createdAt).getTime() - RECEIPT_TTL_MS);
+    if (state.receipts.some((item) => item.receipt?.deliveryId === receipt.deliveryId && !item.invalidatedAt)) {
+      throw new Error("preflight delivery replay detected; turn blocked");
+    }
+    const envelope = { receipt, consumedAt: null, invalidatedAt: null, stateSignature: "" };
+    envelope.stateSignature = createHmac("sha256", key).update(envelopeBody(envelope)).digest("hex");
+    state.receipts.push(envelope); state.revision += 1;
+    state.lastTurn = { status: "ready", receiptId: receipt.id, at: createdAt, host: exactScope.host,
+      instructionHost, instructionFiles: receipt.instructionFiles.length, recall: receipt.providerQueries.map((item) => ({
+        providerId: item.providerId, status: item.status, rejected: item.rejected
+      })), cwdDigest: receipt.cwdDigest, authority: "diagnostic-only" };
+    state.history.push({ event: "ready", receiptId: receipt.id, at: createdAt, authority: "preflight-proof-only" });
+    await writeJson(paths.state, state);
+  });
+  return { receipt, briefing, policy: { configured: Boolean(profile), requiredProviderIds } };
+}
+
+export async function verifyPreflightReceipt({ receipt, input, scope, resolvedSources, prompt, now = new Date(), env = process.env, consume = false }) {
+  const exactScope = scopeFromInput({ input, scope, resolvedSources, env });
+  const current = new Date(now).getTime();
+  if (!receipt || receipt.schema !== PREFLIGHT_SCHEMA || receipt.status !== "ready" || !DIGEST_RE.test(receipt.bodyDigest || "")
+    || !DIGEST_RE.test(receipt.signature || "") || new Date(receipt.expiresAt).getTime() < current
+    || receipt.promptDigest !== sha256(prompt) || receipt.agentId !== exactScope.agentId || receipt.personaId !== exactScope.personaId
+    || receipt.userId !== exactScope.userId
+    || receipt.tenantId !== exactScope.tenantId || receipt.host !== exactScope.host || receipt.profileId !== exactScope.profileId
+    || receipt.sessionId !== exactScope.sessionId || receipt.projectId !== exactScope.projectId || receipt.cwdDigest !== sha256(exactScope.cwd)
+    || receipt.taskId !== exactScope.taskId || receipt.groupId !== exactScope.groupId) return false;
+  const deliveryId = exactId(input.event_id ?? input.hook_event_id, "hookEventId",
+    `prompt:${sha256(`${exactScope.sessionId}\0${sha256(prompt)}`).slice(0, 32)}`);
+  if (receipt.deliveryId !== deliveryId) return false;
+  const { id: _id, bodyDigest, signature, ...body } = receipt;
+  if (digestObject(body) !== bodyDigest) return false;
+  const key = await signingKey(storagePaths(env));
+  const expected = createHmac("sha256", key).update(bodyDigest).digest();
+  const actual = Buffer.from(signature, "hex");
+  if (!(actual.length === expected.length && timingSafeEqual(actual, expected))) return false;
+  try {
+    const paths = storagePaths(env);
+    const [policy, memories, freshSources, receiptState] = await Promise.all([
+      readJson(paths.policy, MAX_POLICY_BYTES, emptyPolicy).then(validatePolicy),
+      readJson(paths.memories, MAX_STATE_BYTES, emptyMemories).then(validateMemories),
+      resolveHostSourceCatalog({ host: receipt.instructionHost, cwd: exactScope.cwd, input, env }),
+      readVerifiedState(paths)
+    ]);
+    const storedEnvelope = receiptState.receipts.find((item) => item.receipt?.id === receipt.id
+      && item.receipt?.bodyDigest === receipt.bodyDigest);
+    if (!storedEnvelope || storedEnvelope.consumedAt !== null || storedEnvelope.invalidatedAt) return false;
+    const profile = policy.profiles.find((item) => item.enabled && item.agentId === exactScope.agentId && item.host === exactScope.host
+      && item.profileId === exactScope.profileId && item.tenantId === exactScope.tenantId) || null;
+    if (receipt.policyRevision !== policy.revision || receipt.policyProfileDigest !== (profile ? digestObject(profile) : null)) return false;
+    if (canonical(receipt.mustRemember) !== canonical(memoryProofs(memories.entries.filter((item) => memoryMatches(item, exactScope))))) return false;
+    if (receipt.instructionHost !== freshSources.host) return false;
+    await rejectKnownInstructionSymlinks(freshSources, freshSources.host);
+    const currentDocuments = instructionDocuments(freshSources.catalog, freshSources.host);
+    if (currentDocuments.length !== receipt.instructionFiles.length
+      || currentDocuments.some((document, index) => document.path !== receipt.instructionFiles[index]?.path)) return false;
+    let instructionBytes = 0;
+    const maximumInstructionBytes = instructionBudget(receipt.instructionHost).hardLimitBytes;
+    for (const instruction of receipt.instructionFiles) {
+      const allowedRoot = instruction.scope === "user" ? freshSources.hostHome : freshSources.projectRoot;
+      const currentSnapshot = await safeReadRequired(instruction.path, allowedRoot, maximumInstructionBytes);
+      if (currentSnapshot.sha256 !== instruction.sha256 || currentSnapshot.bytes !== instruction.bytes
+        || currentSnapshot.identity !== instruction.identity) return false;
+      instructionBytes += currentSnapshot.bytes;
+    }
+    if (instructionBytes > maximumInstructionBytes
+      || canonical(receipt.instructionBudget) !== canonical(instructionBudget(receipt.instructionHost, instructionBytes))) return false;
+  } catch { return false; }
+  if (consume) {
+    const paths = storagePaths(env);
+    const consumed = await withLock(paths, async () => {
+      const state = await readVerifiedState(paths);
+      const stored = state.receipts.find((item) => item.receipt?.id === receipt.id && item.receipt?.bodyDigest === receipt.bodyDigest);
+      if (!stored || stored.consumedAt !== null || stored.invalidatedAt) return false;
+      stored.consumedAt = timestamp(now); state.revision += 1;
+      stored.stateSignature = createHmac("sha256", key).update(envelopeBody(stored)).digest("hex");
+      state.lastTurn = { ...(state.lastTurn || {}), status: "consumed", receiptId: receipt.id,
+        at: stored.consumedAt, authority: "diagnostic-only" };
+      state.history.push({ event: "consumed", receiptId: receipt.id, at: stored.consumedAt, authority: "preflight-proof-only" });
+      await writeJson(paths.state, state);
+      return true;
+    });
+    if (!consumed) return false;
+  }
+  return true;
+}
+
+function failureCode(error) {
+  const message = String(error?.message || error || "");
+  if (/source resolution|required instruction|host instruction/i.test(message)) return "instructions-failed";
+  if (/required recall|retrieval provider|adapter/i.test(message)) return "provider-failed";
+  if (/budget|injection limit|too large|cannot fit/i.test(message)) return "budget-failed";
+  if (/receipt|replay|delivery/i.test(message)) return "receipt-failed";
+  return "preflight-failed";
+}
+
+export async function recordPreflightFailure({ receiptId = null, input = {}, host = null, error,
+  now = new Date(), env = process.env }) {
+  const paths = storagePaths(env);
+  return withLock(paths, async () => {
+    const state = await readVerifiedState(paths);
+    const at = timestamp(now);
+    if (receiptId) {
+      const stored = state.receipts.find((item) => item.receipt?.id === receiptId
+        && item.consumedAt === null && !item.invalidatedAt);
+      if (stored) {
+        stored.invalidatedAt = at;
+        const key = await signingKey(paths);
+        stored.stateSignature = createHmac("sha256", key).update(envelopeBody(stored)).digest("hex");
+      }
+    }
+    const code = failureCode(error);
+    state.lastTurn = { status: "blocked", code, receiptId, at, host: host || null,
+      deliveryDigest: sha256(String(input.event_id ?? input.hook_event_id ?? "missing")), authority: "diagnostic-only" };
+    state.revision += 1;
+    state.history.push({ event: "blocked", code, receiptId, at, authority: "preflight-proof-only" });
+    await writeJson(paths.state, state);
+    return state.lastTurn;
+  });
+}
+
+export async function preflightStatus(env = process.env) {
+  const paths = storagePaths(env);
+  const [policy, memories, state] = await Promise.all([
+    readJson(paths.policy, MAX_POLICY_BYTES, emptyPolicy).then(validatePolicy),
+    readJson(paths.memories, MAX_STATE_BYTES, emptyMemories).then(validateMemories),
+    readVerifiedState(paths)
+  ]);
+  return { schema: PREFLIGHT_SCHEMA, policies: policy.profiles.length, requiredProviders: policy.profiles.flatMap((item) => item.providers).filter((item) => item.required).length,
+    pendingMemories: memories.candidates.filter((item) => item.status === "pending-confirmation").length,
+    activeMustRemember: memories.entries.filter((item) => item.status === "active").length,
+    readyReceipts: state.receipts.filter((item) => item.consumedAt === null && !item.invalidatedAt && item.receipt?.status === "ready"
+      && new Date(item.receipt.expiresAt).getTime() >= Date.now()).length,
+    status: policy.profiles.some((item) => item.providers.some((provider) => provider.required)) ? "wrapper-hard-required" : "instructions-only-no-required-provider",
+    lastTurn: state.lastTurn,
+    authority: "diagnostic-only" };
+}