Skip to content

armgit / ODS

Public Imported from GitHub
0

ODS V3 Pre-Release: Public testing and refinement ahead of the official V3 launch. Turn your PC, Mac, or Linux box into a private AI server.

37.8 KB
Raw Blame
// One gateway-process admission barrier for every agent, including native/cron
// runs. Decisions and disk commits are synchronous: admission cannot interleave
// with acquiring the transition lease. Never retain hook conversation payloads.
import fs from 'node:fs';
import path from 'node:path';
import os from 'node:os';
import crypto from 'node:crypto';
import {spawnSync} from 'node:child_process';
import {readRuntimeSettings} from './settings-runtime-readback.mjs';
import {readRuntimeModel} from './model-runtime-readback.mjs';

const hex = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
const hash = value => crypto.createHash('sha256').update(value).digest('hex');
const revision = () => crypto.randomBytes(32).toString('hex');
const blocked = () => ({outcome: 'block', reason: 'ods-access-transition',
  message: 'Pixel access settings are changing. Retry when the transition completes.'});
const bootId = value => typeof value === 'string' && /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(value);

function processAlive(pid) {
  try { process.kill(pid, 0); return true; }
  catch (error) { if (error.code === 'ESRCH') return false; throw error; }
}

function structuredOwnerAlive(pid) {
  try { return processAlive(pid); }
  catch (error) {
    // process.json is a private, owner-created file and every structured lock
    // is written by this same uid. A still-live owner is therefore signalable.
    // EPERM means Linux has recycled the PID to a different security principal;
    // ProtectProc=invisible can also hide its /proc identity, so retaining that
    // foreign PID would otherwise disable admission permanently.
    if (error.code === 'EPERM') return false;
    throw error;
  }
}

