blun-king-cli 9.1.567 → 9.1.569

package/agent-spine-plugin/src/lib/codex-skill-installation.js

@@ -0,0 +1,211 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, open, readFile, realpath, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { withOwnedFileLock } from "./owned-file-lock.js";
+import { replaceFileWithRetry } from "./filesystem-retry.js";
+
+const MARKER_SCHEMA = "agentspine.codex-skill-installation/v1";
+const AUTHORITY = "host-registration-only";
+const SKILL_NAME = "agent-spine";
+const MAX_SKILL_BYTES = 256 * 1024;
+
+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 seal(value) {
+  return { ...value, digest: sha256(canonical(value)) };
+}
+
+function verifySeal(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || typeof value.digest !== "string") return false;
+  const { digest, ...payload } = value;
+  return digest === sha256(canonical(payload));
+}
+
+async function exactDirectory(path, label, { create = false } = {}) {
+  if (!isAbsolute(path)) throw new Error(`${label} must be absolute`);
+  const target = resolve(path);
+  if (create) await mkdir(target, { recursive: true, mode: 0o700 });
+  const metadata = await lstat(target);
+  if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+    throw new Error(`${label} must be a regular non-symlink directory`);
+  }
+  return realpath(target);
+}
+
+async function regularOrMissing(path, label) {
+  try {
+    const metadata = await lstat(path);
+    if (!metadata.isFile() || metadata.isSymbolicLink()) {
+      throw new Error(`${label} must be a regular non-symlink file`);
+    }
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function atomicWrite(path, content, assertOwned) {
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  let handle;
+  try {
+    handle = await open(temporary, "wx", 0o600);
+    await handle.writeFile(content);
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await replaceFileWithRetry(temporary, path, { beforeAttempt: assertOwned });
+  } finally {
+    await handle?.close();
+    await rm(temporary, { force: true }).catch(() => {});
+  }
+}
+
+async function sourceSkill(packageRoot) {
+  const root = await exactDirectory(packageRoot, "AgentSpine package root");
+  const packagePath = join(root, "package.json");
+  const skillPath = join(root, "skills", SKILL_NAME, "SKILL.md");
+  if (!await regularOrMissing(packagePath, "AgentSpine package manifest")) {
+    throw new Error("AgentSpine package manifest is missing");
+  }
+  if (!await regularOrMissing(skillPath, "AgentSpine skill source")) {
+    throw new Error("AgentSpine skill source is missing");
+  }
+  const [packageText, content] = await Promise.all([
+    readFile(packagePath, "utf8"), readFile(skillPath)
+  ]);
+  if (content.length === 0 || content.length > MAX_SKILL_BYTES) {
+    throw new Error("AgentSpine skill source size is outside the install limit");
+  }
+  const version = JSON.parse(packageText).version;
+  if (typeof version !== "string" || !version) throw new Error("AgentSpine package version is missing");
+  if (!content.toString("utf8").startsWith("---\nname: agent-spine\n")) {
+    throw new Error("AgentSpine skill source has invalid frontmatter");
+  }
+  return { packageRoot: root, sourcePath: skillPath, version, content, digest: sha256(content) };
+}
+
+async function readMarker(path) {
+  if (!await regularOrMissing(path, "Codex AgentSpine skill marker")) return null;
+  let value;
+  try { value = JSON.parse(await readFile(path, "utf8")); }
+  catch (error) { throw new Error("Codex AgentSpine skill marker is malformed", { cause: error }); }
+  if (!verifySeal(value) || value.schema !== MARKER_SCHEMA || !["updating", "installed"].includes(value.state)) {
+    throw new Error("Codex AgentSpine skill marker is invalid");
+  }
+  return value;
+}
+
+async function digestOrNull(path) {
+  return await regularOrMissing(path, "Codex AgentSpine SKILL.md") ? sha256(await readFile(path)) : null;
+}
+
+async function recoverMarker(marker, markerPath, skillPath, assertOwned) {
+  if (!marker) return null;
+  const actual = await digestOrNull(skillPath);
+  if (marker.state === "installed") {
+    if (actual !== marker.skillDigest) throw new Error("installed Codex AgentSpine skill was changed outside its managed update");
+    return marker;
+  }
+  if (actual === marker.targetDigest) {
+    const recovered = seal({
+      schema: MARKER_SCHEMA, state: "installed", skillName: SKILL_NAME,
+      skillDigest: marker.targetDigest, version: marker.targetVersion,
+      packageRoot: marker.targetPackageRoot, authority: AUTHORITY
+    });
+    await atomicWrite(markerPath, `${JSON.stringify(recovered, null, 2)}\n`, assertOwned);
+    return recovered;
+  }
+  if (actual === marker.previousDigest) {
+    if (actual === null) {
+      await assertOwned();
+      await rm(markerPath, { force: true });
+      return null;
+    }
+    const recovered = seal({
+      schema: MARKER_SCHEMA, state: "installed", skillName: SKILL_NAME,
+      skillDigest: marker.previousDigest, version: marker.previousVersion,
+      packageRoot: marker.previousPackageRoot, authority: AUTHORITY
+    });
+    await atomicWrite(markerPath, `${JSON.stringify(recovered, null, 2)}\n`, assertOwned);
+    return recovered;
+  }
+  throw new Error("Codex AgentSpine skill update has an unrecognized partial state");
+}
+
+export function defaultCodexSkillsRoot(env = process.env) {
+  const home = env.HOME || env.USERPROFILE || homedir();
+  return resolve(env.AGENTSPINE_CODEX_SKILLS_ROOT || join(home, ".agents", "skills"));
+}
+
+export async function installCodexSkill({
+  skillsRoot = defaultCodexSkillsRoot(), packageRoot,
+  faultAfter = null
+} = {}) {
+  const source = await sourceSkill(packageRoot);
+  const root = await exactDirectory(skillsRoot, "Codex user skills root", { create: true });
+  const skillDirectoryPath = join(root, SKILL_NAME);
+  const lockPath = join(root, ".agent-spine-install.lock");
+  if (await regularOrMissing(lockPath, "Codex AgentSpine skill install lock")) {
+    // withOwnedFileLock owns regular stale/current lock handling.
+  }
+  return withOwnedFileLock(lockPath, async ({ assertOwned, recovered: lockRecovered }) => {
+    let created = false;
+    try { await exactDirectory(skillDirectoryPath, "Codex AgentSpine skill directory"); }
+    catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      await mkdir(skillDirectoryPath, { mode: 0o700 });
+      created = true;
+    }
+    const skillDirectory = await realpath(skillDirectoryPath);
+    const markerPath = join(skillDirectory, ".agentspine-install.json");
+    const skillPath = join(skillDirectory, "SKILL.md");
+    let marker = await readMarker(markerPath);
+    if (!marker && !created) {
+      throw new Error("Codex already has an unmanaged agent-spine skill directory");
+    }
+    marker = await recoverMarker(marker, markerPath, skillPath, assertOwned);
+    if (marker?.skillDigest === source.digest && marker.version === source.version
+      && marker.packageRoot === source.packageRoot) {
+      return {
+        schema: "agentspine.codex-skill-install-result/v1", status: "unchanged",
+        version: source.version, packageRoot: source.packageRoot, skillPath, skillDigest: source.digest,
+        markerPath, markerDigest: marker.digest, recovered: lockRecovered, authority: AUTHORITY
+      };
+    }
+    const updating = seal({
+      schema: MARKER_SCHEMA, state: "updating", skillName: SKILL_NAME,
+      previousDigest: marker?.skillDigest ?? null, previousVersion: marker?.version ?? null,
+      previousPackageRoot: marker?.packageRoot ?? null,
+      targetDigest: source.digest, targetVersion: source.version,
+      targetPackageRoot: source.packageRoot, authority: AUTHORITY
+    });
+    await atomicWrite(markerPath, `${JSON.stringify(updating, null, 2)}\n`, assertOwned);
+    if (faultAfter === "marker") throw new Error("synthetic crash after Codex skill update marker");
+    await atomicWrite(skillPath, source.content, assertOwned);
+    if (faultAfter === "skill") throw new Error("synthetic crash after Codex skill publication");
+    const installed = seal({
+      schema: MARKER_SCHEMA, state: "installed", skillName: SKILL_NAME,
+      skillDigest: source.digest, version: source.version,
+      packageRoot: source.packageRoot, authority: AUTHORITY
+    });
+    await atomicWrite(markerPath, `${JSON.stringify(installed, null, 2)}\n`, assertOwned);
+    return {
+      schema: "agentspine.codex-skill-install-result/v1",
+      status: marker ? "updated" : "installed", version: source.version, packageRoot: source.packageRoot,
+      skillPath, skillDigest: source.digest, markerPath, markerDigest: installed.digest,
+      recovered: lockRecovered, authority: AUTHORITY
+    };
+  });
+}

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

@@ -4,6 +4,7 @@ import { ancestorsBetween, canonicalPath, isInside } from "./paths.js";
 import { buildCatalog } from "./catalog.js";
 import { attachDocumentSnapshot, documentSnapshotContent } from "./documents.js";
 import { loadGraph } from "./graph.js";
+import { readCatalogDocument } from "./catalog-document-read.js";
 
 function depth(root, path) {
   const value = relative(root, dirname(path));
@@ -131,8 +132,9 @@ export async function resolveContext({ root = process.cwd(), cwd = root, host =
   };
 }
 
-export async function readDocument({ root = process.cwd(), path, offset = 0, length = 65536 }) {
+export async function readDocument({ root = process.cwd(), path, offset = 0, length = 65536, catalog: providedCatalog = null }) {
   if (!path) throw new Error("path is required");
+  if (providedCatalog) return readCatalogDocument({ root, path, offset, length, catalog: providedCatalog });
   const catalog = await buildCatalog(root);
   const absolute = resolve(catalog.root, path);
   const document = catalog.documents.find((item) => item.path === absolute);

package/agent-spine-plugin/src/lib/delivery-agent-usage.js

@@ -0,0 +1,224 @@
+import { mkdir, readFile, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { withOwnedFileLock } from "./owned-file-lock.js";
+import { canonicalPath, projectStateDir } from "./paths.js";
+import { writePremortemFile } from "./delivery-premortem-file.js";
+import { inspectPremortemState } from "./delivery-premortem.js";
+import { parsePremortemRequirementId } from "./delivery-premortem-binding.js";
+import { premortemBlock as block, premortemBoundary as boundary } from "./delivery-premortem-results.js";
+import { premortemSha256 as sha256, premortemTime as at,
+  sealPremortem as seal, validPremortemSeal as validSeal,
+  validPremortemTime as validTime } from "./delivery-premortem-codec.js";
+
+const STATE_SCHEMA = "agentspine.delivery-agent-usage/v1";
+const RECEIPT_SCHEMA = "agentspine.delivery-agent-use-receipt/v1";
+const AUTHORITY = "context-only";
+const MAX_BYTES = 32 * 1024;
+const DIGEST_RE = /^[a-f0-9]{64}$/;
+
+export const DELIVERY_AGENT_USE_TEXT = [
+  "Reuse a host-verified briefing for this requirement; no second content fetch is needed.",
+  "Use delivery_knowledge_query and record_delivery_premortem for relevant preparation.",
+  "Without a verified briefing, report uncertainty; session_briefing is optional. No automatic retry or work restriction.",
+  "Only matching host or MCP evidence counts; claims, foreign or reused receipts do not. Context-only; no authority."
+].join("\n");
+
+function stateMaterial(state) {
+  const material = { ...state };
+  delete material.integrityDigest;
+  return material;
+}
+
+function sealState(state) {
+  return { ...state, integrityDigest: sha256(stateMaterial(state)) };
+}
+
+function validReceipt(value, stage, requirementId) {
+  return value && value.schema === RECEIPT_SCHEMA && value.stage === stage
+    && value.requirementId === requirementId && value.authority === AUTHORITY
+    && (value.origin === undefined || value.origin === "verified-host-preflight")
+    && DIGEST_RE.test(value.inputDigest || "") && DIGEST_RE.test(value.resultDigest || "")
+    && validTime(value.recordedAt) && validSeal(value);
+}
+
+function validateState(state, parsed) {
+  if (!state || state.schema !== STATE_SCHEMA || state.authority !== AUTHORITY
+    || state.requirementId !== `premortem-requirement:${parsed.laneDigest}:${parsed.generationDigest}`
+    || state.laneDigest !== parsed.laneDigest || state.generationDigest !== parsed.generationDigest
+    || !Number.isInteger(state.revision) || state.revision < 0 || state.revision > 3
+    || (state.briefing !== null && !validReceipt(state.briefing, "briefing", state.requirementId))
+    || (state.knowledge !== null && !validReceipt(state.knowledge, "knowledge", state.requirementId))
+    || Boolean(state.knowledge) > Boolean(state.briefing)
+    || (state.consumedAt !== null && !validTime(state.consumedAt))
+    || (state.consumedDigest !== null && !DIGEST_RE.test(state.consumedDigest))
+    || Boolean(state.consumedAt) !== Boolean(state.consumedDigest)
+    || !DIGEST_RE.test(state.integrityDigest || "")
+    || state.integrityDigest !== sha256(stateMaterial(state))) {
+    const error = new Error("delivery AgentSpine usage state failed integrity validation");
+    error.code = "AGENTSPINE_USAGE_UNCERTAIN";
+    throw error;
+  }
+  return state;
+}
+
+async function pathsFor(root, requirementId) {
+  const parsed = parsePremortemRequirementId(requirementId);
+  const directory = join(await projectStateDir(await canonicalPath(root)), "delivery-agent-usage");
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const path = join(directory, `${parsed.generationDigest}.json`);
+  return { parsed, path, lockPath: `${path}.lock` };
+}
+
+async function readState(path, parsed) {
+  try {
+    const text = await readFile(path, "utf8");
+    if (Buffer.byteLength(text) > MAX_BYTES) throw new Error("delivery AgentSpine usage state exceeds 32 KiB");
+    return validateState(JSON.parse(text), parsed);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    if (error instanceof SyntaxError) {
+      const invalid = new Error("delivery AgentSpine usage state is not valid JSON");
+      invalid.code = "AGENTSPINE_USAGE_UNCERTAIN";
+      throw invalid;
+    }
+    throw error;
+  }
+}
+
+function emptyState(requirementId, parsed) {
+  return sealState({ schema: STATE_SCHEMA, requirementId,
+    laneDigest: parsed.laneDigest, generationDigest: parsed.generationDigest,
+    revision: 0, briefing: null, knowledge: null,
+    consumedAt: null, consumedDigest: null, authority: AUTHORITY });
+}
+
+async function currentRequirement(root, requirementId) {
+  const current = await inspectPremortemState({ root, requirementId });
+  if (current.status === "degraded") return current;
+  if (current.blocked) return current;
+  if (current.status === "absent" || !current.requirement) {
+    return block("stale", `AgentSpine cannot bind usage to current requirement ${requirementId}.`,
+      { requirementId });
+  }
+  return current;
+}
+
+function receipt(stage, requirementId, input, result, now, verifiedHostBriefing) {
+  return seal({ schema: RECEIPT_SCHEMA, stage, requirementId,
+    ...(verifiedHostBriefing ? { origin: "verified-host-preflight" } : {}),
+    inputDigest: sha256(input), resultDigest: sha256(result),
+    recordedAt: at(now), authority: AUTHORITY });
+}
+
+async function recordStage({ root, requirementId, stage, input, result,
+  verifiedHostBriefing = false, preserveConsumed = false, now = new Date() }) {
+  try {
+    const current = await currentRequirement(root, requirementId);
+    if (current.status === "degraded" || current.blocked) return current;
+    const paths = await pathsFor(root, requirementId);
+    return await withOwnedFileLock(paths.lockPath, async ({ assertOwned }) => {
+      let state = await readState(paths.path, paths.parsed)
+        || emptyState(requirementId, paths.parsed);
+      if (!preserveConsumed && state.briefing?.origin !== "verified-host-preflight"
+        && state.consumedAt && stage === "briefing" && current.closed && !current.consumed) {
+        state = emptyState(requirementId, paths.parsed);
+      } else if (state.consumedAt) return block("reused",
+        `AgentSpine usage receipts for ${requirementId} were already consumed.`, { requirementId });
+      if (stage === "knowledge" && !state.briefing) return block("missing-briefing",
+        "AgentSpine delivery preflight is missing stage 1: session_briefing.", { requirementId });
+      if (stage === "briefing" && !verifiedHostBriefing && state.briefing?.origin === "verified-host-preflight") {
+        return { status: "satisfied-by-host", blocked: false, requirementId,
+          receipt: structuredClone(state.briefing), digest: state.briefing.digest };
+      }
+      const proposed = receipt(stage, requirementId, input, result, now, verifiedHostBriefing);
+      if (state[stage]) {
+        if (state[stage].inputDigest !== proposed.inputDigest
+          || state[stage].resultDigest !== proposed.resultDigest) {
+          return block(`conflicting-${stage}`,
+            `AgentSpine delivery preflight has a conflicting ${stage} call.`, { requirementId });
+        }
+        return { status: "duplicate", blocked: false, requirementId,
+          receipt: structuredClone(state[stage]), digest: state[stage].digest };
+      }
+      state[stage] = proposed;
+      state.revision += 1;
+      state = sealState(state);
+      await writePremortemFile(paths.path, state, assertOwned, MAX_BYTES);
+      return { status: "recorded", blocked: false, requirementId,
+        receipt: structuredClone(proposed), digest: proposed.digest };
+    });
+  } catch (error) {
+    return boundary(error);
+  }
+}
+
+export function deliveryAgentUseGuidance(root, requirementId) {
+  return { root, requirementId, calls: ["session_briefing", "delivery_knowledge_query",
+    "record_delivery_premortem"], instruction: DELIVERY_AGENT_USE_TEXT };
+}
+
+export function recordDeliveryBriefingUse(input) {
+  return recordStage({ ...input, stage: "briefing" });
+}
+
+export function recordDeliveryKnowledgeUse(input) {
+  return recordStage({ ...input, stage: "knowledge" });
+}
+
+export async function verifyDeliveryAgentUse({ root, requirementId }) {
+  try {
+    const current = await currentRequirement(root, requirementId);
+    if (current.status === "degraded" || current.blocked) return current;
+    const paths = await pathsFor(root, requirementId);
+    const state = await readState(paths.path, paths.parsed);
+    if (!state?.briefing) return block("missing-briefing",
+      "AgentSpine delivery preflight is missing stage 1: session_briefing.", { requirementId });
+    if (!state.knowledge) return block("missing-knowledge",
+      "AgentSpine delivery preflight is missing stage 2: delivery_knowledge_query.", { requirementId });
+    if (state.consumedAt) return block("reused",
+      `AgentSpine usage receipts for ${requirementId} were already consumed.`, { requirementId });
+    return { status: "verified", blocked: false, requirementId,
+      briefingReceipt: structuredClone(state.briefing),
+      knowledgeReceipt: structuredClone(state.knowledge),
+      digest: sha256({ briefing: state.briefing.digest, knowledge: state.knowledge.digest }) };
+  } catch (error) {
+    return boundary(error);
+  }
+}
+
+export async function consumeDeliveryAgentUse({ root, requirementId, now = new Date() }) {
+  try {
+    const verified = await verifyDeliveryAgentUse({ root, requirementId });
+    if (verified.blocked || verified.status === "degraded") return verified;
+    const paths = await pathsFor(root, requirementId);
+    return withOwnedFileLock(paths.lockPath, async ({ assertOwned }) => {
+      let state = await readState(paths.path, paths.parsed);
+      if (state.consumedAt) return { status: "duplicate", blocked: false,
+        requirementId, digest: state.consumedDigest };
+      state.consumedAt = at(now);
+      state.consumedDigest = sha256({ requirementId, usageDigest: verified.digest });
+      state.revision += 1;
+      state = sealState(state);
+      await writePremortemFile(paths.path, state, assertOwned, MAX_BYTES);
+      return { status: "consumed", blocked: false, requirementId,
+        digest: state.consumedDigest };
+    });
+  } catch (error) {
+    return boundary(error);
+  }
+}
+
+export async function removeDeliveryAgentUse({ root, requirementId }) {
+  try {
+    const paths = await pathsFor(root, requirementId);
+    return withOwnedFileLock(paths.lockPath, async ({ assertOwned }) => {
+      await assertOwned();
+      await unlink(paths.path).catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+      });
+      return { status: "removed", blocked: false, requirementId };
+    });
+  } catch (error) {
+    return boundary(error);
+  }
+}

package/agent-spine-plugin/src/lib/delivery-assignment.js

@@ -0,0 +1,220 @@
+import { mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { withOwnedFileLock } from "./owned-file-lock.js";
+import { canonicalPath, projectStateDir } from "./paths.js";
+import { writePremortemFile } from "./delivery-premortem-file.js";
+import { inspectPremortemState } from "./delivery-premortem.js";
+import { canonicalPremortem as canonical, premortemSha256 as sha256,
+  premortemTime as at, sealPremortem as seal,
+  validPremortemSeal as validSeal, validPremortemTime as validTime } from "./delivery-premortem-codec.js";
+
+const ASSIGNMENT_SCHEMA = "agentspine.delivery-assignment/v1";
+const POINTER_SCHEMA = "agentspine.delivery-assignment-pointer/v1";
+const AUTHORITY = "context-only";
+const MAX_BYTES = 16 * 1024;
+const ID_RE = /^assignment:[a-f0-9]{64}$/;
+
+function sessionBinding(binding) {
+  return {
+    host: binding.host,
+    sessionId: binding.sessionId,
+    projectId: binding.projectId
+  };
+}
+
+function sessionDigest(binding) {
+  return sha256({ schema: "agentspine.delivery-assignment-session/v1",
+    binding: sessionBinding(binding) });
+}
+
+function eventDigest(binding, eventId) {
+  return sha256({ schema: "agentspine.delivery-assignment-event/v1",
+    binding: sessionBinding(binding), eventId });
+}
+
+function validAssignment(value, expectedSessionDigest = null) {
+  return value && value.schema === ASSIGNMENT_SCHEMA && value.authority === AUTHORITY
+    && ID_RE.test(value.assignmentId || "")
+    && /^[a-f0-9]{64}$/.test(value.sessionDigest || "")
+    && /^[a-f0-9]{64}$/.test(value.eventDigest || "")
+    && (value.predecessorAssignmentId === null || ID_RE.test(value.predecessorAssignmentId || ""))
+    && value.binding && canonical(sessionBinding(value.binding)) === canonical(sessionBinding(value))
+    && (!expectedSessionDigest || value.sessionDigest === expectedSessionDigest)
+    && validTime(value.createdAt) && validSeal(value);
+}
+
+function validPointer(value, digest) {
+  return value && value.schema === POINTER_SCHEMA && value.authority === AUTHORITY
+    && value.sessionDigest === digest && validAssignment(value.assignment, digest)
+    && value.assignmentId === value.assignment.assignmentId
+    && Number.isInteger(value.revision) && value.revision > 0
+    && validTime(value.updatedAt) && validSeal(value);
+}
+
+async function pathsFor(root, binding) {
+  const digest = sessionDigest(binding);
+  const directory = join(await projectStateDir(await canonicalPath(root)),
+    "delivery-assignments", digest);
+  await mkdir(join(directory, "events"), { recursive: true, mode: 0o700 });
+  return { digest, directory, pointer: join(directory, "active.json"),
+    lock: join(directory, "active.lock") };
+}
+
+async function readJson(path, maxBytes = MAX_BYTES) {
+  try {
+    const text = await readFile(path, "utf8");
+    if (Buffer.byteLength(text) > maxBytes) throw new Error("delivery assignment state exceeds 16 KiB");
+    return JSON.parse(text);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    if (error instanceof SyntaxError) throw new Error("delivery assignment state is not valid JSON");
+    throw error;
+  }
+}
+
+async function readPointer(paths) {
+  const value = await readJson(paths.pointer);
+  if (value && !validPointer(value, paths.digest)) {
+    throw new Error("delivery assignment pointer failed integrity validation");
+  }
+  return value;
+}
+
+function assignmentFor(binding, eventId, digest, predecessor, now) {
+  const event = eventDigest(binding, eventId);
+  return seal({ schema: ASSIGNMENT_SCHEMA,
+    assignmentId: `assignment:${sha256({ sessionDigest: digest, eventDigest: event })}`,
+    sessionDigest: digest, eventDigest: event,
+    host: binding.host, sessionId: binding.sessionId, projectId: binding.projectId,
+    binding: { host: binding.host, sessionId: binding.sessionId,
+      projectId: binding.projectId, entityId: binding.entityId || null,
+      groupId: binding.groupId || null, taskId: binding.taskId || null,
+      goalId: binding.goalId || null, goalStepId: binding.goalStepId || null,
+      queueId: binding.queueId || null, gatewayAttempt: binding.gatewayAttempt ?? null,
+      planDefinitionsDigest: binding.planDefinitionsDigest || null },
+    predecessorAssignmentId: predecessor?.assignmentId || null,
+    createdAt: at(now), authority: AUTHORITY });
+}
+
+function pointerFor(paths, assignment, previous, now) {
+  return seal({ schema: POINTER_SCHEMA, sessionDigest: paths.digest,
+    assignmentId: assignment.assignmentId, assignment,
+    revision: (previous?.revision || 0) + 1,
+    updatedAt: at(now), authority: AUTHORITY });
+}
+
+async function publishEvent(path, assignment, assertOwned) {
+  const existing = await readJson(path);
+  if (existing) {
+    if (!validAssignment(existing, assignment.sessionDigest)
+      || existing.assignmentId !== assignment.assignmentId
+      || existing.eventDigest !== assignment.eventDigest) {
+      throw new Error("delivery assignment event conflicts with stored history");
+    }
+    return existing;
+  }
+  await writePremortemFile(path, assignment, assertOwned, MAX_BYTES);
+  return assignment;
+}
+
+export async function beginDeliveryAssignment({ root, binding, eventId, now = new Date() }) {
+  if (typeof eventId !== "string" || !eventId || eventId.length > 512 || /[\0\r\n]/.test(eventId)) {
+    throw new Error("delivery assignment requires an exact prompt eventId");
+  }
+  const paths = await pathsFor(root, binding);
+  return withOwnedFileLock(paths.lock, async ({ assertOwned }) => {
+    const previous = await readPointer(paths);
+    const proposed = assignmentFor(binding, eventId, paths.digest, previous?.assignment || null, now);
+    const path = join(paths.directory, "events", `${proposed.eventDigest}.json`);
+    const assignment = await publishEvent(path, proposed, assertOwned);
+    if (previous?.assignmentId === assignment.assignmentId) {
+      return { status: "duplicate", blocked: false, assignmentId: assignment.assignmentId,
+        assignment: structuredClone(assignment) };
+    }
+    if (assignment.predecessorAssignmentId !== (previous?.assignmentId || null)) {
+      return { status: "stale-assignment", blocked: true,
+        reason: "A replayed prompt cannot replace the current delivery assignment." };
+    }
+    await writePremortemFile(paths.pointer, pointerFor(paths, assignment, previous, now),
+      assertOwned, MAX_BYTES);
+    return { status: "started", blocked: false, assignmentId: assignment.assignmentId,
+      assignment: structuredClone(assignment) };
+  });
+}
+
+export async function resolveDeliveryAssignment({ root, binding, assignmentId = null }) {
+  const paths = await pathsFor(root, binding);
+  const pointer = await readPointer(paths);
+  if (!pointer) return { status: "legacy", blocked: false, assignmentId: null, assignment: null };
+  if (assignmentId && assignmentId !== pointer.assignmentId) {
+    return { status: "foreign-assignment", blocked: true,
+      reason: "The supplied delivery assignment is not active for this exact session and project." };
+  }
+  const stored = pointer.assignment.binding;
+  for (const key of ["entityId", "groupId", "taskId"]) {
+    if (stored[key] && binding[key] && stored[key] !== binding[key]) {
+      return { status: "foreign-assignment", blocked: true,
+        reason: `The active delivery assignment is bound to a different ${key}.` };
+    }
+  }
+  return { status: "resolved", blocked: false, assignmentId: pointer.assignmentId,
+    assignment: structuredClone(pointer.assignment) };
+}
+
+export async function continueDeliveryAssignment({ root, binding, assignmentId }) {
+  if (!ID_RE.test(assignmentId || "")) {
+    return { status: "foreign-assignment", blocked: true,
+      reason: "Continuation requires the exact active assignmentId returned by this host session." };
+  }
+  const paths = await pathsFor(root, binding);
+  // Serialize the check with new assignments. Continuation never advances the pointer
+  // or rewrites history, including when a process exits during this inspection.
+  return withOwnedFileLock(paths.lock, async () => {
+    const current = await resolveDeliveryAssignment({ root, binding, assignmentId });
+    if (current.blocked) return current;
+    if (!current.assignment) return { status: "foreign-assignment", blocked: true,
+      reason: "This session has no active assignment matching the continuation." };
+    for (const key of ["entityId", "groupId", "taskId", "goalId", "goalStepId", "queueId",
+      "gatewayAttempt", "planDefinitionsDigest"]) {
+      if ((current.assignment.binding[key] || null) !== (binding[key] || null)) {
+        return { status: "foreign-assignment", blocked: true,
+          reason: `Continuation requires the same explicit ${key} binding, including absence.` };
+      }
+    }
+    const exact = assignmentPremortemBinding(binding, current);
+    const inspected = await inspectPremortemState({ root, binding: exact });
+    if (inspected.blocked || inspected.status === "degraded") return inspected;
+    if (!inspected.requirement) return { status: "missing", blocked: true,
+      reason: "The exact continuation scope has no existing premortem requirement." };
+    if (inspected.closed || inspected.consumed) return { status: "finalized", blocked: true,
+      reason: "A completed assignment cannot be continued; a new delivery needs fresh preflight calls." };
+    if (inspected.conflicted) return { status: "conflict", blocked: true,
+      requirementId: inspected.requirementId,
+      reason: "Continuation cannot repair a conflicted registration or bypass its recovery checks." };
+    return { ...current, status: "continued", requirement: inspected.requirement,
+      requirementId: inspected.requirementId, binding: exact };
+  });
+}
+
+export async function withActiveDeliveryAssignment({ root, binding }, action) {
+  const paths = await pathsFor(root, binding);
+  return withOwnedFileLock(paths.lock, async ({ assertOwned }) => {
+    const current = await resolveDeliveryAssignment({ root, binding,
+      assignmentId: binding.assignmentId });
+    if (current.blocked) return current;
+    if (!current.assignment || current.assignmentId !== binding.assignmentId) {
+      return { status: "foreign-assignment", blocked: true,
+        reason: "Completion requires the active assignment for this session and project." };
+    }
+    const result = await action(assertOwned);
+    await assertOwned();
+    return result;
+  });
+}
+
+export function assignmentPremortemBinding(binding, result) {
+  if (binding.goalId || binding.queueId) return { ...binding, assignmentId: null };
+  if (!result?.assignment) return { ...binding, assignmentId: null };
+  return { ...binding, ...result.assignment.binding,
+    assignmentId: result.assignment.assignmentId };
+}