@piagent/platform 1.6.1 → 1.8.0

package/scripts/benchmark-arm-observer.mjs

@@ -0,0 +1,320 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { pathToFileURL } from "node:url";
+import { types } from "node:util";
+import { createScopedMaterialBroker, loadScopedBrokerPiExtension,
+  SCOPED_TOOL_DEFINITIONS } from "./benchmark-scoped-tool-broker.mjs";
+import { assertScopedBrokerPiOwnership, createQualifiedLoopbackModelRuntime, createQualifiedLoopbackTransport,
+  scopedContextPolicySha256, scopedQualificationIdentity } from "./benchmark-scoped-verification-supervisor.mjs";
+export { createQualifiedLoopbackTransport };
+
+const attached = new WeakSet();
+
+// This public-session seam is useful for qualification. It is not a gateway
+// injection seam, an admission guard, a phase receipt, or a live child launcher.
+// Observation failure invalidates evidence without changing the host callback.
+export function attachBenchmarkArmObserver({ session, identity, record, maximumCallbacks = 128 }) {
+  if (!session?.agent || typeof session.agent.onPayload !== "function"
+    || typeof session.sessionManager?.getSessionId !== "function") throw new Error("arm-observer-public-session-required");
+  if (typeof record !== "function" || !Number.isSafeInteger(maximumCallbacks) || maximumCallbacks < 1
+    || maximumCallbacks > 4096) throw new Error("arm-observer-options-invalid");
+  const keys = ["armId", "candidateDigest", "sessionId", "runtimeInstanceRef"];
+  if (!identity || Object.keys(identity).length !== keys.length
+    || !keys.every(key => typeof identity[key] === "string" && identity[key].length > 0)
+    || !/^[a-f0-9]{64}$/.test(identity.candidateDigest)
+    || session.sessionManager.getSessionId() !== identity.sessionId) throw new Error("arm-observer-identity-invalid");
+  const bound = Object.freeze({ ...identity }), agent = session.agent;
+  if (attached.has(agent)) throw new Error("arm-observer-already-attached");
+  const previous = agent.onPayload;
+  let callbackCount = 0, returnedCount = 0, thrownCount = 0, recordedCount = 0;
+  const failures = new Set();
+  function capture(value) {
+    let nodes = 0;
+    function copy(item, depth) {
+      if (++nodes > 100000 || depth > 64) throw new Error("payload-bounds");
+      if (item === null || typeof item === "string" || typeof item === "boolean") return item;
+      if (typeof item === "number" && Number.isFinite(item)) return item;
+      if (!item || typeof item !== "object" || types.isProxy(item)) throw new Error("payload-non-json");
+      const array = Array.isArray(item), prototype = Object.getPrototypeOf(item);
+      if (!array && prototype !== Object.prototype && prototype !== null) throw new Error("payload-prototype");
+      const descriptors = Object.getOwnPropertyDescriptors(item), result = array ? [] : Object.create(null);
+      for (const key of Reflect.ownKeys(descriptors)) {
+        const descriptor = descriptors[key];
+        if (array && key === "length") continue;
+        if (typeof key !== "string" || !("value" in descriptor) || !descriptor.enumerable
+          || array && !/^(0|[1-9][0-9]*)$/.test(key)) throw new Error("payload-descriptor");
+        Object.defineProperty(result, key, { value: copy(descriptor.value, depth + 1), enumerable: true, configurable: true });
+      }
+      if (array && (result.length !== item.length || Object.keys(result).length !== item.length)) throw new Error("payload-sparse-array");
+      return result;
+    }
+    const json = JSON.stringify(copy(value, 0));
+    if (Buffer.byteLength(json) > 4 * 1024 * 1024) throw new Error("payload-size");
+    return createHash("sha256").update(json).digest("hex");
+  }
+  async function observe(event) {
+    if (event.sequence > maximumCallbacks) { failures.add("callback-limit"); return; }
+    try { await record(Object.freeze({ ...bound, ...event })); recordedCount++; }
+    catch { failures.add("record-failed"); }
+  }
+  async function wrapper(...args) {
+    const sequence = ++callbackCount;
+    let result;
+    try { result = await Reflect.apply(previous, this, args); }
+    catch (error) {
+      thrownCount++;
+      await observe({ sequence, outcome: "thrown", payloadSha256: null });
+      throw error;
+    }
+    returnedCount++;
+    try {
+      const payloadSha256 = capture(result === undefined ? args[0] : result);
+      await observe({ sequence, outcome: "returned", payloadSha256 });
+    } catch { failures.add("payload-unobservable"); }
+    return result;
+  }
+  agent.onPayload = wrapper;
+  attached.add(agent);
+  return Object.freeze({
+    status() {
+      const reasons = [...failures];
+      if (agent.onPayload !== wrapper) reasons.push("callback-ownership-lost");
+      return Object.freeze({ callbackCount, returnedCount, thrownCount, recordedCount,
+        complete: reasons.length === 0 && recordedCount === callbackCount, reasons,
+        phaseWireQualified: false, dispatchPermission: false });
+    },
+    detach() {
+      if (agent.onPayload !== wrapper) { failures.add("callback-ownership-lost"); return false; }
+      agent.onPayload = previous; attached.delete(agent); return true;
+    }
+  });
+}
+
+const HASH = /^[a-f0-9]{64}$/;
+const ARM_KEYS = ["version", "armId", "candidateRoot", "candidateDigest", "configSha256", "brokerClosureSha256",
+  "toolDefinitionsSha256", "manifestAuthoritySha256", "journalSignerSha256", "journalPathSha256",
+  "contextPolicySha256", "sdkRoot", "sdkVersion", "sdkTreeSha256", "assetsRoot", "assetTreeSha256", "runtimeHome"];
+const TOOL_NAMES = Object.freeze(SCOPED_TOOL_DEFINITIONS.map(tool => tool.name));
+function armFail(code) { throw Object.assign(new Error(code), { armCode: code }); }
+function exactRecord(value, keys, code) {
+  if (!value || typeof value !== "object" || types.isProxy(value)
+    || ![null, Object.prototype].includes(Object.getPrototypeOf(value))) armFail(code);
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (Reflect.ownKeys(descriptors).length !== keys.length || !keys.every(key => descriptors[key]?.enumerable
+    && Object.hasOwn(descriptors[key], "value"))) armFail(code);
+}
+function realDirectory(value, code) {
+  if (typeof value !== "string" || !path.isAbsolute(value) || path.normalize(value) !== value
+    || !fs.statSync(value).isDirectory()) armFail(code);
+  const real = fs.realpathSync(value);
+  if (real !== value) armFail(code);
+  return real;
+}
+function inside(root, file, code) {
+  const real = fs.realpathSync(file);
+  if (real !== root && !real.startsWith(root + path.sep)) armFail(code);
+  return real;
+}
+function validateArmIdentity(identity) {
+  exactRecord(identity, ARM_KEYS, "arm-identity-fields");
+  if (identity.version !== 3 || !["A", "B", "C"].includes(identity.armId)
+    || !["candidateDigest", "configSha256", "brokerClosureSha256", "toolDefinitionsSha256",
+      "manifestAuthoritySha256", "journalSignerSha256", "journalPathSha256", "contextPolicySha256",
+      "sdkTreeSha256", "assetTreeSha256"]
+      .every(key => HASH.test(identity[key]))
+    || typeof identity.sdkVersion !== "string" || !/^\d+\.\d+\.\d+$/.test(identity.sdkVersion)) armFail("arm-identity-invalid");
+  const result = { ...identity, candidateRoot: realDirectory(identity.candidateRoot, "arm-candidate-root"),
+    sdkRoot: realDirectory(identity.sdkRoot, "arm-sdk-root"), assetsRoot: realDirectory(identity.assetsRoot, "arm-assets-root"),
+    runtimeHome: realDirectory(identity.runtimeHome, "arm-runtime-home") };
+  inside(result.candidateRoot, path.join(result.assetsRoot, "index.html"), "arm-assets-outside-candidate");
+  if (result.runtimeHome.startsWith(result.candidateRoot + path.sep)
+    || result.runtimeHome.startsWith(result.sdkRoot + path.sep)) armFail("arm-runtime-home-overlap");
+  return Object.freeze(result);
+}
+async function candidateModules(root, names) {
+  return await Promise.all(names.map(async relative => {
+    const file = inside(root, path.join(root, relative), "arm-module-outside-candidate");
+    return await import(pathToFileURL(file).href);
+  }));
+}
+/** Creates the explicit G0 launcher. Nothing changes in the default gateway path. */
+export function createQualifiedArmGatewayLauncher({ identity: rawIdentity, brokerConfigPath,
+  createBroker = createScopedMaterialBroker, modelRuntime, loopbackTransport, record, contextPolicy,
+  scopedBrokerRouter = null } = {}) {
+  const identity = validateArmIdentity(rawIdentity);
+  if (scopedContextPolicySha256(contextPolicy) !== identity.contextPolicySha256) armFail("arm-context-policy-mismatch");
+  if (typeof record !== "function") armFail("arm-record-required");
+  if (typeof brokerConfigPath !== "string" || !path.isAbsolute(brokerConfigPath)
+    || path.normalize(brokerConfigPath) !== brokerConfigPath) armFail("arm-broker-config-path");
+  if (scopedBrokerRouter && (!Array.isArray(scopedBrokerRouter.toolNames)
+    || typeof scopedBrokerRouter.extensionFactory !== "function"
+    || typeof scopedBrokerRouter.beginOperation !== "function"
+    || typeof scopedBrokerRouter.settlementEvidence !== "function"
+    || typeof scopedBrokerRouter.assertProviderDispatchReady !== "function"
+    || typeof scopedBrokerRouter.takeFatalProviderBoundaryError !== "function"
+    || typeof scopedBrokerRouter.assertOwnership !== "function"
+    || typeof scopedBrokerRouter.dispose !== "function")) armFail("arm-scoped-router-invalid");
+  let launched = false;
+  return async function qualifiedArmGateway(options) {
+    if (launched) armFail("arm-launcher-single-use"); launched = true;
+    if (fs.realpathSync(options.packageRoot) !== identity.candidateRoot
+      || fs.realpathSync(options.staticRoot) !== identity.assetsRoot
+      || fs.realpathSync(options.agentDir) !== identity.runtimeHome
+      || options.expectedPiVersion !== identity.sdkVersion
+      || (options.scopedBrokerRouter ?? null) !== scopedBrokerRouter) armFail("arm-launch-identity-mismatch");
+    const actual = scopedQualificationIdentity({ candidateRoot: identity.candidateRoot,
+      assetsRoot: identity.assetsRoot, sdkRoot: identity.sdkRoot });
+    if (actual.sourceSha256 !== identity.candidateDigest || actual.assetTreeSha256 !== identity.assetTreeSha256
+      || actual.sdkTreeSha256 !== identity.sdkTreeSha256
+      || actual.brokerClosureSha256 !== identity.brokerClosureSha256) armFail("arm-broker-identity-mismatch");
+    const capturedRuntime = await createQualifiedLoopbackModelRuntime({ modelRuntime, transport: loopbackTransport,
+      record, identity, contextPolicy });
+    const loaded = scopedBrokerRouter ? null
+      : loadScopedBrokerPiExtension({ configPath: brokerConfigPath, createBroker });
+    let loopback, runtimes;
+    try {
+    const shared = { armId: identity.armId, sourceSha256: identity.candidateDigest,
+      assetTreeSha256: identity.assetTreeSha256, configSha256: identity.configSha256,
+      brokerClosureSha256: identity.brokerClosureSha256, toolDefinitionsSha256: identity.toolDefinitionsSha256,
+      manifestAuthoritySha256: identity.manifestAuthoritySha256, journalSignerSha256: identity.journalSignerSha256,
+      journalPathSha256: identity.journalPathSha256, contextPolicySha256: identity.contextPolicySha256,
+      sdkTreeSha256: identity.sdkTreeSha256 };
+    if (loaded ? loaded.configSha256 !== identity.configSha256
+      || Object.entries(shared).some(([key, value]) => loaded.identity[key] !== value)
+      : createHash("sha256").update(fs.readFileSync(brokerConfigPath)).digest("hex") !== identity.configSha256) {
+      armFail("arm-broker-identity-mismatch");
+    }
+    const names = ["packages/piagent-webui/gateway/pi-host.ts", "packages/piagent-webui/gateway/session-runtime-factory.ts",
+      "packages/piagent-webui/server/loopback-server.ts", "packages/piagent-webui/gateway/profile-state.ts",
+      "packages/piagent-webui/gateway/session-metadata-store.ts", "packages/piagent-webui/gateway/project-registry.ts",
+      "packages/piagent-webui/gateway/session-lease-store.ts", "packages/piagent-webui/gateway/gateway-events.ts",
+      "packages/piagent-webui/gateway/session-runtime-supervisor.ts", "packages/piagent-webui/gateway/session-catalog.ts",
+      "packages/piagent-webui/gateway/session-command-store.ts", "packages/piagent-webui/gateway/session-command-controller.ts",
+      "packages/piagent-webui/gateway/runtime-command-controller.ts", "packages/piagent-webui/gateway/gateway-protocol-service.ts",
+      "packages/piagent-webui/gateway/session-inspection-registry.ts", "packages/piagent-webui/gateway/session-live-state.ts"];
+    const [piHost, factoryModule, loopbackModule, profileModule, metadataModule, projectModule, leaseModule,
+      eventsModule, supervisorModule, catalogModule, commandStoreModule, commandModule, runtimeCommandModule,
+      protocolModule, inspectionModule, liveModule] = await candidateModules(identity.candidateRoot, names);
+    const selectedFactoryModule = scopedBrokerRouter
+      ? await import("../packages/piagent-webui/gateway/session-runtime-factory.ts") : factoryModule;
+    const selectedSupervisorModule = scopedBrokerRouter
+      ? await import("../packages/piagent-webui/gateway/session-runtime-supervisor.ts") : supervisorModule;
+    if (fs.realpathSync(piHost.installedPiHostRoot()) !== identity.sdkRoot) armFail("arm-sdk-root-mismatch");
+    const host = await piHost.loadPinnedPiHost(identity.sdkVersion), runtimeScope = new AsyncLocalStorage();
+    let claimedSession = false; const observers = [];
+    const facade = { ...host,
+      async createAgentSessionServices(input) {
+        const guard = inside(identity.candidateRoot, path.join(identity.candidateRoot,
+          "packages/piagent-core/extensions/piagent-guard.ts"), "arm-guard-outside-candidate");
+        const supplied = input.resourceLoaderOptions?.additionalExtensionPaths ?? [];
+        if (supplied.length !== 1 || fs.realpathSync(supplied[0]) !== guard) armFail("arm-extension-route-mismatch");
+        const extensionFactory = scopedBrokerRouter?.extensionFactory ?? loaded.extensionFactory;
+        const suppliedFactories = input.resourceLoaderOptions?.extensionFactories;
+        if (scopedBrokerRouter && suppliedFactories !== undefined
+          && (suppliedFactories.length !== 1 || suppliedFactories[0] !== extensionFactory)) {
+          armFail("arm-extension-route-mismatch");
+        }
+        const suppliedModelRuntime = scopedBrokerRouter ? input.modelRuntime : capturedRuntime;
+        if (scopedBrokerRouter) {
+          const descriptor = Object.getOwnPropertyDescriptor(suppliedModelRuntime ?? {}, "streamSimple");
+          if (Object.getPrototypeOf(suppliedModelRuntime ?? {}) !== capturedRuntime
+            || typeof descriptor?.value !== "function" || descriptor.enumerable !== true
+            || descriptor.writable !== false || descriptor.configurable !== false) {
+            armFail("arm-provider-boundary-route-mismatch");
+          }
+        }
+        try { const services = await host.createAgentSessionServices({ ...input, agentDir: identity.runtimeHome,
+          modelRuntime: suppliedModelRuntime,
+          resourceLoaderOptions: { ...input.resourceLoaderOptions, noExtensions: true, noSkills: true,
+            noPromptTemplates: true, noThemes: true, noContextFiles: true,
+            additionalExtensionPaths: [guard], extensionFactories: [extensionFactory] } });
+          const ownership = scopedBrokerRouter ? scopedBrokerRouter.assertOwnership(services.resourceLoader)
+            : assertScopedBrokerPiOwnership(services.resourceLoader, extensionFactory);
+          await record({ version: 2, kind: "qualified-tool-ownership", ...ownership }); return services; }
+        catch (error) { await record({ version: 1, kind: "qualified-arm-error", stage: "services", message: String(error?.message ?? error) }); throw error; }
+      },
+      async createAgentSessionFromServices(input) {
+        if (claimedSession) armFail("arm-session-cap"); claimedSession = true;
+        let created;
+        try { created = await host.createAgentSessionFromServices({ ...input, noTools: "all", tools: [...TOOL_NAMES] }); }
+        catch (error) { await record({ version: 1, kind: "qualified-arm-error", stage: "session", message: String(error?.message ?? error) }); throw error; }
+        const scope = runtimeScope.getStore();
+        if (!scope) armFail("arm-runtime-scope-missing");
+        observers.push(attachBenchmarkArmObserver({ session: created.session, identity: { armId: identity.armId,
+          candidateDigest: identity.candidateDigest, sessionId: created.session.sessionManager.getSessionId(),
+          runtimeInstanceRef: scope.runtimeInstanceRef }, record }));
+        if (JSON.stringify(created.session.getActiveToolNames()) !== JSON.stringify(TOOL_NAMES)) armFail("arm-tool-surface-mismatch");
+        created.session.subscribe(event => { if (event?.type === "message_end" && event.message?.errorMessage)
+          void record({ version: 1, kind: "qualified-arm-error", stage: "message", message: String(event.message.errorMessage) }); });
+        await record({ version: 1, kind: "qualified-session-created", armId: identity.armId,
+          sessionId: created.session.sessionManager.getSessionId(), tools: created.session.getActiveToolNames() });
+        return created;
+      } };
+    const baseFactory = selectedFactoryModule.createProductionRuntimeFactory({ host: facade,
+      agentDir: identity.runtimeHome, packageRoot: identity.candidateRoot, modelRuntime: capturedRuntime,
+      ...(scopedBrokerRouter ? { scopedBrokerRouter } : {}) });
+    const runtimeFactory = async (info, runtimeInstanceRef, manager, initial) => {
+      try {
+        return await runtimeScope.run({ runtimeInstanceRef },
+          () => baseFactory(info, runtimeInstanceRef, manager, initial));
+      }
+      catch (error) { await record({ version: 1, kind: "qualified-arm-error", stage: "runtime", message: String(error?.message ?? error) }); throw error; }
+    };
+    const state = profileModule.gatewayProfileState(identity.runtimeHome), key = profileModule.readOrCreateCatalogKey(state);
+    const metadata = new metadataModule.SessionMetadataStore(state.root, key), projects = new projectModule.ProjectRegistry(state.root, key);
+    const gatewayInstanceRef = `g0_${process.pid}_${identity.armId}_${Date.now()}`;
+    const events = new eventsModule.GatewayEventStore();
+    runtimes = new selectedSupervisorModule.SessionRuntimeSupervisor({ gatewayInstanceRef, key,
+      leases: new leaseModule.SessionLeaseStore(state.root, key), listSessions: () => host.SessionManager.listAll(),
+      runtimeFactory, host, events, resolveProject: ref => projects.resolve(ref),
+      compositeSettlementEvidence: scopedBrokerRouter
+        ? () => scopedBrokerRouter.settlementEvidence() : loaded.settlementEvidence });
+    const readCatalog = () => catalogModule.buildSessionCatalog({ gatewayInstanceRef, key,
+      listSessions: () => runtimes.listSessions(), readMetadata: () => metadata.read(),
+      readOwnership: ref => runtimes.ownership(ref), readSessionOptions: () => ({ modelLabel: null, thinkingLevel: "unknown" }) });
+    runtimes.setProjectionReader(async ref => { const catalog = await readCatalog(), row = catalog.sessions.find(item => item.sessionRef === ref);
+      if (!row) armFail("arm-session-projection"); return { sessionRevision: row.sessionRevision, liveState: row.liveState }; });
+    const commands = new commandModule.SessionCommandController({ catalog: readCatalog, runtimes, metadata,
+      store: new commandStoreModule.SessionCommandStore(state.root, key), events });
+    const runtimeCommands = new runtimeCommandModule.RuntimeCommandController({ catalog: readCatalog, runtimes, events });
+    const capabilities = () => ({ schemaVersion: 1, version: "piagent-gateway-capabilities-v1", generatedAt: new Date().toISOString(),
+      gatewayInstanceRef, protocol: { minimum: 1, maximum: 1, selected: 1, compatibility: "ready" }, mode: "full",
+      capabilities: { catalog: { status: "available", version: 1, reasonCode: null }, events: { status: "available", version: 1, reasonCode: null },
+        terminalAdapter: { status: "unavailable", version: null, reasonCode: "g0-scoped" }, sessionRuntime: { status: "available", version: 1, reasonCode: null },
+        sessionActions: Object.fromEntries(["create", "send", "abort", "setModel", "setThinking", "setPermission", "rename", "pin", "archive", "unarchive", "fork", "acquire", "release"]
+          .map(name => [name, { status: "available", version: 1, reasonCode: null }])) }, reasonCode: null });
+    const protocol = new protocolModule.GatewayProtocolService({ capabilities, catalog: readCatalog, events, command: commands });
+    const inspections = new inspectionModule.SessionInspectionRegistry({ gatewayInstanceRef, host, key,
+      packageRoot: identity.candidateRoot, agentDir: identity.runtimeHome, models: capturedRuntime, projects,
+      listSessions: () => runtimes.listSessions(), openLiveSession: ref => runtimes.liveSessionManager(ref),
+      operationLiveness: ref => runtimes.currentOperation(ref) ? "running" : "idle" });
+    loopback = await loopbackModule.startLoopbackServer({ staticRoot: identity.assetsRoot, mode: "gateway",
+      readCapabilities: capabilities, readSessionCatalog: readCatalog,
+      readSessionLiveState: () => liveModule.buildSessionLiveState({ gatewayInstanceRef,
+        eventSequence: events.stateVersion, operations: runtimes.currentOperations(), settlements: events.recentOperationSettlements() }),
+      readSessionCreationOptions: () => inspections.creationOptions(), readSessionModel: ref => inspections.provider(ref),
+      executeRuntimeCommand: command => runtimeCommands.execute(command), gatewayProtocol: protocol });
+    await record(Object.freeze({ version: 1, kind: "qualified-arm-start", armId: identity.armId,
+      candidateDigest: identity.candidateDigest, configSha256: identity.configSha256, moduleCount: names.length,
+      tools: [...TOOL_NAMES], providerRoute: "local-loopback", externalProviderCalls: 0 }));
+    return Object.freeze({ descriptor: { gatewayInstanceRef, origin: loopback.origin }, launchUrl: loopback.issueLaunchUrl(),
+      qualification: "PROVISIONAL_NOT_G0", async wait() {}, async close() {
+        await loopback.close().catch(() => undefined); await runtimes.close().catch(() => undefined);
+        await record({ version: 1, kind: "qualified-observer-status", armId: identity.armId,
+          transport: loopbackTransport.status(), statuses: observers.map(observer => observer.status()) });
+        if (loaded && !loaded.broker.status().ended) {
+          if (!loaded.broker.status().cancelled) loaded.broker.cancel(); loaded.broker.close();
+        }
+      } });
+    } catch (error) {
+      await loopback?.close().catch(() => undefined); await runtimes?.close().catch(() => undefined);
+      try { if (loaded && !loaded.broker.status().ended) {
+        if (!loaded.broker.status().cancelled) loaded.broker.cancel(); loaded.broker.close();
+      } }
+      catch {}
+      throw error;
+    }
+  };
+}