function processStartTicks(pid) {
  let stat;
  try { stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8'); }
  catch (error) {
    if (error.code === 'ENOENT' && !processAlive(pid)) return null;
    throw error;
  }
  // comm can contain spaces and closing parentheses. Fields after its LAST
  // closing parenthesis begin at field 3; starttime is field 22, not wall time.
  const end = stat.lastIndexOf(')');
  const startTicks = stat.slice(end + 2).trim().split(/\s+/)[19];
  if (!stat.startsWith(`${pid} (`) || end < 0 || stat[end + 1] !== ' ' ||
      !/^(0|[1-9][0-9]*)$/.test(startTicks ?? '')) {
    throw new Error('process start identity unavailable');
  }
  return startTicks;
}

function processInvocation(pid) {
  // ProcSubset=pid hides boot_id. Read only this exact bounded environment
  // value; discard unrelated entries without retaining or reporting them.
  const prefix = Buffer.from('INVOCATION_ID='), fd = fs.openSync(`/proc/${pid}/environ`, 'r');
  const chunk = Buffer.alloc(4096);
  let matched = 0, value = '', found = null, bytes = 0;
  try {
    let count;
    while ((count = fs.readSync(fd, chunk, 0, chunk.length, null)) > 0) {
      bytes += count;
      if (bytes > 1048576) throw new Error('process environment identity unavailable');
      for (const byte of chunk.subarray(0, count)) {
        if (byte === 0) {
          if (matched === prefix.length) {
            if (found !== null || !/^[a-f0-9]{32}$/.test(value)) throw new Error('process invocation identity unavailable');
            found = value;
          }
          matched = 0; value = '';
        } else if (matched === prefix.length) {
          if (value.length >= 32) throw new Error('process invocation identity unavailable');
          value += String.fromCharCode(byte);
        } else if (matched >= 0) matched = byte === prefix[matched] ? matched + 1 : -1;
      }
    }
    if (matched !== 0 || found === null) throw new Error('process invocation identity unavailable');
    return found;
  } finally { chunk.fill(0); fs.closeSync(fd); }
}

function linuxProcessIdentity(pid, format = 'auto') {
  let boot;
  if (format !== 'invocation') {
    try { boot = fs.readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim(); }
    catch (error) {
      if (format !== 'auto' || !['ENOENT', 'EACCES', 'EPERM'].includes(error.code)) throw error;
    }
    if (boot !== undefined && !bootId(boot)) throw new Error('process boot identity unavailable');
  }
  const startTicks = processStartTicks(pid);
  if (startTicks === null) return null;
  if (boot !== undefined) {
    if (fs.readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim() !== boot) throw new Error('process boot identity changed');
    return {version: 2, pid, bootId: boot, startTicks};
  }
  const invocationId = processInvocation(pid);
  // Bind the environment read to one process incarnation, including exits
  // and PID reuse during the read. Never compare only our own invocation ID.
  if (processStartTicks(pid) !== startTicks) throw new Error('process invocation identity changed');
  return {version: 3, pid, invocationId, startTicks};
}

function provenManagedIngressReuse(pid, startTicks) {
  // WSL can reuse the old gateway PID in the same kernel tick after a distro
  // restart. Pixel ingress has a different, root-owned systemd service, but
  // ProtectHome can make its /proc/environ unreadable to the gateway owner.
  // Accept only this exact other managed role, then pin the same incarnation
  // across both reads. All unknown processes continue to fence admission.
  const groupPath = `/proc/${pid}/cgroup`, commandPath = `/proc/${pid}/cmdline`;
  const expectedGroup = '0::/system.slice/pixel-ingress.service\n';
  const expectedCommand = Buffer.from('node\0/usr/local/libexec/ods-pixel-ingress.mjs\0');
  try {
    const group = fs.readFileSync(groupPath, 'utf8');
    const command = fs.readFileSync(commandPath);
    return group === expectedGroup && Buffer.isBuffer(command) && command.equals(expectedCommand) &&
      processStartTicks(pid) === startTicks &&
      fs.readFileSync(groupPath, 'utf8') === group && fs.readFileSync(commandPath).equals(command);
  } catch { return false; }
}

function systemdUnitIdentity(unit) {
  const result = spawnSync('/usr/bin/systemctl', ['show', unit,
    '--property=MainPID,InvocationID,ExecStart,User,Group,ActiveState,FragmentPath,ExecMainStartTimestampMonotonic'],
  {encoding: 'utf8', timeout: 5000, maxBuffer: 4096});
  if (result.error || result.status !== 0 || typeof result.stdout !== 'string' || result.stdout.length > 4096) return null;
  const fields = Object.create(null);
  for (const line of result.stdout.trimEnd().split('\n')) {
    const separator = line.indexOf('=');
    if (separator < 1 || Object.hasOwn(fields, line.slice(0, separator))) return null;
    fields[line.slice(0, separator)] = line.slice(separator + 1);
  }
  return fields;
}

function provenManagedIngressBySystemd(previous, current) {
  if (previous.version !== 3 || current?.version !== 3) return false;
  // ProtectProc=invisible can hide every /proc entry for another systemd
  // service. Ask the root-owned manager for both exact unit identities; no
  // command is executed in the other process. A stable, separately invoked
  // ingress service cannot also be the old live gateway lock owner.
  const snapshot = () => ({gateway: systemdUnitIdentity('openclaw-gateway.service'),
    ingress: systemdUnitIdentity('pixel-ingress.service')});
  const first = snapshot(), second = snapshot();
  if (!first.gateway || !first.ingress || JSON.stringify(first) !== JSON.stringify(second)) return false;
  const {gateway, ingress} = first, owner = os.userInfo().username;
  return gateway.ActiveState === 'active' && gateway.MainPID === String(process.pid) &&
    gateway.InvocationID === current.invocationId && gateway.User === owner &&
    ingress.ActiveState === 'active' && ingress.MainPID === String(previous.pid) &&
    ingress.User === owner && ingress.Group === 'ods-pixel' &&
    ingress.FragmentPath === '/etc/systemd/system/pixel-ingress.service' &&
    /^[a-f0-9]{32}$/.test(ingress.InvocationID ?? '') &&
    ingress.InvocationID !== previous.invocationId && ingress.InvocationID !== current.invocationId &&
    /^[1-9][0-9]*$/.test(ingress.ExecMainStartTimestampMonotonic ?? '') &&
    Number.isSafeInteger(Number(ingress.ExecMainStartTimestampMonotonic)) &&
    /^\{ path=\/usr\/bin\/env ; argv\[\]=\/usr\/bin\/env node \/usr\/local\/libexec\/ods-pixel-ingress\.mjs ; ignore_errors=no ;/.test(ingress.ExecStart ?? '');
}

function systemdUnitOfPid(pid) {
  const result = spawnSync('/usr/bin/systemctl', ['whoami', String(pid)], {encoding: 'utf8', timeout: 5000, maxBuffer: 4096});
  if (result.error || result.status !== 0 || typeof result.stdout !== 'string') return null;
  const unit = result.stdout.trim();
  return /^[A-Za-z0-9:_.@-]+\.service$/.test(unit) ? unit : null;
}

function provenSiblingUnitBySystemd(previous, current) {
  if (previous.version !== 3 || current?.version !== 3) return false;
  // After a distro restart the boot order is repeatable, so the old gateway PID
  // can come back as any other same-owner ODS service, hidden from this gateway
  // by ProtectProc=invisible. Ask the manager which unit owns that PID. Its main
  // process was started for that unit's own invocation, so a different stable
  // InvocationID proves the recorded owner is gone. The gateway unit itself, a
  // non-main process, or an unattributed PID keeps admission held.
  const snapshot = () => {
    const unit = systemdUnitOfPid(previous.pid);
    return {unit, gateway: systemdUnitIdentity('openclaw-gateway.service'), sibling: unit && systemdUnitIdentity(unit)};
  };
  const first = snapshot(), second = snapshot();
  if (!first.unit || first.unit === 'openclaw-gateway.service' || !first.gateway || !first.sibling ||
      JSON.stringify(first) !== JSON.stringify(second)) return false;
  const {gateway, sibling} = first, owner = os.userInfo().username;
  return gateway.ActiveState === 'active' && gateway.MainPID === String(process.pid) &&
    gateway.InvocationID === current.invocationId && gateway.User === owner &&
    sibling.ActiveState === 'active' && sibling.MainPID === String(previous.pid) &&
    /^[a-f0-9]{32}$/.test(sibling.InvocationID ?? '') &&
    sibling.InvocationID !== previous.invocationId && sibling.InvocationID !== current.invocationId;
}

function provenReusedBySystemd(previous, current) {
  return provenManagedIngressBySystemd(previous, current) || provenSiblingUnitBySystemd(previous, current);
}

function previousProcessAlive(previous, currentIdentity) {
  if (!previous || Array.isArray(previous) || !Number.isSafeInteger(previous.pid) || previous.pid < 1) {
    throw new Error('invalid process lock');
  }
  const keys = Object.keys(previous).sort().join(',');
  // A live legacy record has no reliable start identity: never infer it stale.
  if (keys === 'pid') return processAlive(previous.pid);
  const boot = previous.version === 2 && keys === 'bootId,pid,startTicks,version' && bootId(previous.bootId);
  const invocation = previous.version === 3 && keys === 'invocationId,pid,startTicks,version' &&
    typeof previous.invocationId === 'string' && /^[a-f0-9]{32}$/.test(previous.invocationId);
  if ((!boot && !invocation) || typeof previous.startTicks !== 'string' ||
      !/^(0|[1-9][0-9]*)$/.test(previous.startTicks) || process.platform !== 'linux') throw new Error('unknown process lock identity');
  // Death is independently verifiable even if an older record used boot_id
  // and this gateway's namespace now hides it. A live unknown owner stays held.
  if (!structuredOwnerAlive(previous.pid)) return false;
  // A reused PID may belong to an unrelated process whose environment is
  // unreadable under proc restrictions. A different start time already proves
  // that the recorded owner is gone; do not require that stranger's identity.
  // Matching start times still require the full boot/invocation check below.
  let startTicks;
  try { startTicks = processStartTicks(previous.pid); }
  catch (error) {
    if (['ENOENT', 'EACCES', 'EPERM'].includes(error.code) &&
        provenReusedBySystemd(previous, currentIdentity)) return false;
    throw error;
  }
  if (startTicks !== previous.startTicks) return false;
  let current;
  try { current = linuxProcessIdentity(previous.pid, boot ? 'boot' : 'invocation'); }
  catch (error) {
    if (!boot && ['EACCES', 'EPERM'].includes(error.code) &&
        (provenManagedIngressReuse(previous.pid, previous.startTicks) ||
         provenReusedBySystemd(previous, currentIdentity))) return false;
    throw error;
  }
  return current !== null && current.startTicks === previous.startTicks &&
    (boot ? current.bootId === previous.bootId : current.invocationId === previous.invocationId);
}

export function executionHostForAgent(config, id = 'pixel') {
  const agents = config?.agents?.list?.filter(agent => agent?.id === id) ?? [];
  if (agents.length !== 1) throw new Error('Pixel agent configuration is ambiguous');
  const mode = agents[0].sandbox?.mode ?? config.agents?.defaults?.sandbox?.mode ?? 'off';
  const host = agents[0].tools?.exec?.host ?? config.tools?.exec?.host ?? 'sandbox';
  if (mode === 'off' && host === 'gateway') return 'gateway';
  if (mode === 'all' && host === 'sandbox') return 'sandbox';
  throw new Error('Pixel execution mode is unsupported');
}

export function createAccessRuntime({directory = path.join(os.homedir(), '.openclaw', '.ods-access-runtime'),
  config, settingsConfig, createTools, resolveSandbox, execControl, runtimeVersion = 'unknown', hooksAllowed = false,
  readProcessSessions, now = () => performance.now(),
  probeDirectory = path.join(process.platform === 'darwin' ? '/private/var/lib/ods-pixel-access-probes' :
    '/var/lib/ods-pixel-access-probes', String(process.getuid?.() ?? 'unsupported'))} = {}) {
  if (typeof process.getuid !== 'function') {
    const unavailable = () => { throw new Error('POSIX admission unavailable'); };
    return {status: () => ({available: false, phase: 'unavailable', revision: null, active: 0, proof: null}),
      admit: () => ({outcome: 'pass'}), finish() {}, beforeTool() {}, afterTool() {},
      acquire: unavailable, acquireMaintenance: unavailable, release: unavailable, releaseMaintenance: unavailable,
      probe: unavailable, readSettings: unavailable, readModel: unavailable,
      owns: () => false, isProbe: () => false};
  }
  // Admission coverage was inspected against these exact installed contracts.
  // Other releases keep normal guard behavior, but cannot change access until
  // their hook coverage is qualified. Held state always continues to block.
  const qualified = runtimeVersion === '2026.6.33' && hooksAllowed === true;
  const runs = new Set(), tools = new Set(), detached = new Map(), internalRuns = new Set();
  const transitionFailures = new WeakMap();
  const transitionError = code => {
    const failure = new Error('runtime transition refused');
    transitionFailures.set(failure, code);
    return failure;
  };
  const filename = path.join(directory, 'state.json');
  let state, failed = false, probeRun = null, proof = null, probeFailure = null;
  let maintenanceProof = null;
  let initializationStage = 'state-directory', initializationFailure = null;
  let processClaim = null;
  let processTimer = null, processCheck = null;
  const isInternal = context => (probeRun !== null && context?.runId === probeRun) || internalRuns.has(context?.runId);
  // Construct only the SDK's scoped process-list reader. Never execute a shell,
  // change the configured policy, or retain its command/output fields.
  const inspectProcesses = readProcessSessions ?? (typeof config === 'function' && typeof createTools === 'function'
    ? async context => {
      const cfg = config(), runId = `ods-access-process-check-${crypto.randomUUID()}`;
      const agent = cfg?.agents?.list?.find(item => item?.id === context.agentId);
      if (!agent) throw new Error('process scope unavailable');
      internalRuns.add(runId);
      try {
        const reader = createTools({config: cfg, agentId: context.agentId,
          sessionKey: context.sessionKey, sessionId: context.sessionId, runId,
          workspaceDir: agent.workspace, cwd: agent.workspace, oneShotCliRun: true})
          .find(tool => tool.name === 'process');
        if (!reader) throw new Error('process reader unavailable');
        const result = await reader.execute(runId, {action: 'list'});
        if (result?.isError || result?.details?.status !== 'completed' || !Array.isArray(result.details.sessions)) {
          throw new Error('process status unavailable');
        }
        return result.details.sessions.map(({sessionId, startedAt, status}) => ({sessionId, startedAt, status}));
      } finally { internalRuns.delete(runId); }
    } : null);
  function privateEntry(target, directoryEntry = false) {
    const s = fs.lstatSync(target);
    if (s.isSymbolicLink() || s.uid !== process.getuid() || (s.mode & 0o077) ||
        (directoryEntry ? !s.isDirectory() : !s.isFile() || s.nlink !== 1)) throw new Error('unsafe runtime state');
    return s;
  }
  function save() {
    privateEntry(directory, true);
    const temporary = path.join(directory, `.state-${revision()}`);
    let fd;
    try {
      fd = fs.openSync(temporary, 'wx', 0o600);
      fs.writeFileSync(fd, JSON.stringify(state)); fs.fsyncSync(fd); fs.closeSync(fd); fd = undefined;
      fs.renameSync(temporary, filename);
      const dir = fs.openSync(directory, 'r'); try { fs.fsyncSync(dir); } finally { fs.closeSync(dir); }
    } catch (error) { failed = true; throw error; }
    finally { if (fd !== undefined) fs.closeSync(fd); if (fs.existsSync(temporary)) fs.unlinkSync(temporary); }
  }
  function claimProcess() {
    if (!['linux', 'darwin'].includes(process.platform)) return {release() {}};
    // Linux requires util-linux /usr/bin/flock. The inherited descriptor shares
    // the parent's open file description, so its lock survives helper exit and
    // is released by close or gateway death, even during stale-record recovery.
    const claim = path.join(directory, '.process-claim');
    if (fs.existsSync(claim)) privateEntry(claim);
    // Darwin O_EXLOCK (sys/fcntl.h) acquires a descriptor-owned flock during
    // open. O_NONBLOCK refuses a competing owner without hanging the gateway.
    // Node does not expose O_EXLOCK by name; never apply its value on Linux.
    const macLock = process.platform === 'darwin' ? 0x20 | fs.constants.O_NONBLOCK : 0;
    const fd = fs.openSync(claim, fs.constants.O_CREAT | fs.constants.O_RDWR | fs.constants.O_NOFOLLOW | macLock, 0o600);
    try {
      const opened = fs.fstatSync(fd), current = privateEntry(claim);
      if (opened.dev !== current.dev || opened.ino !== current.ino) throw new Error('process claim changed');
      if (process.platform === 'linux') {
        const result = spawnSync('/usr/bin/flock', ['--exclusive', '--nonblock', '3'],
          {stdio: ['ignore', 'ignore', 'ignore', fd], timeout: 5000});
        if (result.error || result.status !== 0) throw new Error('process claim unavailable');
        return {release: () => fs.closeSync(fd)};
      }
      if (!Number.isSafeInteger(opened.dev) || opened.dev < 0 ||
          !Number.isSafeInteger(opened.ino) || opened.ino <= 0) throw new Error('process claim identity unavailable');
      return {release: () => fs.closeSync(fd), identity: [String(opened.dev), String(opened.ino)]};
    } catch (error) { fs.closeSync(fd); throw error; }
  }
  function ownerStamp(lock) {
    privateEntry(lock);
    const entry = fs.statSync(lock, {bigint: true});
    return [entry.dev, entry.ino, entry.birthtimeNs, entry.ctimeNs].map(value => value.toString());
  }
  const claimWitness = path.join(directory, 'process-claim.json');
  function witnessedDarwinOwner(lock, previous) {
    if (process.platform !== 'darwin' || !fs.existsSync(claimWitness)) return false;
    if (privateEntry(claimWitness).size > 4096) throw new Error('oversized process claim witness');
    const witness = JSON.parse(fs.readFileSync(claimWitness, 'utf8'));
    const stamp = (value, size) => Array.isArray(value) && value.length === size &&
      value.every(field => typeof field === 'string' && /^(0|[1-9][0-9]*)$/.test(field));
    if (!witness || Object.keys(witness).sort().join(',') !== 'claim,owner,pid,version' ||
        witness.version !== 1 || !Number.isSafeInteger(witness.pid) || witness.pid < 1 ||
        !stamp(witness.claim, 2) || !stamp(witness.owner, 4)) throw new Error('invalid process claim witness');
    // Older runtimes rewrite process.json but do not retain O_EXLOCK. Bind the
    // witness to the exact file incarnation, not just its recycled PID. A
    // stale witness after a downgrade cannot displace a live legacy gateway.
    return previous && Object.keys(previous).join(',') === 'pid' && previous.pid === witness.pid &&
      JSON.stringify(witness.claim) === JSON.stringify(processClaim.identity) &&
      JSON.stringify(witness.owner) === JSON.stringify(ownerStamp(lock));
  }
  function saveClaimWitness(lock) {
    if (process.platform !== 'darwin') return;
    const value = {version: 1, pid: process.pid, claim: processClaim.identity, owner: ownerStamp(lock)};
    const temporary = path.join(directory, `.claim-${revision()}`);
    const fd = fs.openSync(temporary, 'wx', 0o600);
    try { fs.writeFileSync(fd, JSON.stringify(value)); fs.fsyncSync(fd); }
    finally { fs.closeSync(fd); }
    fs.renameSync(temporary, claimWitness);
    const parent = fs.openSync(directory, 'r');
    try { fs.fsyncSync(parent); } finally { fs.closeSync(parent); }
  }
  try {
    if (!fs.existsSync(directory)) fs.mkdirSync(directory, {mode: 0o700});
    privateEntry(directory, true);
    const lock = path.join(directory, 'process.json');
    // Serialize inspection AND replacement, including the missing-lock case.
    // An inode check alone cannot prevent two stale claimants unlinking a new
    // live owner's record. Never unlink the reusable kernel-lock file.
    initializationStage = 'process-claim';
    processClaim = claimProcess();
    try {
      initializationStage = 'process-identity';
      const identity = process.platform === 'linux' ? linuxProcessIdentity(process.pid) : {pid: process.pid};
      if (!identity) throw new Error('current process identity unavailable');
      if (fs.existsSync(lock)) {
        const entry = privateEntry(lock);
        if (entry.size > 4096) throw new Error('oversized process lock');
        const previous = JSON.parse(fs.readFileSync(lock, 'utf8'));
        if (!witnessedDarwinOwner(lock, previous) && previousProcessAlive(previous, identity)) {
          throw new Error('another runtime owns admission');
        }
        const current = privateEntry(lock);
        if (current.dev !== entry.dev || current.ino !== entry.ino) throw new Error('process lock changed');
        fs.unlinkSync(lock);
      }
      const lockFd = fs.openSync(lock, 'wx', 0o600);
      try { fs.writeFileSync(lockFd, JSON.stringify(identity)); fs.fsyncSync(lockFd); }
      finally { fs.closeSync(lockFd); }
      saveClaimWitness(lock);
    } finally {
      // Darwin has no /proc start identity. Keep its exact kernel claim until
      // process exit, including when state is idle. Linux keeps its existing
      // boot/invocation identity and short registration lock.
      if (process.platform !== 'darwin') { processClaim.release(); processClaim = null; }
    }
    initializationStage = 'state-read';
    if (fs.existsSync(filename)) {
      privateEntry(filename);
      if (fs.statSync(filename).size > 4096) throw new Error('oversized runtime state');
      state = JSON.parse(fs.readFileSync(filename, 'utf8'));
      if (state.version !== 1 || !hex(state.revision) || !['idle','busy','held','interrupted'].includes(state.phase) ||
          !(state.tokenHash === null || hex(state.tokenHash))) throw new Error('invalid runtime state');
      if (state.phase === 'busy') state.phase = 'interrupted';
    } else state = {version: 1, phase: 'idle', revision: revision(), tokenHash: null};
    // Restart invalidates every previous runtime proof, even at identical config.
    initializationStage = 'state-save';
    state.revision = revision(); save();
  } catch {
    if (processClaim !== null) { processClaim.release(); processClaim = null; }
    failed = true; initializationFailure = initializationStage;
  }
  const busy = () => runs.size + tools.size + detached.size > 0;
  function changed() { state.revision = revision(); save(); }
  function scheduleProcessCheck() {
    if (processTimer !== null || processCheck !== null || failed || !qualified ||
        typeof inspectProcesses !== 'function' || ![...detached.values()].some(record => record.context)) return;
    processTimer = setTimeout(() => {
      processTimer = null;
      void reconcileDetached();
    }, 5000);
    processTimer.unref?.();
  }
  function reconcileDetached() {
    if (processCheck !== null) return processCheck;
    if (failed || !qualified || typeof inspectProcesses !== 'function') return Promise.resolve(status());
    if (processTimer !== null) { clearTimeout(processTimer); processTimer = null; }
    const pending = [...detached.entries()];
    processCheck = (async () => {
      for (const [sessionId, record] of pending) {
        if (!record.context || !Number.isSafeInteger(record.startedAt) || record.startedAt <= 0) continue;
        try {
          const sessions = await inspectProcesses(record.context);
          if (failed || detached.get(sessionId) !== record || !Array.isArray(sessions)) continue;
          const matches = sessions.filter(item => item?.sessionId === sessionId);
          // Absence, expiration, malformed results and a reused session ID do
          // not prove this particular process finished. Keep admission held.
          if (matches.length !== 1 || matches[0].startedAt !== record.startedAt ||
              !['completed', 'failed', 'exited'].includes(matches[0].status)) continue;
          detached.delete(sessionId);
          if (!busy() && state.phase === 'busy') state.phase = 'idle';
          changed();
        } catch { /* Keep the exact outstanding record and retry later. */ }
      }
      return status();
    })().finally(() => { processCheck = null; scheduleProcessCheck(); });
    return processCheck;
  }
  function status() {
    return {available: !failed && qualified, phase: failed ? 'unavailable' : state.phase,
      revision: failed ? null : state.revision, active: runs.size + tools.size + detached.size,
      activity: {runs: runs.size, tools: tools.size, detached: detached.size},
      pid: process.pid, runtime_version: runtimeVersion, proof, probe_failure: probeFailure,
      initialization_failure: initializationFailure,
      qualification_failure: qualified ? null : runtimeVersion !== '2026.6.33' ? 'runtime-version' : 'conversation-hooks'};
  }
  function admit(_event, context) {
    const id = context?.runId;
    if (failed || typeof id !== 'string' || !id || ['held','interrupted'].includes(state.phase)) return blocked();
    runs.add(id); state.phase = 'busy';
    try { changed(); } catch { return blocked(); }
    return {outcome: 'pass'};
  }
  function finish(event, context) {
    runs.delete(context?.runId ?? event?.runId);
    if (!failed && !busy() && state.phase === 'busy') { state.phase = 'idle'; changed(); }
  }
  function beforeTool(event, context) {
    if (isInternal(context)) return;
    if (failed || ['held','interrupted'].includes(state.phase)) return {block: true, blockReason: blocked().message};
    // Missing identities cannot be paired safely; fail closed before execution.
    if (!event?.toolCallId) return {block: true, blockReason: 'Tool identity unavailable during access coordination.'};
    tools.add(event.toolCallId); state.phase = 'busy'; changed();
  }
  function afterTool(event, context) {
    if (isInternal(context)) return;
    tools.delete(event?.toolCallId);
    const detail = event?.result?.details;
    let detachedChanged = false;
    if (event?.toolName === 'exec' && detail?.status === 'running' && detail.sessionId) {
      const scope = typeof context?.agentId === 'string' && context.agentId &&
        typeof context?.sessionKey === 'string' && context.sessionKey
        ? {agentId: context.agentId, sessionKey: context.sessionKey,
          ...(typeof context.sessionId === 'string' ? {sessionId: context.sessionId} : {})} : null;
      detached.set(detail.sessionId, {startedAt: detail.startedAt, context: scope});
      detachedChanged = true;
      scheduleProcessCheck();
    }
    if (event?.toolName === 'process' && event?.params?.sessionId &&
        ['completed','failed','exited'].includes(detail?.status) &&
        (Number.isInteger(detail.exitCode) || (typeof detail.exitSignal === 'string' && detail.exitSignal))) {
      detachedChanged = detached.delete(event.params.sessionId) || detachedChanged;
    }
    if (!failed) {
      if (!busy() && state.phase === 'busy') { state.phase = 'idle'; detachedChanged = true; }
      if (detachedChanged) changed();
    }
  }
  function acquire(token, expected) {
    if (failed || !qualified || !hex(token) || !hex(expected)) throw transitionError('native-transition-unavailable');
    if (state.phase === 'held' && state.tokenHash === hash(token)) {
      maintenanceProof = null; return status();
    }
    if (expected !== state.revision) throw transitionError('native-transition-revision-changed');
    // Preserve a bounded, non-forgeable reason for a refused transition.  The
    // controller exposes only this trusted token, never run/tool identifiers or
    // conversation data.  Distinguishing the owner class is essential on first
    // boot where a leaked startup run and a detached command require different
    // recovery paths.
    if (runs.size) throw transitionError('native-transition-busy-active-run');
    if (tools.size) throw transitionError('native-transition-busy-active-tool');
    if (detached.size) throw transitionError('native-transition-busy-detached-process');
    if (state.phase === 'held') throw transitionError('native-transition-busy-held');
    if (!['idle','interrupted'].includes(state.phase)) throw transitionError('native-transition-busy-phase');
    state.phase = 'held'; state.tokenHash = hash(token); proof = null; maintenanceProof = null; changed(); return status();
  }
  function maintenanceConfig() {
    const cfg = config(), current = typeof settingsConfig === 'function' ? settingsConfig() : cfg;
    const configHash = hash(JSON.stringify(cfg));
    if (hash(JSON.stringify(current)) !== configHash) throw new Error('runtime configuration changed');
    executionHostForAgent(current);
    return configHash;
  }
  function acquireMaintenance(token, expected, authority = null) {
    // Internal context maintenance only. Never exposed as an HTTP operation.
    if (maintenanceProof && owns(token)) {
      if (maintenanceProof.authority !== authority) throw new Error('runtime maintenance owner changed');
      return status();
    }
    const previous = proof ? structuredClone(proof) : null;
    let configHash = null;
    try { configHash = maintenanceConfig(); } catch { /* No valid proof to preserve. */ }
    const result = acquire(token, expected);
    if (previous?.executed === true && previous.pid === process.pid && configHash &&
        previous.config_sha256 === configHash) {
      maintenanceProof = {proof:previous, configHash, authority, tokenHash:hash(token), revision:state.revision,
        expiresAt:now() + 1920000};
    }
    return result;
  }
  function owns(token) { return !failed && hex(token) && state.phase === 'held' && state.tokenHash === hash(token); }
  function readSettings(token, expected) {
    // Bind readback to this process's current hold, not a token from before
    // restart or release. Keep it synchronous with admission and lease checks.
    if (!qualified || !owns(token) || !hex(expected) || expected !== state.revision || busy() || probeRun) {
      throw new Error('runtime lease mismatch');
    }
    // A registration-time snapshot can lag hot reload. Require the SDK's
    // current runtime getter; never fall back to disk or startup config.
    if (typeof settingsConfig !== 'function') throw new Error('runtime settings snapshot unavailable');
    return readRuntimeSettings(settingsConfig(), {pid: process.pid, runtimeVersion,
      revision: state.revision, observedAt: new Date().toISOString()});
  }
  function readModel(token, expected) {
    if (!qualified || failed || typeof settingsConfig !== 'function' ||
        token !== undefined && (!owns(token) || expected !== state.revision || busy() || probeRun)) {
      throw new Error('runtime model snapshot unavailable');
    }
    return readRuntimeModel(settingsConfig(), {pid:process.pid,revision:state.revision,observedAt:new Date().toISOString()});
  }
  function release(token) {
    if (!owns(token) || busy() || probeRun) throw new Error('runtime lease mismatch');
    maintenanceProof = null;
    state.phase = 'idle'; state.tokenHash = null; changed(); return status();
  }
  function releaseMaintenance(token, authority = null) {
    if (!owns(token) || busy() || probeRun) throw new Error('runtime lease mismatch');
    const saved = maintenanceProof;
    if (saved && saved.authority !== authority) {
      maintenanceProof = null;
      throw new Error('runtime maintenance owner changed');
    }
    let restored = null;
    try {
      if (!failed && qualified && saved?.tokenHash === hash(token) && saved.revision === state.revision &&
          saved.proof.pid === process.pid && now() < saved.expiresAt &&
          maintenanceConfig() === saved.configHash) restored = saved.proof;
    } catch { /* A changed/unavailable authority cannot restore the old proof. */ }
    // Validate before reopening admission. A failed durable release never
    // restores proof; the guard is process-local and cannot survive restart.
    release(token);
    proof = restored;
    return status();
  }
  async function probe(token) {
    if (!owns(token) || busy() || probeRun) throw new Error('runtime lease mismatch');
    maintenanceProof = null;
    probeFailure = null;
    const cfg = config();
    const agent = cfg.agents.list.find(entry => entry.id === 'pixel');
    const workspace = agent.workspace ?? cfg.agents.defaults?.workspace;
    if (!path.isAbsolute(workspace ?? '')) throw new Error('workspace unavailable');
    const executionHost = executionHostForAgent(cfg);
    const model = agent.model ?? cfg.agents.defaults?.model;
    const primary = typeof model === 'string' ? model : model?.primary;
    if (typeof primary !== 'string' || !primary.includes('/')) throw new Error('model policy identity unavailable');
    const modelProvider = primary.slice(0, primary.indexOf('/'));
    const modelId = primary.slice(primary.indexOf('/') + 1);
    const id = crypto.randomUUID(), sessionKey = `agent:pixel:ods-access-proof:${id}`;
    const runId = `ods-access-proof-${id}`;
    // Root provisions this empty owner-private fixture outside home/workspace.
    // Its host path is fixed by UID; callers cannot supply a write destination.
    const outside = probeDirectory;
    try { privateEntry(outside, true); }
    catch (error) { probeFailure = 'probe-directory-unavailable'; throw error; }
    const sentinel = path.join(outside, `sentinel-${id}`);
    const nonce = revision();
    probeRun = runId;
    let stage = 'sandbox-resolution';
    try {
      const sandbox = await resolveSandbox({config: cfg, sessionKey, workspaceDir: workspace});
      if ((executionHost === 'sandbox') !== Boolean(sandbox?.enabled)) throw new Error('sandbox runtime mismatch');
      stage = 'core-tool-construction';
      const allTools = createTools({config: cfg, agentId: 'pixel', sessionKey, runId, sessionId: id,
        workspaceDir: workspace, cwd: workspace, sandbox, modelProvider, modelId, oneShotCliRun: true});
      const exec = allTools.find(tool => tool.name === 'exec');
      const write = allTools.find(tool => tool.name === 'write');
      if (!exec || !write) throw new Error('required core tools unavailable');
      // These calls use the installed core tool constructors and unchanged
      // loaded policy. They do not request a model or accept arbitrary commands.
      const control = execControl();
      stage = 'core-exec';
      const command = control.prepare(runId, `printf '%s' '${nonce}'`);
      const result = await exec.execute(`proof-exec-${id}`, {command, timeout: 10});
      const text = result?.content?.filter(item => item.type === 'text').map(item => item.text).join('\n') ?? '';
      if (result?.isError || !text.includes(nonce) || result?.details?.status === 'running') throw new Error('core exec proof failed');
      stage = 'core-cancellation';
      const cancelledCommand = control.prepare(runId, 'sleep 30');
      let signalFailed = false;
      const timer = setTimeout(() => { try { control.signal(runId); } catch { signalFailed = true; } }, 250);
      let cancelled;
      try { cancelled = await exec.execute(`proof-cancel-${id}`, {command: cancelledCommand, timeout: 10, yieldMs: 10000}); }
      finally { clearTimeout(timer); }
      if (signalFailed || cancelled?.details?.exitCode !== 130) throw new Error('core cancellation proof failed');
      stage = 'filesystem-boundary';
      let writeDenied = false;
      try {
        const written = await write.execute(`proof-write-${id}`, {path: sentinel, content: nonce});
        writeDenied = written?.isError === true;
      } catch { writeDenied = true; }
      const present = fs.existsSync(sentinel) && fs.readFileSync(sentinel, 'utf8') === nonce;
      if (executionHost === 'gateway' ? (!present || writeDenied) : (present || !writeDenied)) throw new Error('filesystem boundary proof failed');
      proof = {mode: executionHost === 'gateway' ? 'full-access' : 'sandboxed', pid: process.pid,
        config_sha256: hash(JSON.stringify(cfg)), executed: true, at: new Date().toISOString()};
      return status();
    } catch (error) {
      // Fixed stage identifiers aid recovery without exposing commands,
      // credentials, private paths, or arbitrary provider diagnostics.
      probeFailure = stage;
      throw error;
    } finally {
      execControl().clear(runId); probeRun = null;
      // Only the unique directory and sentinel created by this probe.
      if (fs.existsSync(sentinel)) fs.unlinkSync(sentinel);
    }
  }
  return {status, admit, finish, beforeTool, afterTool, acquire, acquireMaintenance, release, releaseMaintenance,
    probe, owns, readSettings, readModel, reconcileDetached,
    classifyTransitionError: failure => transitionFailures.get(failure) ?? null, isProbe: isInternal};
}