nexakit 0.0.0-stage → 0.2.0

package/src/client-runtime-state.js

@@ -0,0 +1,67 @@
+import { createClientRuntimeAdmission } from "./client-runtime-admission.js";
+import { validators, copyInertJson, ParseFailure, fail, hash, same, fresh, ledgerFacts, recalculate } from "./client-runtime-core.js";
+
+/** Calculate CAS proposals only. No mutable store, locks, clock or processes. */
+export function createClientRuntimeState(base, preference, adapter, runtime) {
+  const validate = validators(base, preference, adapter, runtime);
+  const admit = createClientRuntimeAdmission(base, preference, adapter, runtime);
+  return function transition(input) {
+    const r = { schemaVersion: "1.0.0", engineVersion: "1.0.0", state: "invalid", executed: false, runtimeReady: false,
+      verifiedAdmission: false, persisted: false, operation: null, nextLedger: null, compareAndSwap: null, reasons: [] };
+    function finish(state, code) {
+      r.state = state; r.reasons = [code];
+      if (state !== "proposed") { r.nextLedger = null; r.compareAndSwap = null; }
+      if (!validate.stateReport(r)) throw Error("Runtime state invariant failed"); return r;
+    }
+    try {
+      const d = copyInertJson(input); if (!validate.stateInput(d)) fail("invalid-runtime-transition");
+      r.operation = d.operation; const beforeHash = hash(d.ledger);
+      if (d.expectedRevision !== d.ledger.revision || d.expectedLedgerSha256 !== beforeHash) return finish("blocked", "runtime-snapshot-conflict");
+      ledgerFacts(d.ledger, d.now);
+      if (d.ledger.revision >= 1_000_000) return finish("blocked", "runtime-revision-limit");
+      const next = copyInertJson(d.ledger); let a = next.attempts.find(a => a.attemptId === d.attemptId);
+      if (d.operation === "reserve") {
+        if (a) return finish("blocked", "runtime-attempt-already-exists");
+        if (!same(d.admissionInput.ledger, d.ledger) || d.admissionInput.now !== d.now) return finish("blocked", "runtime-admission-snapshot-conflict");
+        const admission = admit(d.admissionInput);
+        if (admission.state !== "eligible-for-reservation") return finish(admission.state === "invalid" ? "invalid" : "blocked", "runtime-reservation-not-eligible");
+        const v = admission.reservation;
+        a = { attemptId: d.attemptId, identity: v.identity, planSha256: v.planSha256, client: v.client,
+          profileId: v.profileId, model: v.model, effort: v.effort, state: "reserved", startObservation: "not-reported",
+          reservedCalls: v.calls, reservedSeconds: v.seconds, reservedAt: d.now, updatedAt: d.now,
+          actualCalls: null, actualSeconds: null, outcome: null, evidenceRef: null };
+        next.attempts.push(a);
+      } else {
+        if (!a) return finish("blocked", "runtime-attempt-not-found");
+        if (a.state === "settled") return finish("blocked", "runtime-attempt-already-settled");
+        if (Date.parse(d.now) < Date.parse(a.updatedAt)) return finish("blocked", "runtime-observation-before-attempt");
+        if (d.operation === "mark-started") {
+          if (a.state !== "reserved") return finish("blocked", "runtime-start-observation-conflict");
+          a.state = "started"; a.startObservation = "started";
+        } else if (d.operation === "interrupt") {
+          if (a.state === "reconciliation-required") return finish("blocked", "runtime-attempt-already-interrupted");
+          a.state = "reconciliation-required"; a.startObservation = a.startObservation === "started" ? "started" : "unknown"; a.outcome = "indeterminate";
+        } else {
+          if (d.reconciliation.status !== "approved" || d.reconciliation.revoked || !fresh(d.reconciliation, d.now, 3600) || !d.terminationConfirmed) return finish("blocked", "runtime-reconciliation-not-authorized-or-terminated");
+          if (d.reconciliation.projectId !== next.projectId || d.reconciliation.taskId !== next.taskId ||
+              d.reconciliation.attemptId !== a.attemptId || d.reconciliation.ledgerSha256 !== beforeHash) return finish("blocked", "runtime-reconciliation-binding-mismatch");
+          if (a.startObservation === "started" && d.startObservation !== "started") return finish("blocked", "runtime-start-observation-conflict");
+          if (d.startObservation === "not-started" && (d.actualCalls || d.actualSeconds || d.outcome !== "not-started")) return finish("blocked", "runtime-not-started-consumption-conflict");
+          if (d.startObservation === "started" && d.outcome === "not-started") return finish("blocked", "runtime-started-outcome-conflict");
+          Object.assign(a, { state: "settled", startObservation: d.startObservation, actualCalls: d.actualCalls,
+            actualSeconds: d.actualSeconds, outcome: d.outcome, evidenceRef: d.reconciliation.evidenceRef });
+        }
+        a.updatedAt = d.now;
+      }
+      next.revision++; recalculate(next);
+      if (!validate.ledger(next)) return finish("blocked", "runtime-ledger-counter-or-capacity-limit");
+      ledgerFacts(next, d.now);
+      r.nextLedger = next; r.compareAndSwap = { expectedRevision: d.expectedRevision, nextRevision: next.revision,
+        expectedSha256: beforeHash, nextSha256: hash(next) };
+      return finish("proposed", next.status === "reconciliation-required" ? "declared-transition-reconciliation-required" : "declared-transition-only");
+    } catch (error) {
+      if (!(error instanceof ParseFailure)) throw error;
+      return finish("invalid", error.code);
+    }
+  };
+}