package/scripts/benchmark-budget-ipc.mjs

@@ -0,0 +1,34 @@
+import { BENCHMARK_BUDGET_CONTEXT } from "./benchmark-budget-runtime.mjs";
+
+// Only the frozen core's direct parent can acknowledge owned process groups.
+// This narrows cleanup races; it does not promise a zero spawn/registration gap
+// for command-line providers whose prompt is already present in argv.
+export function createBenchmarkBudgetProcessHooks({ env = process.env, channel = process, timeoutMs = 5_000 } = {}) {
+  if (!env[BENCHMARK_BUDGET_CONTEXT]) return {};
+  const { stageId, parentPid } = JSON.parse(env[BENCHMARK_BUDGET_CONTEXT]);
+  if (!/^[a-f0-9]{32}$/.test(stageId ?? "") || parentPid !== channel.ppid
+    || typeof channel.send !== "function" || !channel.connected) {
+    throw new Error("Benchmark budget process ownership requires the direct launcher IPC channel");
+  }
+  const exchange = (event, pid) => new Promise((resolve, reject) => {
+    const finish = error => {
+      clearTimeout(timer);
+      channel.off("message", onMessage); channel.off("disconnect", onDisconnect);
+      if (error) reject(error); else resolve();
+    };
+    const onDisconnect = () => finish(new Error("Benchmark budget launcher IPC disconnected"));
+    const onMessage = message => {
+      if (message?.kind !== "benchmark-budget-process-ack-v1") return;
+      if (message.stageId === stageId && message.pid !== pid) return; // Another concurrent owned command.
+      if (message.stageId !== stageId || message.pid !== pid || message.event !== event || message.accepted !== true) {
+        finish(new Error("Benchmark budget ownership receipt mismatched"));
+      } else finish();
+    };
+    const timer = setTimeout(() => finish(new Error("Benchmark budget ownership receipt timed out")), timeoutMs);
+    channel.on("message", onMessage); channel.once("disconnect", onDisconnect);
+    try {
+      channel.send({ kind: "benchmark-budget-process-v1", stageId, event, pid }, error => { if (error) finish(error); });
+    } catch (error) { finish(error); }
+  });
+  return { started: pid => exchange("started", pid), closed: pid => exchange("closed", pid) };
+}

