machine-bridge-mcp 2.0.0 → 3.0.0-beta.10

package/src/local/runtime.mjs

@@ -6,7 +6,7 @@ import { isRelayReadyContext } from "./relay-connection.mjs";
 import { ProcessSessionManager } from "./process-sessions.mjs";
 import { MAX_CONCURRENT_TOOL_CALLS } from "./execution-limits.mjs";
 export { MAX_COMMAND_BYTES } from "./process-contract.mjs";
-import { normalizePolicy, PolicyGate } from "./tools.mjs";
+import { normalizePolicy, PolicyGate, toolNamesForPolicy } from "./tools.mjs";
 import { publicError } from "./errors.mjs";
 import { ProcessTracker } from "./process-tracker.mjs";
 import { CallRegistry } from "./call-registry.mjs";
@@ -14,6 +14,7 @@ import { RuntimeObservability } from "./observability.mjs";
 import { ToolExecutor } from "./tool-executor.mjs";
 import { boundedErrorMessage, ProcessExecutionService } from "./process-execution.mjs";
 import { GitService } from "./git-service.mjs";
+import { createTrustedGitResolver } from "./trusted-git-executable.mjs";
 import { LifecycleController } from "./lifecycle.mjs";
 import { MAX_WRITE_BYTES, sha256, WorkspaceFileService } from "./workspace-file-service.mjs";
 export { MAX_WRITE_BYTES, sha256 } from "./workspace-file-service.mjs";
@@ -32,6 +33,9 @@ import { buildProjectOverview, buildRuntimeInfo } from "./runtime-reporting.mjs"
 import { diagnoseRuntime as runRuntimeDiagnostics } from "./runtime-diagnostics.mjs";
 import { bindRuntimeToolHandlers, runtimeToolHandlerNames as registeredRuntimeToolHandlerNames } from "./runtime-tool-handlers.mjs";
 import { OperationAuthorizer } from "./operation-authorization.mjs";
+import { SecurityAuditLog } from "./security-audit-log.mjs";
+import { delegatedProcessIsolationStatus } from "./delegated-process-sandbox.mjs";
+import { policyForContext } from "./authority-context.mjs";
 import { createRuntimeRelayConnection, normalizeRelayResumeCalls, normalizeRelayToolCall } from "./runtime-relay.mjs";
 import { RelayCallRecovery } from "./relay-call-recovery.mjs";
 import { assertContainedPath, createRuntimeDir, redactRuntimeErrorMessage, stateRootFromProfileStatePath } from "./runtime-paths.mjs";