package/src/client-runtime-store-files.js

@@ -0,0 +1,91 @@
+import fs from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { ParseFailure, fail } from "./client-output-json.js";
+
+export const FILE_LIMIT = 1024 * 1024;
+export const bytesHash = bytes => createHash("sha256").update(bytes).digest("hex");
+const missing = e => e?.code === "ENOENT";
+export { missing };
+
+// Local cooperative writers only. These checks are not openat-style containment.
+export function createStoreFiles(overrides = {}) {
+  const io = { ...fs, ...overrides };
+  const uid = process.getuid?.() ?? null;
+  // Directory link counts change when our own task directory is created.
+  // File link count is independently required to remain one by privateType.
+  const identity = s => ({ dev: s.dev, ino: s.ino, uid: s.uid, mode: s.mode });
+  const equal = (a, b) => JSON.stringify(identity(a)) === JSON.stringify(identity(b));
+  function privateType(s, directory) {
+    if (s.uid !== uid || (s.mode & 0o7777) !== (directory ? 0o700 : 0o600) ||
+      (directory ? !s.isDirectory() : !s.isFile() || s.nlink !== 1)) fail("store-unsafe-resource");
+  }
+  async function physical(full) {
+    let current = path.parse(full).root;
+    for (const part of full.slice(current.length).split(path.sep).filter(Boolean)) {
+      current = path.join(current, part); const s = await io.lstat(current);
+      if (s.isSymbolicLink()) fail("store-symlink-path");
+      if (current !== full && !s.isDirectory()) fail("store-invalid-parent");
+    }
+  }
+  async function directory(full, expected) {
+    await physical(full); const s = await io.lstat(full); privateType(s, true);
+    if (expected && !equal(s, expected)) fail("store-directory-replaced");
+    return s;
+  }
+  async function syncDirectory(full, expected) {
+    await directory(full, expected);
+    const h = await io.open(full, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    try { const s = await h.stat(); privateType(s, true); if (!equal(s, expected)) fail("store-directory-replaced"); await h.sync(); }
+    finally { await h.close(); }
+    await directory(full, expected);
+  }
+  async function read(full, limit = FILE_LIMIT) {
+    await physical(full); const before = await io.lstat(full); privateType(before, false);
+    if (before.size > limit) fail("store-file-limit");
+    const h = await io.open(full, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const opened = await h.stat(); privateType(opened, false);
+      if (!equal(before, opened) || opened.size > limit) fail("store-resource-changed");
+      const buffer = Buffer.alloc(limit + 1); let offset = 0;
+      while (offset < buffer.length) { const { bytesRead } = await h.read(buffer, offset, buffer.length - offset, offset); if (!bytesRead) break; offset += bytesRead; }
+      if (offset > limit) fail("store-file-limit");
+      const after = await h.stat(); const named = await io.lstat(full);
+      privateType(after, false); privateType(named, false);
+      if (!equal(opened, after) || !equal(after, named) || after.size !== offset || opened.size !== after.size || opened.mtimeMs !== after.mtimeMs) fail("store-resource-changed");
+      return { bytes: buffer.subarray(0, offset), stat: after };
+    } finally { await h.close(); }
+  }
+  async function exclusive(full) {
+    let h;
+    try { h = await io.open(full, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
+    catch (e) { if (e?.code === "EEXIST") fail("store-resource-exists"); throw e; }
+    try { const stat = await h.stat(); privateType(stat, false); return { handle: h, stat, full, digest: null }; }
+    catch { await h.close(); fail("store-created-resource-unusable"); }
+  }
+  async function write(resource, bytes) {
+    let offset = 0;
+    while (offset < bytes.length) {
+      const { bytesWritten } = await resource.handle.write(bytes, offset, bytes.length - offset, offset);
+      if (!bytesWritten) fail("store-short-write"); offset += bytesWritten;
+    }
+    resource.digest = bytesHash(bytes); await resource.handle.sync();
+  }
+  async function owned(resource) {
+    const r = await read(resource.full); if (!equal(r.stat, resource.stat)) fail("store-resource-replaced");
+    if (resource.digest !== null && bytesHash(r.bytes) !== resource.digest) fail("store-resource-replaced");
+    return r;
+  }
+  async function remove(resource, dir, expected) {
+    await directory(dir, expected); await owned(resource); await io.unlink(resource.full);
+  }
+  async function contents(dir, allowed) {
+    const h = await io.opendir(dir);
+    try { let n = 0; for (;;) { const e = await h.read(); if (!e) break; if (++n > allowed.length || !allowed.includes(e.name)) fail("store-residual-resource"); } }
+    finally { await h.close(); }
+  }
+  return { io, uid, equal, physical, directory, syncDirectory, read, exclusive, write, owned, remove, contents,
+    async exists(full) { try { return await io.lstat(full); } catch (e) { if (missing(e)) return null; throw e; } },
+    code(e) { return e instanceof ParseFailure ? e.code : "store-io-failed"; } };
+}

package/src/client-runtime-store.js

@@ -0,0 +1,239 @@
+import path from "node:path";
+import { supportsLocalPosix } from "./client-local-platform.js";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+import Ajv2020 from "ajv/dist/2020.js";
+import { constants } from "node:fs";
+import { createClientRuntimeState } from "./client-runtime-state.js";
+import { copyInertJson, ParseFailure, fail, canonical, hash, same, fresh, ledgerFacts } from "./client-runtime-core.js";
+import { decode, parseEventJson } from "./client-output-json.js";
+import { createStoreFiles, bytesHash, FILE_LIMIT, missing } from "./client-runtime-store-files.js";
+import { createFixturePermit, revokeFixturePermit } from "./client-runtime-fixture-permit.js";
+
+export const LOCAL_STORE_ID = "https://agent-toolkit.local/schemas/agent-client-runtime-local.schema.json";
+const toolkit = fileURLToPath(new URL("../", import.meta.url)).replace(/\/$/, "");
+const contained = (child, parent) => child === parent || child.startsWith(parent + path.sep);
+const validPath = p => path.isAbsolute(p) && path.normalize(p) === p && !p.includes("\0");
+const utc = value => {
+  const t = Date.parse(value);
+  return typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/.test(value) && Number.isFinite(t) && new Date(t).toISOString() === value.replace(/Z$/, ".000Z");
+};
+
+/** Trusted factory configuration/dependencies, inert JSON operations. No client launcher. */
+export function createClientRuntimeStore(base, preference, adapter, runtime, local, configuration, dependencies = {}) {
+  const schemas = [base, preference, adapter, runtime, local].map(copyInertJson);
+  if (schemas[4].$id !== LOCAL_STORE_ID) throw Error("Unsupported local runtime schema");
+  const ajv = new Ajv2020({ strict: true, allErrors: true }); ajv.addFormat("date-time", { type: "string", validate: utc });
+  schemas.forEach(s => ajv.addSchema(s));
+  const check = Object.fromEntries(["configuration", "request", "document", "report"].map(n => [n, ajv.compile({ $ref: `${LOCAL_STORE_ID}#/$defs/${n}` })]));
+  const cfg = copyInertJson(configuration); if (!check.configuration(cfg)) throw Error("Invalid local runtime configuration");
+  const transition = createClientRuntimeState(...schemas.slice(0, 4));
+  const files = createStoreFiles(dependencies.io); const clock = dependencies.clock ?? Date.now;
+  const checkpoint = dependencies.checkpoint ?? (() => {});
+
+  async function execute(input, sessionConsumer, sessionGate) {
+    const r = { schemaVersion: "1.0.0", engineVersion: "1.0.0", scope: "cooperative-local-data-only", state: "blocked",
+      executed: false, nativeExecuted: false, runtimeReady: false, verifiedAdmission: false, writeObservation: "unchanged",
+      durability: "unconfirmed", cleanup: "complete", identity: null, snapshot: null, snapshotSha256: null, reasons: [] };
+    let root, rootStat, dir, dirStat, lock, temp, before = null, after = null, target, publishing = false, published = false;
+    let keep = false;
+    const sessionResources = [];
+    const phase = name => checkpoint(name);
+    function now() { const ms = clock(); if (typeof ms !== "number" || !Number.isFinite(ms)) fail("store-clock-unavailable"); const date = new Date(ms); if (!Number.isFinite(date.getTime())) fail("store-clock-unavailable"); return date.toISOString().replace(/\.\d{3}Z$/, "Z"); }
+    const document = ledger => ({ storageVersion: "1.0.0", identity: r.identity, ledgerSha256: hash(ledger), ledger });
+    function inspect(bytes, time) {
+      const d = copyInertJson(parseEventJson(decode(bytes)));
+      if (!check.document(d) || !same(d.identity, r.identity) || !same({ projectId: d.ledger.projectId, taskId: d.ledger.taskId }, r.identity) || d.ledgerSha256 !== hash(d.ledger)) fail("store-invalid-document");
+      ledgerFacts(d.ledger, time); return d;
+    }
+    async function roots() {
+      if (!validPath(cfg.root) || cfg.root === path.parse(cfg.root).root || !cfg.forbiddenRoots.every(validPath)) fail("store-invalid-root");
+      await files.physical(cfg.root); root = await files.io.realpath(cfg.root); rootStat = await files.directory(root);
+      const forbidden = [toolkit, ...cfg.forbiddenRoots];
+      for (const p of forbidden) {
+        let resolved = p; try { resolved = await files.io.realpath(p); } catch (e) { if (!missing(e)) throw e; }
+        if (contained(root, resolved) || contained(resolved, root)) fail("store-forbidden-root");
+      }
+      // Refuse roots within an existing repository or Obsidian vault without invoking Git.
+      for (let p = root; p !== path.parse(p).root; p = path.dirname(p)) {
+        if (await files.exists(path.join(p, ".git")) || await files.exists(path.join(p, ".obsidian"))) fail("store-forbidden-root");
+      }
+    }
+    function permission(d, time) {
+      const a = d.authorization;
+      if (a.status !== "approved" || a.revoked || !a.operations.includes(d.operation) || !fresh(a, time, 3600) ||
+        !same(a.identity, d.identity) || a.rootSha256 !== hash(root)) fail("store-not-authorized");
+    }
+    async function fence() {
+      await files.directory(root, rootStat); await files.directory(dir, dirStat); await files.owned(lock);
+    }
+    async function current(time) { const read = await files.read(target); return { ...read, data: inspect(read.bytes, time) }; }
+    async function unchanged(time) {
+      if (before === null) { if (await files.exists(target)) fail("store-snapshot-conflict"); }
+      else { const read = await current(time); if (!files.equal(before.stat, read.stat) || bytesHash(before.bytes) !== bytesHash(read.bytes)) fail("store-snapshot-conflict"); }
+    }
+    try {
+      const d = copyInertJson(input); if (!check.request(d)) fail("store-invalid-request"); r.identity = d.identity;
+      if (!supportsLocalPosix(process.platform) || cfg.evaluation.platform !== process.platform || cfg.evaluation.nodeVersion !== process.version ||
+        !constants.O_NOFOLLOW || !constants.O_DIRECTORY) fail("store-platform-not-evaluated");
+      let time = now(); await roots(); permission(d, time);
+      if (d.operation === "initialize") {
+        const imported = inspect(Buffer.from(canonical(document(d.ledger))), time);
+        const facts = ledgerFacts(imported.ledger, time);
+        if (d.importReferenceId !== imported.ledger.importEvidenceRef || imported.ledger.status !== "reconciled" || facts.active || facts.uncertain || facts.overrun) fail("store-import-not-reconciled");
+      } else if (d.operation === "apply" && !same({ projectId: d.transition.ledger.projectId, taskId: d.transition.ledger.taskId }, d.identity)) fail("store-transition-identity-mismatch");
+      dir = path.join(root, hash(d.identity)); target = path.join(dir, "ledger.json");
+      if (d.operation === "initialize") {
+        try { await files.io.mkdir(dir, { mode: 0o700 }); await files.syncDirectory(root, rootStat); }
+        catch (e) { if (e?.code !== "EEXIST") throw e; }
+      }
+      try { dirStat = await files.directory(dir); } catch (e) { if (missing(e)) fail("store-ledger-missing"); throw e; }
+      await files.contents(dir, ["ledger.json", "write.lock"]);
+      try { lock = await files.exclusive(path.join(dir, "write.lock")); }
+      catch (e) { if (e instanceof ParseFailure && e.code === "store-resource-exists") fail("store-locked"); throw e; }
+      await phase("lock-created"); await files.write(lock, Buffer.from(canonical({ protocolVersion: "1.0.0", ownerId: randomUUID() }) + "\n"));
+      await files.syncDirectory(dir, dirStat); await phase("lock-durable");
+      await fence(); time = now(); permission(d, time);
+      if (await files.exists(target)) before = await current(time);
+      await phase("snapshot-read");
+      if (d.operation === "initialize") {
+        if (before !== null) fail("store-already-initialized"); after = document(d.ledger);
+      } else {
+        if (before === null) fail("store-ledger-missing");
+        if (d.operation === "read") { r.state = "unchanged"; r.snapshot = before.data.ledger; r.snapshotSha256 = before.data.ledgerSha256; r.reasons = ["store-snapshot-read"]; }
+        else {
+          const t = copyInertJson(d.transition);
+          if (!same(t.ledger, before.data.ledger) || t.expectedRevision !== before.data.ledger.revision || t.expectedLedgerSha256 !== before.data.ledgerSha256) fail("store-snapshot-conflict");
+          t.now = time;
+          if (t.operation === "reserve") { t.admissionInput.now = time; t.admissionInput.ledger = copyInertJson(before.data.ledger); }
+          const proposal = transition(t); if (proposal.state !== "proposed") fail("store-transition-blocked");
+          after = document(proposal.nextLedger);
+        }
+      }
+      if (after) {
+        const bytes = Buffer.from(canonical(after) + "\n"); if (bytes.length > FILE_LIMIT) fail("store-file-limit");
+        inspect(bytes, time);
+        temp = await files.exclusive(path.join(dir, `.ledger-${randomUUID()}.tmp`)); await phase("temp-created");
+        await files.write(temp, bytes); await phase("temp-synced");
+        const readback = await files.owned(temp); if (!same(inspect(readback.bytes, time), after)) fail("store-invalid-temporary");
+        await phase("before-publish"); time = now(); permission(d, time);
+        // Recheck temporal admission at publication, without refreshing evidence stamps.
+        if (d.operation === "apply") {
+          const t = copyInertJson(d.transition); t.now = time;
+          if (t.operation === "reserve") t.admissionInput.now = time;
+          const again = transition(t); if (again.state !== "proposed") fail("store-transition-blocked");
+          if (!same(again.nextLedger, after.ledger)) {
+            // Time-sensitive proposals must be regenerated, not silently installed stale.
+            fail("store-publication-time-changed");
+          }
+        } else inspect(bytes, time);
+        await fence(); await files.owned(temp); await unchanged(time);
+        publishing = true; await files.io.rename(temp.full, target); published = true; r.writeObservation = "replaced";
+        await phase("published"); await files.syncDirectory(dir, dirStat); r.durability = "confirmed";
+        await phase("directory-synced"); await fence(); const final = await current(now());
+        if (!same(final.data, after) || bytesHash(final.bytes) !== temp.digest) fail("store-publication-mismatch");
+        await phase("confirmed"); r.state = "committed"; r.snapshot = final.data.ledger; r.snapshotSha256 = final.data.ledgerSha256; r.reasons = ["store-transition-committed"];
+        if (sessionConsumer) {
+          // Internal session: lock remains held. A public committed JSON cannot enter here.
+          let active = true;
+          const pending = new Set();
+          const attemptId = d.transition.attemptId;
+          const getSnapshot = () => copyInertJson(r.snapshot);
+          const guard = async () => {
+            if (!active) fail("store-session-closed");
+            const time = now(); permission(d, time); await sessionGate(time);
+            await fence(); const observed = await current(time);
+            if (!same(observed.data.ledger, r.snapshot)) fail("store-snapshot-conflict");
+          };
+          const performSession = async value => {
+            await guard();
+            const t = copyInertJson(value);
+            if (!["mark-started", "interrupt", "settle"].includes(t.operation) || t.attemptId !== attemptId ||
+                !check.request({ ...d, transition: t }) || !same(t.ledger, r.snapshot) ||
+                t.expectedRevision !== r.snapshot.revision || t.expectedLedgerSha256 !== hash(r.snapshot)) fail("store-session-transition-invalid");
+            let time = now(); t.now = time;
+            const proposed = transition(t); if (proposed.state !== "proposed") fail("store-transition-blocked");
+            const previous = await current(time); after = document(proposed.nextLedger);
+            const bytes = Buffer.from(canonical(after) + "\n"); if (bytes.length > FILE_LIMIT) fail("store-file-limit"); inspect(bytes, time);
+            const next = await files.exclusive(path.join(dir, `.ledger-${randomUUID()}.tmp`)); sessionResources.push(next);
+            await files.write(next, bytes); await phase(`session-${t.operation}-before-publish`);
+            const readback = await files.owned(next); if (!same(inspect(readback.bytes, time), after)) fail("store-invalid-temporary");
+            time = now(); t.now = time; await guard();
+            const checked = transition(t);
+            if (checked.state !== "proposed" || !same(checked.nextLedger, after.ledger)) fail("store-publication-time-changed");
+            const old = await current(time);
+            if (!files.equal(previous.stat, old.stat) || bytesHash(previous.bytes) !== bytesHash(old.bytes)) fail("store-snapshot-conflict");
+            await files.owned(next); r.durability = "unconfirmed";
+            await files.io.rename(next.full, target); await phase(`session-${t.operation}-published`);
+            await files.syncDirectory(dir, dirStat); r.durability = "confirmed"; await fence();
+            const confirmed = await current(now());
+            if (!same(confirmed.data, after) || bytesHash(confirmed.bytes) !== next.digest) fail("store-publication-mismatch");
+            r.snapshot = confirmed.data.ledger; r.snapshotSha256 = confirmed.data.ledgerSha256;
+            await phase(`session-${t.operation}-confirmed`);
+            return getSnapshot();
+          };
+          const applySession = value => {
+            const operation = performSession(value); pending.add(operation);
+            operation.then(() => pending.delete(operation), () => pending.delete(operation));
+            return operation;
+          };
+          const bindingSha256 = await sessionGate(now());
+          const handle = createFixturePermit(async () => {
+            await guard();
+            if (r.snapshot.attempts.find(a => a.attemptId === attemptId)?.state !== "reserved") fail("store-session-not-reserved");
+          }, () => applySession({ schemaVersion: "1.0.0", operation: "mark-started", now: now(), ledger: getSnapshot(),
+            expectedRevision: r.snapshot.revision, expectedLedgerSha256: r.snapshotSha256, attemptId }), bindingSha256);
+          try {
+            await phase("session-reserved");
+            await sessionConsumer(Object.freeze({ handle, snapshot: getSnapshot, apply: applySession }));
+            if (r.snapshot.attempts.find(a => a.attemptId === attemptId)?.state !== "settled") fail("store-session-reconciliation-required");
+            await guard();
+          } finally {
+            active = false; revokeFixturePermit(handle);
+            // Do not close descriptors or return while a started-observation write is still in flight.
+            await Promise.allSettled([...pending]);
+          }
+        }
+      }
+    } catch (e) {
+      const primary = files.code(e); r.reasons = [primary]; r.state = "blocked"; r.snapshot = null; r.snapshotSha256 = null;
+      if (primary === "store-created-resource-unusable") { r.state = "indeterminate"; r.cleanup = "intervention-required"; }
+      if (publishing) {
+        keep = true; r.state = "indeterminate";
+        try {
+          const observed = await current(now());
+          if (after && same(observed.data, after)) { published = true; r.writeObservation = "replaced"; }
+          else if (before && bytesHash(observed.bytes) === bytesHash(before.bytes)) r.writeObservation = "unchanged";
+          else r.writeObservation = "unknown";
+        } catch { r.writeObservation = "unknown"; }
+      }
+    } finally {
+      try {
+        if (lock) {
+          await phase("before-cleanup");
+          await files.directory(root, rootStat); await files.directory(dir, dirStat);
+          if (!keep) {
+            if (temp && !published) await files.remove(temp, dir, dirStat);
+            await files.remove(lock, dir, dirStat); await files.syncDirectory(dir, dirStat);
+            await phase("after-cleanup");
+          } else r.cleanup = "intervention-required";
+        }
+      } catch { r.cleanup = "intervention-required"; r.state = "indeterminate"; r.reasons.push("store-cleanup-required"); r.snapshot = null; r.snapshotSha256 = null; }
+      for (const resource of [...sessionResources, temp, lock]) if (resource) {
+        try { await resource.handle.close(); } catch { r.cleanup = "intervention-required"; r.state = "indeterminate"; r.reasons.push("store-close-unconfirmed"); }
+      }
+    }
+    if (r.state === "indeterminate" || r.state === "blocked") { r.snapshot = null; r.snapshotSha256 = null; }
+    r.reasons = [...new Set(r.reasons)];
+    if (!check.report(r)) throw Error("Local runtime store invariant failed");
+    return r;
+  }
+  const store = input => execute(input, null, null);
+  // Trusted C2.2 coordinator only. JSON operation API and all C2.1 reports stay unchanged.
+  store.withFixtureSession = async (input, consumer, gate) => {
+    const d = copyInertJson(input);
+    if (d?.operation !== "apply" || d?.transition?.operation !== "reserve" || typeof consumer !== "function" || typeof gate !== "function") throw Error("Invalid trusted fixture session");
+    return execute(d, consumer, gate);
+  };
+  return store;
+}

package/src/client-runtime-supervisor.js

@@ -0,0 +1,146 @@
+import { supportsLocalPosix } from "./client-local-platform.js";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn as nativeSpawn } from "node:child_process";
+import { claimFixturePermit } from "./client-runtime-fixture-permit.js";
+import { createFixtureProtocol } from "./client-runtime-fixture-protocol.js";
+import { copyBytes, ParseFailure } from "./client-output-json.js";
+import { copyInertJson, hash } from "./client-runtime-core.js";
+
+export const FIXTURES = Object.freeze(["success", "split-utf8", "silent", "blocked-stdin", "failure", "stdout-overflow", "stderr-overflow", "long-line", "event-overflow", "invalid-utf8", "forbidden-event", "duplicate-json", "after-terminal", "unterminated", "incomplete", "ignore-term", "parent-child", "child-after-parent", "stderr-invalid", "environment", "closed-stdin"]);
+const script = fileURLToPath(new URL("./runtime-fixtures/runtime-supervisor/fixture.cjs", import.meta.url));
+export const monotonicMs = () => Number(process.hrtime.bigint() / 1_000_000n);
+const reason = e => e instanceof ParseFailure ? e.code : "fixture-local-error";
+
+/** Trusted fixtures only. Internal dependencies cannot arrive in request JSON. */
+export async function superviseFixture(handle, request, { signal, beganAt, checkpoint = () => {}, spawn = nativeSpawn,
+  kill = process.kill.bind(process), monotonic = monotonicMs } = {}) {
+  const r = { scope: "fixture-only", state: "not-started", fixtureExecuted: false, spawnAttempts: 0,
+    nativeExecuted: false, runtimeReady: false, verifiedAdmission: false, modelCalls: 0,
+    started: false, exitObserved: false, pipesClosed: false, groupObservation: "not-started",
+    terminationConfirmed: false, stdoutBytes: 0, stderrBytes: 0, events: 0, elapsedMs: 0, reasons: [] };
+  const start = beganAt ?? monotonic(); let l;
+  let cwd, owned, capability, spawnReturned = false;
+  try {
+    request = copyInertJson(request); l = request.limits;
+    if (!supportsLocalPosix(process.platform) || !FIXTURES.includes(request.fixtureId)) throw Error("fixture-not-admitted");
+    const input = copyBytes(request.inputText, l.maxInputBytes);
+    if (signal?.aborted) { r.reasons = ["fixture-canceled-before-start"]; r.terminationConfirmed = true; return r; }
+    cwd = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "agent-fixture-work-")));
+    await fs.chmod(cwd, 0o700); owned = await fs.lstat(cwd);
+    // Fixed packaged program and Node executable; never a path or recipe from JSON.
+    const source = await fs.lstat(script);
+    if (!source.isFile() || source.isSymbolicLink() || (source.mode & 0o022)) throw Error("fixture-source-unsafe");
+    if (monotonic() - start >= l.timeoutMs - l.graceMs - l.confirmationMs) throw Error("fixture-deadline-before-start");
+    await checkpoint("fixture-before-claim"); capability = await claimFixturePermit(handle, hash(request));
+    if (signal?.aborted || monotonic() - start >= l.timeoutMs - l.graceMs - l.confirmationMs) throw Error("fixture-stopped-before-start");
+    r.spawnAttempts = 1;
+    const child = spawn(process.execPath, [script, request.fixtureId], {
+      shell: false, detached: true, cwd, env: { LANG: "C", LC_ALL: "C" }, stdio: ["pipe", "pipe", "pipe"]
+    });
+    spawnReturned = true;
+    // No awaits between spawn and registration of all lifecycle/error handlers.
+    await new Promise(resolve => {
+      const protocol = createFixtureProtocol(l); const stderrDecoder = new TextDecoder("utf-8", { fatal: true });
+      let done = false, canceled = false, cancelAt = null, forced = false, terminalFailure = false;
+      let groupGone = false, spawnFailed = false, spawned = false, recordPending = false, recordFailed = false;
+      let stdinClosed = false, stdoutClosed = false, stderrClosed = false, closeObserved = false, exitCode = null;
+      let timer, hardTimer;
+      const add = code => { if (!r.reasons.includes(code)) r.reasons.push(code); };
+      const elapsed = () => Math.max(0, monotonic() - start);
+      const observeGroup = () => {
+        if (groupGone || spawnFailed) return false;
+        if (!spawned) return true;
+        try { kill(-child.pid, 0); return true; }
+        catch (e) { if (e?.code === "ESRCH") { groupGone = true; return false; } add("fixture-group-unconfirmed"); return true; }
+      };
+      const send = sig => {
+        if (!spawned || groupGone) return;
+        try { kill(-child.pid, sig); }
+        catch (e) { if (e?.code === "ESRCH") groupGone = true; else add("fixture-signal-unconfirmed"); }
+      };
+      const cancel = (code, state = "failed") => {
+        if (done) return;
+        add(code);
+        if (done || canceled) return;
+        canceled = true; terminalFailure = true; cancelAt = monotonic(); r.state = state;
+        child.stdin.destroy(); send("SIGTERM");
+      };
+      const finalize = uncertain => {
+        if (done) return; done = true; clearInterval(timer); clearTimeout(hardTimer); signal?.removeEventListener("abort", abort);
+        const counts = protocol.counts(); Object.assign(r, { stdoutBytes: counts.stdoutBytes, events: counts.events,
+          pipesClosed: stdinClosed && stdoutClosed && stderrClosed && closeObserved, elapsedMs: elapsed() });
+        r.groupObservation = spawnFailed ? "not-started" : groupGone ? "absent" : "unconfirmed";
+        // Process termination and uncertainty of storage/elapsed time are separate observations.
+        r.terminationConfirmed = spawnFailed || r.exitObserved && r.pipesClosed && groupGone;
+        if (uncertain || recordFailed || r.elapsedMs > l.timeoutMs) { r.state = "indeterminate"; add("fixture-reconciliation-required"); }
+        else if (spawnFailed) r.state = "not-started";
+        else if (!terminalFailure) r.state = "completed";
+        if (!r.reasons.length) add("fixture-completed");
+        // Never retain or print raw child data. Stop reads if closure is uncertain.
+        child.stdin.destroy(); child.stdout.destroy(); child.stderr.destroy(); resolve();
+      };
+      const poll = () => {
+        if (done) return;
+        const ms = elapsed();
+        if (ms >= l.timeoutMs - l.graceMs - l.confirmationMs && !canceled) cancel("fixture-deadline", "timed-out");
+        if (canceled && !forced && monotonic() - cancelAt >= l.graceMs) { forced = true; send("SIGKILL"); }
+        const alive = observeGroup();
+        if (r.exitObserved && closeObserved && stdinClosed && stdoutClosed && stderrClosed && !recordPending && !alive) {
+          if (!canceled && !spawnFailed) {
+            try { if (exitCode !== 0) throw Error("failed"); protocol.finish(); stderrDecoder.decode(); }
+            catch (e) { terminalFailure = true; r.state = "failed"; add(e instanceof ParseFailure ? e.code : "fixture-exit-or-stderr-invalid"); }
+          }
+          finalize(false);
+        } else if (r.exitObserved && alive && !canceled) cancel("fixture-descendants-live");
+        if (spawnFailed && closeObserved) finalize(false);
+      };
+      const abort = () => cancel("fixture-canceled", "canceled");
+      child.on("spawn", () => {
+        if (done) { spawned = true; send("SIGKILL"); return; }
+        spawned = true; r.started = true; r.fixtureExecuted = true; recordPending = true;
+        if (canceled) send("SIGTERM");
+        Promise.resolve().then(() => checkpoint("fixture-spawned")).then(() => capability.started())
+          .catch(() => { recordFailed = true; cancel("fixture-mark-started-unconfirmed"); })
+          .finally(() => { recordPending = false; poll(); });
+      });
+      child.on("error", () => { if (done) return; if (!spawned) { spawnFailed = true; add("fixture-spawn-failed"); } else cancel("fixture-process-error"); });
+      child.on("exit", code => { if (done) return; r.exitObserved = true; exitCode = code; poll(); });
+      child.on("close", () => { closeObserved = true; poll(); });
+      child.stdin.on("close", () => { stdinClosed = true; poll(); });
+      child.stdout.on("close", () => { stdoutClosed = true; poll(); });
+      child.stderr.on("close", () => { stderrClosed = true; poll(); });
+      child.stdin.on("error", () => cancel("fixture-stdin-error"));
+      child.stdout.on("error", () => cancel("fixture-stdout-error"));
+      child.stderr.on("error", () => cancel("fixture-stderr-error"));
+      child.stdout.on("data", chunk => {
+        if (done || canceled) return;
+        try { protocol.push(chunk); } catch (e) { cancel(reason(e)); }
+      });
+      child.stderr.on("data", chunk => {
+        if (done || canceled) return;
+        r.stderrBytes += chunk.length;
+        if (r.stderrBytes > l.maxStderrBytes) cancel("fixture-stderr-limit");
+        else try { stderrDecoder.decode(chunk, { stream: true }); } catch { cancel("fixture-stderr-invalid-utf8"); }
+      });
+      signal?.addEventListener("abort", abort, { once: true }); if (signal?.aborted) abort();
+      timer = setInterval(poll, 10);
+      hardTimer = setTimeout(() => { send("SIGKILL"); poll(); if (!done) finalize(true); }, Math.max(1, l.timeoutMs - elapsed()));
+      try { child.stdin.end(input, error => { if (error) cancel("fixture-stdin-error"); }); }
+      catch { cancel("fixture-stdin-error"); }
+    });
+  } catch (e) {
+    r.reasons = [e instanceof ParseFailure ? e.code : "fixture-start-blocked"];
+    r.terminationConfirmed = !spawnReturned; r.elapsedMs = Math.max(0, monotonic() - start);
+    // A synchronous spawn failure is known not-started; an unexpected post-spawn error is uncertain.
+    if (spawnReturned) r.state = "indeterminate";
+  } finally {
+    if (cwd && (!r.spawnAttempts || r.terminationConfirmed)) {
+      try { const s = await fs.lstat(cwd); if (s.dev !== owned.dev || s.ino !== owned.ino || !s.isDirectory()) throw Error("replaced"); await fs.rmdir(cwd); }
+      catch { r.state = "indeterminate"; r.reasons.push("fixture-workspace-cleanup-required"); }
+    }
+  }
+  return copyInertJson(r);
+}