package/scripts/benchmark-budget-launcher.mjs

@@ -0,0 +1,91 @@
+import crypto from "node:crypto";
+import { openBenchmarkBudgetGovernor } from "../packages/piagent-core/benchmark/benchmark-budget-governor.js";
+import { BENCHMARK_BUDGET_CONTEXT, assertBenchmarkBudgetPolicyUnchanged } from "./benchmark-budget-runtime.mjs";
+import { createBenchmarkBudgetProcessRegistry } from "./benchmark-budget-processes.mjs";
+
+function signalGroup(child, signal) {
+  try {
+    if (process.platform !== "win32" && child.pid) process.kill(-child.pid, signal);
+    else child.kill(signal);
+  } catch { /* Child already exited. */ }
+}
+
+// The outer process owns timing from before snapshot setup through snapshot
+// cleanup. The core is the sole attempt-state writer during the child lifetime.
+export function startBenchmarkBudgetLaunch(control, { resume = false, now = Date.now,
+  schedule = setTimeout, cancel = clearTimeout, registryOptions = {}, signalCore = signalGroup } = {}) {
+  if (!control) return null;
+  assertBenchmarkBudgetPolicyUnchanged(control);
+  const parameters = { statePath: control.identity.statePath, policy: control.policy, binding: control.binding, now };
+  const stageId = crypto.randomBytes(16).toString("hex");
+  const governor = openBenchmarkBudgetGovernor({ ...parameters, resume });
+  let started;
+  try { started = governor.startStage(stageId); } finally { governor.close(); }
+  const deadline = started.stages.find(stage => stage.stageId === stageId).lastCheckpointAtMs + started.remainingActiveWallTimeMs;
+  const registry = createBenchmarkBudgetProcessRegistry({ ...registryOptions, stageId });
+  const timers = new Set();
+  let timedOut = false, finished = false, supervised = false, coreClosed = false, protocolFailed = false;
+  let childProcess, cleanupReceipt;
+  const terminate = signal => {
+    registry.terminateAll(signal);
+    if (childProcess && !coreClosed) signalCore(childProcess, signal);
+  };
+  const escalate = () => {
+    terminate("SIGTERM");
+    const killTimer = schedule(() => terminate("SIGKILL"), 10_000);
+    timers.add(killTimer);
+  };
+  const protocolFailure = () => { if (!protocolFailed) { protocolFailed = true; escalate(); } };
+  return {
+    context: JSON.stringify({ stageId, parentPid: process.pid, policySha256: control.identity.sha256,
+      statePath: control.identity.statePath }),
+    environmentKey: BENCHMARK_BUDGET_CONTEXT,
+    assertReady() {
+      assertBenchmarkBudgetPolicyUnchanged(control);
+      if (now() >= deadline) {
+        timedOut = true;
+        throw Object.assign(new Error("Benchmark budget: active stage wall threshold reached before child launch"),
+          { exitCode: 1, code: "BENCHMARK_BUDGET_DENIED" });
+      }
+    },
+    supervise(child) {
+      if (supervised) throw new Error("Benchmark budget child was supervised twice");
+      supervised = true;
+      childProcess = child;
+      child.once?.("close", () => { coreClosed = true; });
+      child.on?.("message", message => {
+        try {
+          registry.handleMessage(message);
+          child.send({ kind: "benchmark-budget-process-ack-v1", stageId, event: message.event,
+            pid: message.pid, accepted: true }, error => { if (error) protocolFailure(); });
+        } catch { protocolFailure(); }
+      });
+      const timer = schedule(() => {
+        timedOut = true;
+        escalate();
+      }, Math.max(0, deadline - now()));
+      timers.add(timer);
+    },
+    terminate,
+    async drain(options) {
+      cleanupReceipt = await registry.drain(options);
+      return { ...cleanupReceipt, cleanupConfirmed: cleanupReceipt.cleanupConfirmed && !protocolFailed };
+    },
+    finish() {
+      if (finished) throw new Error("Benchmark budget stage was finalized twice");
+      finished = true;
+      for (const timer of timers) cancel(timer);
+      const finalizer = openBenchmarkBudgetGovernor({ ...parameters, resume: true, finalizeStageId: stageId });
+      try {
+        const launcherErrors = [];
+        const stop = reason => { launcherErrors.push(reason); finalizer.stop(reason); };
+        try { assertBenchmarkBudgetPolicyUnchanged(control); } catch { stop("budget-policy-changed"); }
+        if (timedOut) stop("launcher-wall-watchdog");
+        if (protocolFailed) stop("launcher-process-protocol-failure");
+        if (supervised && cleanupReceipt?.cleanupConfirmed !== true) stop("launcher-process-cleanup-unconfirmed");
+        return { ...finalizer.endStage(stageId), launcherSucceeded: launcherErrors.length === 0,
+          launcherErrors, processCleanup: cleanupReceipt ?? null };
+      } finally { finalizer.close(); }
+    }
+  };
+}