@@ -47,7 +51,7 @@ export function runtimeToolHandlerNames() {
 }
 
 export class LocalRuntime {
-  constructor({ workerUrl = "", deviceIdentity = null, expectedRelayVersion = "", workspace, policy, logger = console, onSuperseded = null, onFatal = null, jobRoot = "", approvalRoot = "", resources = {}, resourceStatePath = "", browserStateRoot = "", agentHome = process.env.HOME || process.env.USERPROFILE || "", codexHome = process.env.CODEX_HOME || "", recoverJobs = true, applicationAutomation = {} }) {
+  constructor({ workerUrl = "", deviceIdentity = null, expectedRelayVersion = "", workspace, policy, logger = console, onSuperseded = null, onFatal = null, jobRoot = "", approvalRoot = "", resources = {}, resourceStatePath = "", browserStateRoot = "", agentHome = process.env.HOME || process.env.USERPROFILE || "", codexHome = process.env.CODEX_HOME || "", recoverJobs = true, applicationAutomation = {}, deviceRootStatus = null, resolveGitExecutable = null }) {
     const remoteWorkerUrl = workerUrl ? String(workerUrl) : "";
     this.workspaceInput = resolve(workspace || process.cwd());
     this.workspace = realpathSync.native ? realpathSync.native(this.workspaceInput) : realpathSync(this.workspaceInput);
@@ -58,6 +62,7 @@ export class LocalRuntime {
     this.logger = logger;
     this.onSuperseded = typeof onSuperseded === "function" ? onSuperseded : null;
     this.resourceStatePath = resourceStatePath ? resolve(resourceStatePath) : "";
+    this.deviceRootStatus = deviceRootStatus && typeof deviceRootStatus === "object" ? Object.freeze({ ...deviceRootStatus }) : null;
     this.processTracker = new ProcessTracker();
     this.lifecycle = new LifecycleController("local runtime");
     this.observability = new RuntimeObservability();
@@ -80,13 +85,15 @@ export class LocalRuntime {
     this.mutationQueue = Promise.resolve();
     this.capabilityObserver = new CapabilityObserver();
     this.runtimeDir = createRuntimeDir();
+    this.resolveGitExecutable = createTrustedGitResolver({ resolve: resolveGitExecutable, workspace: this.workspace, stateRoot: browserStateRoot, runtimeDir: this.runtimeDir, home: agentHome });
     this.workspaceFileService = new WorkspaceFileService({
       workspace: this.workspace,
       policy: this.policy,
       policyGate: this.policyGate,
-      resolveExistingPath: (value) => this.resolveExistingPath(value),
-      resolveWritePath: (value) => this.resolveWritePath(value),
-      displayPath: (value) => this.displayPath(value),
+      policyForContext: (context) => this.effectivePolicy(context),
+      resolveExistingPath: (value, context) => this.resolveExistingPath(value, context),
+      resolveWritePath: (value, context) => this.resolveWritePath(value, context),
+      displayPath: (value, context) => this.displayPath(value, context),
       throwIfCancelled: (context) => this.throwIfCancelled(context),
       withMutationLock: (operation) => this.withMutationLock(operation),
     });
@@ -96,6 +103,7 @@ export class LocalRuntime {
       workspace: this.workspace,
       policy: this.policy,
       authorizeTool: (tool) => this.policyGate.assert(tool),
+      policyForContext: (context) => this.effectivePolicy(context),
       resources,
       resourceStatePath,
       stateRoot: browserStateRoot,
@@ -106,21 +114,23 @@ export class LocalRuntime {
       workspace: this.workspace,
       policy: this.policy,
       authorizeTool: (tool) => this.policyGate.assert(tool),
+      policyForContext: (context) => this.effectivePolicy(context),
       runtimeDir: this.runtimeDir,
       processTracker: this.processTracker,
-      resolveCwd: async (input) => {
-        const cwd = await this.resolveExistingPath(input);
+      resolveCwd: async (input, context) => {
+        const cwd = await this.resolveExistingPath(input, context);
         if (!(await stat(cwd)).isDirectory()) throw new Error("cwd is not a directory");
         return cwd;
       },
-      displayPath: (value) => this.displayPath(value),
+      displayPath: (value, context) => this.displayPath(value, context),
       throwIfCancelled: (context) => this.throwIfCancelled(context),
     });
     this.agentContextManager = new AgentContextManager({
       workspace: this.workspace,
       policy: this.policy,
-      displayPath: (value) => this.displayPath(value),
-      resolveExistingPath: (value) => this.resolveExistingPath(value),
+      policyForContext: (context) => this.effectivePolicy(context),
+      displayPath: (value, context) => this.displayPath(value, context),
+      resolveExistingPath: (value, context) => this.resolveExistingPath(value, context),
       throwIfCancelled: (context) => this.throwIfCancelled(context),
       home: agentHome,
       codexHome,
@@ -129,18 +139,20 @@ export class LocalRuntime {
       workspace: this.workspace,
       policy: this.policy,
       policyGate: this.policyGate,
+      policyForContext: (context) => this.effectivePolicy(context),
       runtimeDir: this.runtimeDir,
       processTracker: this.processTracker,
-      resolveExistingPath: (value) => this.resolveExistingPath(value),
+      resolveExistingPath: (value, context) => this.resolveExistingPath(value, context),
       resolveLocalCommand: (args, context) => this.agentContextManager.resolveLocalCommand(args, context),
-      displayPath: (value) => this.displayPath(value),
+      displayPath: (value, context) => this.displayPath(value, context),
       throwIfCancelled: (context) => this.throwIfCancelled(context),
-      retainCompletedOutput: (value) => this.processSessionManager.retainCompletedOutput(value),
+      retainCompletedOutput: (value, context) => this.processSessionManager.retainCompletedOutput(value, context),
     });
     this.gitService = new GitService({
-      resolveExistingPath: (value) => this.resolveExistingPath(value),
-      displayPath: (value) => this.displayPath(value),
-      runProcess: (...args) => this.processExecutionService.run(...args),
+      resolveExistingPath: (value, context) => this.resolveExistingPath(value, context),
+      displayPath: (value, context) => this.displayPath(value, context),
+      runInternalProcess: (...args) => this.processExecutionService.runFixedInternal(...args),
+      gitExecutable: () => this.resolveGitExecutable(),
       maximumBytes: MAX_WRITE_BYTES,
     });
     const runProcess = (cmd, argv, timeoutMs, allowFailure, maxOutputBytes, context, cwd, stdin) => this.runProcess(cmd, argv, timeoutMs, allowFailure, maxOutputBytes, context, cwd, stdin);
@@ -150,16 +162,18 @@ export class LocalRuntime {
       ...applicationAutomation,
       policy: this.policy,
       authorizeTool: (tool) => this.policyGate.assert(tool),
-      displayPath: (value) => this.displayPath(value),
+      displayPath: (value, context) => this.displayPath(value, context),
       runProcess,
       readResourceText,
       throwIfCancelled: (context) => this.throwIfCancelled(context),
     });
+    this.securityAudit = new SecurityAuditLog({ root: approvalRoot });
     this.operationAuthorizer = new OperationAuthorizer({
       workspace: this.workspace,
       root: approvalRoot,
-      resolveExistingPath: (value) => this.resolveExistingPath(value),
-      resolveWritePath: (value) => this.resolveWritePath(value),
+      resolveExistingPath: (value, context) => this.resolveExistingPath(value, context),
+      resolveWritePath: (value, context) => this.resolveWritePath(value, context),
+      protectedRoots: [approvalRoot, browserStateRoot],
     });
     this.browserBridgeManager = new BrowserBridgeManager({
       policy: this.policy,
@@ -178,8 +192,9 @@ export class LocalRuntime {
       operationAuthorizer: this.operationAuthorizer,
       callRegistry: this.callRegistry,
       observability: this.observability,
+      securityAudit: this.securityAudit,
       logger: this.logger,
-      safeMessage: (error, args) => this.safeErrorMessage(error, args),
+      safeMessage: (error, args, context) => this.safeErrorMessage(error, args, context),
       slowMs: SLOW_TOOL_CALL_MS,
     });
     this.relay = createRuntimeRelayConnection(this, {
@@ -198,11 +213,11 @@ export class LocalRuntime {
 
   tools() { return this.policyGate.names().filter((name) => name !== "server_info"); }
 
-  runtimeInfo() {
-    return buildRuntimeInfo({
+  runtimeInfo(context = {}) {
+    const info = buildRuntimeInfo({
       workspace: this.workspace,
-      displayPath: (value) => this.displayPath(value),
-      policy: this.policy,
+      displayPath: (value) => this.displayPath(value, context),
+      policy: this.effectivePolicy(context),
       toolNames: this.tools(),
       capabilityObserver: this.capabilityObserver,
       observability: this.observability,
@@ -214,6 +229,16 @@ export class LocalRuntime {
       processSessionManager: this.processSessionManager,
       managedJobManager: this.managedJobManager,
     });
+    return {
+      ...info,
+      security_audit: this.securityAudit.snapshot(),
+      trust: {
+        device_root: this.deviceRootStatus,
+        daemon_session: { ephemeral: true, certificate_lifetime_seconds: 86400, reconnect_prompts: false },
+        delegated_process_isolation: delegatedProcessIsolationStatus(),
+        routine_operation_prompts: false,
+      },
+    };
   }
 
   async start() {
@@ -427,20 +452,24 @@ export class LocalRuntime {
   }
 
   async projectOverview(context = {}) {
+    const effectivePolicy = this.effectivePolicy(context);
     return buildProjectOverview({
       workspace: this.workspace,
-      displayPath: (value) => this.displayPath(value),
-      policy: this.policy,
-      toolNames: this.tools(),
+      displayPath: (value) => this.displayPath(value, context),
+      policy: effectivePolicy,
+      toolNames: toolNamesForPolicy(effectivePolicy).filter((name) => name !== "server_info"),
+      daemonPolicy: this.policy,
+      daemonToolNames: this.tools(),
       capabilityObserver: this.capabilityObserver,
       listTopLevel: (callContext) => this.listDir(".", callContext),
-      runProcess: (...args) => this.runProcess(...args),
-      safeErrorMessage: (error) => this.safeErrorMessage(error),
+      runInternalProcess: (...args) => this.processExecutionService.runFixedInternal(...args),
+      gitExecutable: () => this.resolveGitExecutable(),
+      safeErrorMessage: (error) => this.safeErrorMessage(error, {}, context),
       throwIfCancelled: (callContext) => this.throwIfCancelled(callContext),
     }, context);
   }
 
-  listRoots() { return this.workspaceFileService.listRoots(); }
+  listRoots(context = {}) { return this.workspaceFileService.listRoots(context); }
 
   listDir(pathValue, context = {}) { return this.workspaceFileService.listDir(pathValue, context); }
 
@@ -482,6 +511,7 @@ export class LocalRuntime {
       runProcess: (...args) => this.runProcess(...args),
       probeShell: (callContext) => this.processExecutionService.probeShell(callContext),
       managedJobManager: this.managedJobManager,
+      relayStatus: () => this.relay?.status?.() || null,
       throwIfCancelled: (callContext) => this.throwIfCancelled(callContext),
     }, context);
   }
@@ -577,6 +607,10 @@ export class LocalRuntime {
     return this.processExecutionService.run(cmd, args, timeoutMs, allowFailure, maxOutputBytes, context, cwd, stdin);
   }
 
+  effectivePolicy(context = {}) {
+    return policyForContext(context, this.policy);
+  }
+
   resolvePath(inputPath = ".") {
     const raw = String(inputPath || ".");
     if (raw.includes("\0")) throw new Error("path contains a NUL byte");
@@ -599,14 +633,14 @@ export class LocalRuntime {
     return this.workspaceCanonicalPromise;
   }
 
-  async resolveExistingPath(inputPath = ".") {
+  async resolveExistingPath(inputPath = ".", context = {}) {
     const candidate = this.resolvePath(inputPath);
     const [workspace, canonical] = await Promise.all([this.canonicalWorkspace(), realpath(candidate)]);
-    if (!this.policy.unrestrictedPaths) assertContainedPath(workspace, canonical);
+    if (!this.effectivePolicy(context).unrestrictedPaths) assertContainedPath(workspace, canonical);
     return canonical;
   }
 
-  async resolveWritePath(inputPath = ".") {
+  async resolveWritePath(inputPath = ".", context = {}) {
     const candidate = this.resolvePath(inputPath);
     const candidateInfo = await lstat(candidate).catch(() => null);
     if (candidateInfo?.isSymbolicLink()) throw new Error("refusing to overwrite a symbolic link");
@@ -617,23 +651,23 @@ export class LocalRuntime {
       ancestor = parent;
     }
     const [workspace, canonicalAncestor] = await Promise.all([this.canonicalWorkspace(), realpath(ancestor)]);
-    if (!this.policy.unrestrictedPaths) assertContainedPath(workspace, canonicalAncestor);
+    if (!this.effectivePolicy(context).unrestrictedPaths) assertContainedPath(workspace, canonicalAncestor);
     const suffix = relative(ancestor, candidate);
     return suffix ? resolve(canonicalAncestor, suffix) : canonicalAncestor;
   }
 
-  displayPath(fullPath) {
+  displayPath(fullPath, context = {}) {
     const absolute = resolve(fullPath);
-    if (this.policy.exposeAbsolutePaths) return absolute;
+    if (this.effectivePolicy(context).exposeAbsolutePaths) return absolute;
     const shown = relative(this.workspace, absolute);
     const insideWorkspace = shown === "" || (!shown.startsWith(`..${sep}`) && shown !== ".." && !isAbsolute(shown));
     if (insideWorkspace) return shown ? shown.split(sep).join("/") : ".";
     return `<external-path:${sha256(absolute).slice(0, 12)}>`;
   }
 
-  safeErrorMessage(error, toolArgs = {}) {
+  safeErrorMessage(error, toolArgs = {}, context = {}) {
     const message = boundedErrorMessage(error);
-    if (this.policy.exposeAbsolutePaths) return message;
+    if (this.effectivePolicy(context).exposeAbsolutePaths) return message;
     return redactRuntimeErrorMessage(message, {
       error,
       toolArgs,
@@ -641,7 +675,7 @@ export class LocalRuntime {
       workspaceInput: this.workspaceInput,
       runtimeDir: this.runtimeDir,
       home: process.env.HOME || process.env.USERPROFILE || "",
-      displayPath: (value) => this.displayPath(value),
+      displayPath: (value) => this.displayPath(value, context),
     });
   }
 

package/src/local/secure-file.mjs

@@ -16,6 +16,9 @@ export function openRegularFileSync(file, flags, options = {}) {
   try {
     const info = fstatSync(fd);
     if (!info.isFile()) throw new Error(`${label} is not a regular file`);
+    if (options.rejectMultipleLinks === true && Number(info.nlink) > 1) {
+      throw new Error(`${label} must not have multiple hard links`);
+    }
     if (options.verifyPathIdentity === true) {
       const pathInfo = lstatSync(file);
       if (pathInfo.isSymbolicLink() || !pathInfo.isFile()) throw new Error(`${label} must be a regular file and not a symbolic link`);
@@ -39,7 +42,7 @@ function withRegularFileSync(file, flags, options, callback) {
 }
 
 export function chmodRegularFileSync(file, mode, label = "path") {
-  return withRegularFileSync(file, fsConstants.O_RDONLY, { label, chmod: mode }, () => undefined);
+  return withRegularFileSync(file, fsConstants.O_RDONLY, { label, chmod: mode, rejectMultipleLinks: true }, () => undefined);
 }
 
 export function readBoundedRegularFileSync(file, maxBytes, label = "path", options = {}) {
@@ -52,6 +55,7 @@ export function readBoundedRegularFileWithInfoSync(file, maxBytes, label = "path
   return withRegularFileSync(file, fsConstants.O_RDONLY, {
     label,
     verifyPathIdentity: options.verifyPathIdentity === true,
+    rejectMultipleLinks: options.rejectMultipleLinks === true,
   }, (fd, info) => {
     if (info.size > limit) throw new Error(`file exceeds ${limit} bytes`);
     options.afterOpen?.({ fd, info });

package/src/local/security-audit-log.mjs

@@ -0,0 +1,204 @@
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { replaceFileAtomicallySync } from "./exclusive-file.mjs";
+import { ensureOwnerOnlyDirectorySync, readBoundedRegularFileSync } from "./secure-file.mjs";
+import { withOwnerStateLock } from "./owner-state-lock.mjs";
+
+const SCHEMA_VERSION = 1;
+const MAX_EVENTS = 4096;
+const MAX_BYTES = 4 * 1024 * 1024;
+const HASH_PATTERN = /^[a-f0-9]{64}$/;
+
+export class SecurityAuditLog {
+  constructor({ root = "", now = Date.now } = {}) {
+    this.root = root ? path.resolve(root) : "";
+    this.file = this.root ? path.join(this.root, "security-audit.json") : "";
+    this.now = typeof now === "function" ? now : Date.now;
+    this.queue = Promise.resolve();
+    this.lastError = "";
+    if (this.file && existsSync(this.file)) {
+      try { this.readVerifiedState(); } catch (error) { this.lastError = errorClass(error); }
+    }
+  }
+
+  record(input = {}) {
+    if (!this.file) return Promise.resolve(false);
+    const operation = async () => {
+      try {
+        return await withOwnerStateLock(this.root, async () => {
+          const state = this.readVerifiedState();
+          const event = buildEvent(input, state, this.now());
+          state.events.push(event);
+          while (state.events.length > MAX_EVENTS) {
+            const removed = state.events.shift();
+            state.anchor = removed.hash;
+          }
+          writeState(this.file, state);
+          this.lastError = "";
+          return true;
+        }, {
+          purpose: "security-audit", fileName: "security-audit.lock", label: "security audit",
+        });
+      } catch (error) {
+        this.lastError = errorClass(error);
+        return false;
+      }
+    };
+    const result = this.queue.then(operation, operation);
+    this.queue = result.then(() => undefined, () => undefined);
+    return result;
+  }
+
+  snapshot() {
+    if (!this.file) return { enabled: false, healthy: true, retained: 0, maximum: MAX_EVENTS };
+    try {
+      const state = this.readVerifiedState();
+      return {
+        enabled: true,
+        healthy: !this.lastError,
+        retained: state.events.length,
+        maximum: MAX_EVENTS,
+        last_event_at: state.events.at(-1)?.timestamp || null,
+        last_error_class: this.lastError || null,
+        content_logged: false,
+        chain_verified: true,
+      };
+    } catch (error) {
+      return {
+        enabled: true,
+        healthy: false,
+        retained: 0,
+        maximum: MAX_EVENTS,
+        last_event_at: null,
+        last_error_class: errorClass(error),
+        content_logged: false,
+        chain_verified: false,
+      };
+    }
+  }
+
+  readVerifiedState() {
+    if (!existsSync(this.file)) return emptyState();
+    const raw = readBoundedRegularFileSync(this.file, MAX_BYTES, "security audit state");
+    let state;
+    try { state = JSON.parse(raw.toString("utf8")); } catch (error) {
+      throw new Error("security audit state is not valid JSON", { cause: error });
+    }
+    validateState(state);
+    let previous = state.anchor;
+    for (const event of state.events) {
+      if (event.previous_hash !== previous || event.hash !== eventHash(event)) {
+        throw new Error("security audit hash chain verification failed");
+      }
+      previous = event.hash;
+    }
+    return state;
+  }
+}
+
+function buildEvent(input, state, nowMs) {
+  const timestamp = new Date(Number(nowMs)).toISOString();
+  if (!Number.isFinite(Date.parse(timestamp))) throw new Error("security audit timestamp is invalid");
+  const principal = input.principal && typeof input.principal === "object" ? input.principal : {};
+  const event = {
+    sequence: state.next_sequence,
+    timestamp,
+    outcome: boundedToken(input.outcome, "unknown"),
+    tool: boundedToken(input.tool, "unknown"),
+    risk_category: boundedText(input.riskCategory, "ordinary operation", 160),
+    target_hash: HASH_PATTERN.test(String(input.targetHash || "")) ? String(input.targetHash) : null,
+    account_ref: principal.accountId ? privateReference(state.identity_salt, principal.accountId) : null,
+    client_ref: principal.clientId ? privateReference(state.identity_salt, principal.clientId) : null,
+    family_ref: principal.familyId ? privateReference(state.identity_salt, principal.familyId) : null,
+    account_version: Number.isSafeInteger(principal.accountVersion) ? principal.accountVersion : null,
+    role: boundedToken(principal.role, principal.kind === "local" ? "local" : "unknown"),
+    duration_ms: boundedNumber(input.durationMs),
+    input_bytes: boundedNumber(input.inputBytes),
+    output_bytes: boundedNumber(input.outputBytes),
+    error_code: input.errorCode ? boundedToken(input.errorCode, "unknown") : null,
+    previous_hash: state.events.at(-1)?.hash || state.anchor,
+  };
+  const completed = { ...event, hash: eventHash(event) };
+  state.next_sequence += 1;
+  return completed;
+}
+
+function emptyState() {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    identity_salt: randomBytes(32).toString("hex"),
+    anchor: randomBytes(32).toString("hex"),
+    next_sequence: 1,
+    events: [],
+  };
+}
+
+function validateState(state) {
+  if (!plainRecord(state) || state.schemaVersion !== SCHEMA_VERSION) throw new Error("security audit state schema is invalid");
+  if (!HASH_PATTERN.test(state.identity_salt) || !HASH_PATTERN.test(state.anchor)) throw new Error("security audit state identity is invalid");
+  if (!Number.isSafeInteger(state.next_sequence) || state.next_sequence < 1) throw new Error("security audit sequence is invalid");
+  if (!Array.isArray(state.events) || state.events.length > MAX_EVENTS || !state.events.every(validEvent)) {
+    throw new Error("security audit events are invalid");
+  }
+  if (state.events.length && state.next_sequence <= state.events.at(-1).sequence) throw new Error("security audit sequence did not advance");
+}
+
+function validEvent(event) {
+  return plainRecord(event)
+    && Number.isSafeInteger(event.sequence)
+    && event.sequence > 0
+    && Number.isFinite(Date.parse(String(event.timestamp || "")))
+    && typeof event.outcome === "string"
+    && typeof event.tool === "string"
+    && typeof event.risk_category === "string"
+    && (event.target_hash === null || HASH_PATTERN.test(event.target_hash))
+    && ["account_ref", "client_ref", "family_ref"].every((key) => event[key] === null || HASH_PATTERN.test(event[key]))
+    && (event.account_version === null || Number.isSafeInteger(event.account_version))
+    && typeof event.role === "string"
+    && Number.isFinite(event.duration_ms)
+    && Number.isFinite(event.input_bytes)
+    && Number.isFinite(event.output_bytes)
+    && (event.error_code === null || typeof event.error_code === "string")
+    && HASH_PATTERN.test(event.previous_hash)
+    && HASH_PATTERN.test(event.hash);
+}
+
+function eventHash(event) {
+  const value = { ...event };
+  delete value.hash;
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+
+function privateReference(salt, value) {
+  return createHash("sha256").update(salt).update("\0").update(String(value)).digest("hex");
+}
+
+function writeState(file, state) {
+  ensureOwnerOnlyDirectorySync(path.dirname(file));
+  const content = `${JSON.stringify(state)}\n`;
+  if (Buffer.byteLength(content) > MAX_BYTES) throw new Error("security audit state exceeds its size limit");
+  replaceFileAtomicallySync(file, content, { mode: 0o600 });
+}
+
+function boundedToken(value, fallback) {
+  const text = String(value || fallback).replace(/[^A-Za-z0-9._:-]/g, "_").slice(0, 128);
+  return text || fallback;
+}
+
+function boundedText(value, fallback, maximum) {
+  return String(value || fallback).replace(/[\r\n\t\u0000-\u001f\u007f]/g, " ").trim().slice(0, maximum) || fallback;
+}
+
+function boundedNumber(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? Math.min(Math.floor(number), Number.MAX_SAFE_INTEGER) : 0;
+}
+
+function errorClass(error) {
+  return String(error?.code || error?.name || "audit_error").replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 80);
+}
+
+function plainRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/src/local/service-convergence.mjs

@@ -1,14 +1,30 @@
 const DEFAULT_ATTEMPTS = 20;
 const DEFAULT_DELAY_MS = 100;
 
+export async function waitForActiveStatus(
+  readStatus,
+  { attempts = DEFAULT_ATTEMPTS, delayMs = DEFAULT_DELAY_MS, sleep = delay } = {},
+) {
+  return waitForStatus(readStatus, (status) => status?.active === true, { attempts, delayMs, sleep });
+}
+
 export async function waitForInactiveStatus(
   readStatus,
   { attempts = DEFAULT_ATTEMPTS, delayMs = DEFAULT_DELAY_MS, sleep = delay } = {},
+) {
+  return waitForStatus(readStatus, (status) => status?.active !== true, { attempts, delayMs, sleep });
+}
+
+export async function waitForStatus(
+  readStatus,
+  predicate,
+  { attempts = DEFAULT_ATTEMPTS, delayMs = DEFAULT_DELAY_MS, sleep = delay } = {},
 ) {
   if (typeof readStatus !== "function") throw new TypeError("readStatus must be a function");
+  if (typeof predicate !== "function") throw new TypeError("predicate must be a function");
   const maximum = Number.isInteger(attempts) && attempts > 0 ? attempts : DEFAULT_ATTEMPTS;
   let status = await readStatus();
-  for (let attempt = 1; status?.active === true && attempt < maximum; attempt += 1) {
+  for (let attempt = 1; !predicate(status) && attempt < maximum; attempt += 1) {
     await sleep(delayMs);
     status = await readStatus();
   }

package/src/local/service-ownership.mjs

@@ -0,0 +1,17 @@
+export async function stopOwnedPlatformService({
+  state,
+  inspectWorkspaceDaemon,
+  ownsPlatformAutostart,
+  stopPlatformService,
+} = {}) {
+  if (!state) throw new TypeError("service ownership check requires state");
+  if (typeof inspectWorkspaceDaemon !== "function") throw new TypeError("service ownership check requires inspectWorkspaceDaemon");
+  if (typeof ownsPlatformAutostart !== "function") throw new TypeError("service ownership check requires ownsPlatformAutostart");
+  if (typeof stopPlatformService !== "function") throw new TypeError("service ownership check requires stopPlatformService");
+  const daemon = inspectWorkspaceDaemon(state);
+  if (!ownsPlatformAutostart(daemon)) {
+    return { owned: false, stopped: false, daemon, provider: null };
+  }
+  const provider = await stopPlatformService();
+  return { owned: true, stopped: provider?.ok !== false, daemon, provider };
+}

package/src/local/service-restart-handoff.mjs

@@ -0,0 +1,50 @@
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { restartAutostart } from "./service.mjs";
+import { createLogger } from "./log.mjs";
+
+const DEFAULT_DELAY_MS = 300;
+const MAX_DELAY_MS = 5_000;
+
+export async function runServiceRestartHandoff(options = {}) {
+  const delayMs = boundedDelay(options.delayMs ?? process.argv[2]);
+  const restart = typeof options.restartAutostart === "function" ? options.restartAutostart : restartAutostart;
+  const sleep = typeof options.sleep === "function" ? options.sleep : delay;
+  const logger = options.logger || createLogger({ component: "service-restart", level: "warn", format: "json", stderrOnly: true });
+  await sleep(delayMs);
+  const result = await restart({ logger });
+  if (result?.ok !== true) {
+    const error = new Error(`service restart handoff failed (${result?.reason || result?.provider || "unknown"})`);
+    error.result = result;
+    throw error;
+  }
+  return result;
+}
+
+export async function serviceRestartHandoffMain(options = {}) {
+  const run = typeof options.run === "function"
+    ? options.run
+    : () => runServiceRestartHandoff(options.handoffOptions);
+  const logger = options.logger || createLogger({ component: "service-restart", level: "error", format: "json", stderrOnly: true });
+  try {
+    await run();
+    return 0;
+  } catch (error) {
+    logger.error("service restart handoff failed", { error_class: error?.code || error?.name || "execution_failed" });
+    return 1;
+  }
+}
+
+function boundedDelay(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return DEFAULT_DELAY_MS;
+  return Math.min(MAX_DELAY_MS, Math.max(50, Math.floor(parsed)));
+}
+
+function delay(milliseconds) {
+  return new Promise((resolvePromise) => { setTimeout(resolvePromise, milliseconds); });
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  process.exitCode = await serviceRestartHandoffMain();
+}