package/scripts/benchmark-budget-processes.mjs

@@ -0,0 +1,133 @@
+import { performance } from "node:perf_hooks";
+
+const KIND = "benchmark-budget-process-v1";
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+const validPid = pid => Number.isInteger(pid) && pid > 1 && pid <= 2_147_483_647 && pid !== process.pid && pid !== process.ppid;
+
+function defaultSignalGroup(pid, signal) {
+  process.kill(process.platform === "win32" ? pid : -pid, signal);
+}
+
+function defaultGroupAlive(pid) {
+  try { process.kill(process.platform === "win32" ? pid : -pid, 0); return true; }
+  catch (error) { if (error.code === "ESRCH") return false; throw error; }
+}
+
+/**
+ * The trusted core reports each detached provider process group through its
+ * direct IPC channel. The parent never scans or guesses other process IDs.
+ * Registration must be acknowledged before dispatch can progress. Core exit is
+ * not proof of descendant exit: drain independently TERM/KILL/verifies every
+ * still-owned group, including when the core event loop stops responding.
+ */
+export function createBenchmarkBudgetProcessRegistry({ stageId, signalGroup = defaultSignalGroup,
+  groupAlive = defaultGroupAlive, now = () => performance.now(), sleep = delay } = {}) {
+  if (!/^[a-f0-9]{32}$/.test(stageId ?? "")
+    || ![signalGroup, groupAlive, now, sleep].every(value => typeof value === "function")) {
+    throw new Error("Benchmark process registry requires a stage identity and valid operations");
+  }
+  const groups = new Map();
+  const errors = [];
+  const signals = [];
+  const livenessProbeFailures = new Map();
+  let draining = false;
+  let drainPromise;
+  const note = code => { if (!errors.includes(code)) errors.push(code); };
+  const fail = message => {
+    note(message);
+    throw Object.assign(new Error(`Benchmark process registry: ${message}`), { code: "BENCHMARK_BUDGET_PROCESS_INVALID", exitCode: 1 });
+  };
+  const inspect = pid => {
+    try {
+      const result = groupAlive(pid);
+      if (typeof result !== "boolean") throw Object.assign(new Error("invalid liveness result"), { code: "INVALID_LIVENESS_RESULT" });
+      const priorFailure = livenessProbeFailures.get(pid);
+      if (priorFailure) priorFailure.latestObservation = result ? "alive" : "absent";
+      return result;
+    } catch (error) {
+      // A dying POSIX group can transiently reject kill(group, 0), e.g. EPERM.
+      // This is NEVER proof of exit: retain ownership and retry within the same
+      // bounded drain. Only a later conclusive absent probe can resolve it.
+      const prior = livenessProbeFailures.get(pid);
+      const code = /^[A-Z0-9_]{1,80}$/.test(error?.code ?? "") ? error.code : "UNKNOWN";
+      livenessProbeFailures.set(pid, { pid, count: (prior?.count ?? 0) + 1, lastErrorCode: code, latestObservation: "unknown" });
+      return true;
+    }
+  };
+  const collectExited = () => {
+    for (const [pid, status] of groups) if (status === "active" && !inspect(pid)) groups.set(pid, "closed");
+  };
+  const snapshot = () => {
+    const unconfirmedPids = [...groups].filter(([, status]) => status === "active").map(([pid]) => pid);
+    return { schemaVersion: 1, stageId, registeredGroups: groups.size, cleanupConfirmed: errors.length === 0 && unconfirmedPids.length === 0,
+      unconfirmedPids, errors: [...errors], signals: signals.map(value => ({ ...value })),
+      livenessProbeFailures: [...livenessProbeFailures.values()].map(value => ({ ...value })), draining };
+  };
+  const terminateAll = signal => {
+    if (!["SIGINT", "SIGTERM", "SIGHUP", "SIGKILL"].includes(signal)) fail("unsupported termination signal");
+    for (const [pid, status] of groups) {
+      if (status !== "active") continue;
+      signals.push({ pid, signal });
+      try { signalGroup(pid, signal); }
+      catch (error) { if (error.code !== "ESRCH") note("process-group-signal-unconfirmed"); }
+    }
+    return snapshot();
+  };
+  const waitForGroups = async (graceMs, pollMs) => {
+    const started = now();
+    if (!Number.isFinite(started)) { note("invalid-registry-clock"); return; }
+    // The iteration bound also prevents an injected or regressing clock hanging
+    // shutdown forever. Production uses a monotonic clock, not wall-clock time.
+    for (let index = 0; index <= Math.ceil(graceMs / pollMs); index += 1) {
+      collectExited();
+      if (![...groups.values()].includes("active")) return;
+      const elapsed = now() - started;
+      if (!Number.isFinite(elapsed) || elapsed < 0) { note("invalid-registry-clock"); return; }
+      if (elapsed >= graceMs || index === Math.ceil(graceMs / pollMs)) return;
+      await sleep(Math.min(pollMs, graceMs - elapsed));
+    }
+  };
+  return {
+    handleMessage(message) {
+      if (!message || typeof message !== "object" || Array.isArray(message)
+        || Object.keys(message).sort().join(",") !== "event,kind,pid,stageId"
+        || message.kind !== KIND || message.stageId !== stageId
+        || !["started", "closed"].includes(message.event) || !validPid(message.pid)) fail("malformed-or-foreign-process-message");
+      if (message.event === "started") {
+        if (draining) fail("registry is draining or closed");
+        if (groups.has(message.pid)) fail("duplicate process registration");
+        if (groups.size >= 10_000) fail("process registry capacity exceeded");
+        groups.set(message.pid, "active");
+      } else {
+        if (!groups.has(message.pid)) fail("unknown process close");
+        if (groups.get(message.pid) !== "active") fail("duplicate process close");
+        if (inspect(message.pid)) fail("process group still alive after close receipt");
+        groups.set(message.pid, "closed");
+      }
+      return { accepted: true, pid: message.pid, event: message.event };
+    },
+    terminateAll,
+    snapshot,
+    drain({ termGraceMs = 2000, killGraceMs = 1000, pollMs = 20 } = {}) {
+      if (![termGraceMs, killGraceMs, pollMs].every(Number.isInteger)
+        || termGraceMs < 0 || killGraceMs < 0 || termGraceMs + killGraceMs > 10_000 || pollMs < 1 || pollMs > 1000) {
+        return Promise.reject(new Error("Benchmark process registry drain timing bounds are invalid"));
+      }
+      if (!drainPromise) {
+        draining = true;
+        drainPromise = (async () => {
+          collectExited();
+          terminateAll("SIGTERM");
+          await waitForGroups(termGraceMs, pollMs);
+          terminateAll("SIGKILL");
+          await waitForGroups(killGraceMs, pollMs);
+          collectExited();
+          if ([...groups.values()].includes("active")) note("process-group-cleanup-unconfirmed");
+          if ([...livenessProbeFailures.values()].some(value => value.latestObservation === "unknown")) note("process-group-liveness-unconfirmed");
+          return snapshot();
+        })();
+      }
+      return drainPromise;
+    }
+  };
+}