@arcfold/dsh 0.0.0-stage → 0.4.0

package/src/runtime-lifecycle.mjs

@@ -0,0 +1,227 @@
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { mkdir, open, readFile, rename, stat } from 'node:fs/promises';
+import { createConnection } from 'node:net';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+
+export const RUNTIME_PROTOCOL = 'arcfold-runtime-v1';
+const hostEntry = fileURLToPath(new URL('./runtime-host.mjs', import.meta.url));
+const busy = error => ['EAGAIN', 'EWOULDBLOCK'].includes(error.code) && error.syscall === 'flock';
+const validRunId = value => typeof value === 'string' && /^[a-zA-Z0-9_-]{1,128}$/.test(value);
+export const lifecycleError = (code, message, details) => Object.assign(new Error(message), { code, details });
+export async function readRuntimeRecord(path) {
+  try { return JSON.parse(await readFile(path, 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+export async function writeRuntimeRecord(path, value, { exclusive = false } = {}) {
+  const temporary = exclusive ? path : join(dirname(path), '.runtime-' + randomUUID());
+  const file = await open(temporary, 'wx', 0o600);
+  try { await file.writeFile(JSON.stringify(value) + '\n'); await file.sync(); } finally { await file.close(); }
+  if (!exclusive) await rename(temporary, path);
+  const directory = await open(dirname(path), 'r');
+  try { await directory.sync(); } finally { await directory.close(); }
+}
+
+/** The lock file is never deleted. PID records do not confer ownership. */
+export async function acquireRuntimeLease(runtimeDirectory, { probe = false } = {}) {
+  if (!['darwin', 'linux'].includes(process.platform)) throw lifecycleError('unsupported_platform', 'The runtime owner requires POSIX flock.');
+  const { tryLockExclusive } = await import('@deepseek-ai/node-addon-system/flock');
+  if (!probe) await mkdir(runtimeDirectory, { recursive: true, mode: 0o700 });
+  const path = join(runtimeDirectory, 'owner.lock');
+  for (let attempt = 0; attempt < 3; attempt++) {
+    let handle;
+    try { handle = await open(path, constants.O_RDWR | constants.O_NOFOLLOW | (probe ? 0 : constants.O_CREAT), 0o600); }
+    catch (error) { if (probe && error.code === 'ENOENT') return null; throw error; }
+    try {
+      await tryLockExclusive(handle.fd);
+      const held = await handle.stat({ bigint: true }), current = await stat(path, { bigint: true }).catch(error => {
+        if (error.code === 'ENOENT') return null; throw error;
+      });
+      if (current && held.dev === current.dev && held.ino === current.ino) return handle;
+    } catch (error) {
+      await handle.close();
+      if (busy(error)) {
+        // A read-only status probe briefly holds the same kernel lock. Give that
+        // probe a bounded chance to release; never infer ownership from a PID.
+        if (!probe && attempt < 2) { await delay(10); continue; }
+        throw lifecycleError('already_running', 'This data directory already has a runtime owner.');
+      }
+      throw error;
+    }
+    await handle.close();
+  }
+  throw lifecycleError('owner_path_changed', 'The runtime lock changed while acquiring ownership.');
+}
+async function ownerHeld(runtimeDirectory) {
+  try { const lease = await acquireRuntimeLease(runtimeDirectory, { probe: true }); await lease?.close(); return false; }
+  catch (error) { if (error.code === 'already_running') return true; throw error; }
+}
+export async function runtimeControl(current, method, timeoutMs = 1000) {
+  if (!current || current.schema !== RUNTIME_PROTOCOL || !['status', 'stop', 'open'].includes(method) ||
+      !validRunId(current.runId) || current.controlAddress?.host !== '127.0.0.1' ||
+      !Number.isSafeInteger(current.controlAddress.port) || current.controlAddress.port < 1 || current.controlAddress.port > 65535)
+    throw lifecycleError('invalid_runtime_record', 'No valid current runtime control identity.');
+  const controlPath = join(current.dataRoot, 'runtime', 'runs', current.runId, 'control.json');
+  const file = await open(controlPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+  let control;
+  try {
+    const info = await file.stat();
+    if (!info.isFile() || info.uid !== process.getuid() || (info.mode & 0o777) !== 0o600 || info.size > 4096)
+      throw lifecycleError('invalid_control_owner', 'The runtime control identity is not a private user-owned file.');
+    control = JSON.parse(await file.readFile('utf8'));
+  } finally { await file.close(); }
+  if (control.schema !== RUNTIME_PROTOCOL || control.runId !== current.runId || control.dataRoot !== current.dataRoot ||
+      control.address?.host !== current.controlAddress.host || control.address?.port !== current.controlAddress.port ||
+      typeof control.token !== 'string' || !/^[a-f0-9]{64}$/.test(control.token))
+    throw lifecycleError('invalid_control_owner', 'The private runtime control identity does not match its public record.');
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(current.controlAddress); let data = '', settled = false;
+    const finish = (error, value) => { if (settled) return; settled = true; clearTimeout(timer); socket.destroy(); error ? reject(error) : resolve(value); };
+    const timer = setTimeout(() => finish(lifecycleError('control_timeout', 'The owned runtime did not answer.')), timeoutMs);
+    socket.on('error', error => finish(error));
+    socket.on('connect', () => socket.write(JSON.stringify({ schema: RUNTIME_PROTOCOL, runId: current.runId, dataRoot: current.dataRoot, method, token: control.token }) + '\n'));
+    socket.on('data', chunk => {
+      data += chunk; if (Buffer.byteLength(data) > 256 * 1024) return finish(lifecycleError('invalid_control_response', 'Runtime response is too large.'));
+      if (!data.includes('\n')) return;
+      try { const value = JSON.parse(data.slice(0, data.indexOf('\n')));
+        if (value.schema !== RUNTIME_PROTOCOL || value.runId !== current.runId || value.dataRoot !== current.dataRoot)
+          throw lifecycleError('runtime_identity_changed', 'Runtime control identity did not match.');
+        if (value.controlError) {
+          const messages = { unsupported_platform:'Opening the authenticated page is currently supported only on macOS.',
+            runtime_not_ready:'The runtime is not ready to open its page.', browser_open_failed:'The authenticated page could not be opened.' };
+          const code = value.controlError.code;
+          throw lifecycleError(Object.hasOwn(messages, code) ? code : 'invalid_control_response', messages[code] ?? 'The runtime control request failed.');
+        }
+        if (method === 'open' && value.opened !== true) throw lifecycleError('invalid_control_response', 'The runtime did not confirm opening its page.');
+        finish(null, method === 'open' ? { opened:true } : value);
+      } catch (error) { finish(error); }
+    });
+    socket.on('end', () => { if (!settled) finish(lifecycleError('control_closed', 'Runtime control closed without a complete response.')); });
+  });
+}
+
+/** Status reads existing files only; it neither initializes data nor signals PIDs. */
+export async function inspectOwnedRuntime(identity) {
+  const current = await readRuntimeRecord(join(identity.runtimeDirectory, 'current.json'));
+  if (current && (current.schema !== RUNTIME_PROTOCOL || current.dataRoot !== identity.dataRoot || !validRunId(current.runId)))
+    throw lifecycleError('invalid_runtime_record', 'Runtime metadata belongs to a different data directory.');
+  const held = await ownerHeld(identity.runtimeDirectory);
+  if (held) {
+    if (current) try { return { ...await runtimeControl(current, 'status'), ownerHeld: true }; } catch {}
+    return { schema: RUNTIME_PROTOCOL, dataRoot: identity.dataRoot, phase: 'unreachable', ownerHeld: true,
+      runId: null, lastKnownRunId: current?.runId ?? null, shutdownEvidence: 'unconfirmed' };
+  }
+  const receipt = current && await readRuntimeRecord(join(identity.runtimeDirectory, 'runs', current.runId, 'official-shutdown-returned.json'));
+  const failure = current && await readRuntimeRecord(join(identity.runtimeDirectory, 'runs', current.runId, 'failure.json'));
+  const confirmed = receipt?.runId === current?.runId && receipt?.dataRoot === identity.dataRoot && receipt?.kind === 'official-shutdown-returned';
+  return { schema: RUNTIME_PROTOCOL, dataRoot: identity.dataRoot, phase: 'stopped', ownerHeld: false,
+    runId: current?.runId ?? null, lastPhase: current?.phase ?? null, lastError: failure ?? current?.error ?? null,
+    shutdownEvidence: confirmed ? 'official-shutdown-returned' : current ? 'unconfirmed' : 'none',
+    shutdownReceipt: confirmed ? receipt : null };
+}
+const deadlineMs = value => {
+  const timeout = value ?? 60000;
+  if (!Number.isSafeInteger(timeout) || timeout < 100 || timeout > 600000) throw lifecycleError('invalid_timeout', 'Use a timeout between 100 and 600000 ms.');
+  return timeout;
+};
+export async function statusRuntime({ configPath }) {
+  const { loadRuntimeIdentity } = await import('./runtime-config.mjs');
+  return inspectOwnedRuntime(await loadRuntimeIdentity(configPath));
+}
+export async function openRuntime({ configPath, timeoutMs, signal }) {
+  if (process.platform !== 'darwin') throw lifecycleError('unsupported_platform', 'Opening the authenticated page is currently supported only on macOS.');
+  const timeout = deadlineMs(timeoutMs); signal?.throwIfAborted();
+  const { loadRuntimeIdentity } = await import('./runtime-config.mjs');
+  const identity = await loadRuntimeIdentity(configPath), before = await inspectOwnedRuntime(identity);
+  if (!before.ownerHeld) throw lifecycleError('runtime_not_running', 'Start Arcfold before opening its page.');
+  if (!before.runId || before.phase !== 'ready') throw lifecycleError('runtime_not_ready', 'The runtime is not ready to open its page.');
+  const current = await readRuntimeRecord(join(identity.runtimeDirectory, 'current.json'));
+  if (current?.runId !== before.runId) throw lifecycleError('runtime_identity_changed', 'The runtime owner changed before opening its page.');
+  signal?.throwIfAborted();
+  return runtimeControl(current, 'open', Math.min(timeout, 10000));
+}
+export async function startRuntime({ configPath, timeoutMs, signal }) {
+  const timeout = deadlineMs(timeoutMs); signal?.throwIfAborted();
+  const { loadRuntimePlan } = await import('./runtime-config.mjs');
+  const plan = await loadRuntimePlan(configPath), existing = await inspectOwnedRuntime(plan);
+  if (existing.ownerHeld) throw lifecycleError('already_running', 'This data directory already has a runtime owner.', existing);
+  const runId = randomUUID(), runDirectory = join(plan.runtimeDirectory, 'runs', runId);
+  await mkdir(runDirectory, { recursive: true, mode: 0o700 });
+  const launchFile = join(runDirectory, 'launch.json');
+  await writeRuntimeRecord(launchFile, { schema: RUNTIME_PROTOCOL, runId, runDirectory, plan }, { exclusive: true });
+  let output, errors, child, done, closed = false, exit, launchError;
+  try {
+    output = await open(join(runDirectory, 'stdout.log'), 'ax', 0o600);
+    errors = await open(join(runDirectory, 'stderr.log'), 'ax', 0o600);
+    child = spawn(process.execPath, [hostEntry, '--launch', launchFile], { cwd: plan.workspace, detached: true,
+      stdio: ['ignore', output.fd, errors.fd], env: { ...process.env, DSH_HOME: plan.nativeHome } });
+    child.once('error', error => { launchError = error; });
+    done = new Promise(resolveDone => child.once('close', (code, exitSignal) => { closed = true; exit = { code, signal: exitSignal }; resolveDone(exit); }));
+  } finally { await output?.close(); await errors?.close(); }
+  child.unref();
+  const ownStatePath = join(runDirectory, 'state.json');
+  const isOwnState = value => value?.schema === RUNTIME_PROTOCOL && value.runId === runId && value.dataRoot === plan.dataRoot &&
+    value.pid === child.pid && value.configurationHash === plan.configurationHash;
+  let childFailureObserved = false;
+  const deadline = Date.now() + timeout;
+  try {
+    for (;;) {
+      signal?.throwIfAborted(); if (launchError) throw launchError;
+      const own = await readRuntimeRecord(ownStatePath);
+      if (own && !isOwnState(own)) throw lifecycleError('invalid_runtime_record', 'The startup record does not belong to this child.');
+      if (own?.phase === 'failed') {
+        childFailureObserved = true;
+        throw lifecycleError(own.error?.code || 'startup_failed', own.error?.message || 'Runtime startup failed.', own);
+      }
+      if (own) {
+        const current = await inspectOwnedRuntime(plan);
+        if (current.ownerHeld && current.runId === runId && current.phase === 'ready') return current;
+      }
+      if (closed) throw lifecycleError('startup_exited', 'Runtime exited before validated readiness.', { exit, own });
+      if (Date.now() >= deadline) throw lifecycleError('startup_timeout', 'Runtime readiness was not confirmed before the deadline.', { runId });
+      await delay(50);
+    }
+  } catch (error) {
+    if (!closed && !childFailureObserved) {
+      const latest = await readRuntimeRecord(ownStatePath).catch(() => null);
+      childFailureObserved = isOwnState(latest) && latest.phase === 'failed';
+    }
+    // A ChildProcess handle from this call is the only PID signal authority.
+    // A verified failed child is already cleaning up. The official interrupt
+    // escalates an in-progress shutdown to immediate exit, so do not add one.
+    // Cancellation/timeout without that evidence still sends one SIGTERM only.
+    if (!closed && !childFailureObserved && child.pid) child.kill('SIGTERM');
+    let timer; try { await Promise.race([done, new Promise(resolveWait => { timer = setTimeout(resolveWait, 7000); })]); } finally { clearTimeout(timer); }
+    throw error;
+  }
+}
+export async function stopRuntime({ configPath, timeoutMs, signal }) {
+  const timeout = deadlineMs(timeoutMs); signal?.throwIfAborted();
+  const { loadRuntimeIdentity } = await import('./runtime-config.mjs');
+  const identity = await loadRuntimeIdentity(configPath), before = await inspectOwnedRuntime(identity);
+  if (!before.ownerHeld) return before;
+  if (!before.runId) throw lifecycleError('runtime_unreachable', 'An owner holds the data lock but its control identity is unavailable; no PID was signalled.', before);
+  const current = await readRuntimeRecord(join(identity.runtimeDirectory, 'current.json'));
+  if (current?.runId !== before.runId) throw lifecycleError('runtime_identity_changed', 'The runtime owner changed before stop.');
+  try { await runtimeControl(current, 'stop'); }
+  catch (error) {
+    const after = await inspectOwnedRuntime(identity);
+    if (!after.ownerHeld && after.runId === before.runId) return after;
+    throw lifecycleError('stop_unconfirmed', 'The single stop request was not acknowledged; no PID was signalled.', { runId: before.runId, cause: error.code });
+  }
+  const deadline = Date.now() + timeout;
+  for (;;) {
+    signal?.throwIfAborted(); const result = await inspectOwnedRuntime(identity);
+    if (result.runId && result.runId !== before.runId) throw lifecycleError('runtime_identity_changed', 'Another runtime owns this data after the stop request.');
+    if (!result.ownerHeld) return result;
+    if (Date.now() >= deadline) throw lifecycleError('stop_unconfirmed', 'Stop was requested once; release of ownership remains unconfirmed.', { runId: before.runId });
+    await delay(50);
+  }
+}
+export async function restartRuntime(options) {
+  const previous = await stopRuntime(options); options.signal?.throwIfAborted();
+  return { ...await startRuntime(options), previous };
+}

package/src/runtime-model-settings.mjs

@@ -0,0 +1,111 @@
+import { createModelSelectionHandler } from './model-selection.mjs';
+import { getRuntimeGuard, serviceIdentity } from './runtime-guard.mjs';
+import { runtimeTransport, runtimeRouteAvailability } from './runtime-config.mjs';
+import { runtimeMainAvailability } from './runtime-readiness.mjs';
+
+const choice = value => value ? { provider: value.provider, model: value.model,
+  reasoningEffort: value.reasoningEffort ?? null } : { provider: '', model: '', reasoningEffort: null };
+const defaultView = value => value ? { revision: value.revision, ...choice(value) } : null;
+const fail = (code, message) => { throw Object.assign(new Error(message), { code }); };
+const unavailable = reason => ({ available: false, reason });
+
+/** Read-only views and validated edits over existing native/business owners. */
+export function createRuntimeModelSettings(host, config, guard) {
+  const routes = runtimeTransport(config).routes;
+  const assertReady = () => guard.assertReady();
+  const assertLearningSelection = selected => {
+    // Startup can prepare an existing pending item before the outer stream gate
+    // opens. This grants no send: that gate and the final dispatch still apply.
+    const phase = guard.snapshot().phase;
+    if (!['starting', 'ready'].includes(phase)) assertReady();
+    if (!config.learn || !runtimeRouteAvailability({ ...config, learn: selected }).learn.available)
+      fail('learning_configuration_unavailable', '当前部署不允许这项学习模型设置。');
+  };
+  const assertMainSelection = async (_agent, selected) => {
+    assertReady();
+    const available = await runtimeMainAvailability(host.llm, config, selected);
+    assertReady();
+    if (!available.available) fail('model_selection_unavailable', '当前部署无法使用这项主模型设置。');
+  };
+  const catalog = async () => {
+    const native = await host.sessionController.modelCatalog();
+    return Object.entries(routes).map(([provider, route]) => {
+      const group = native.groups.find(group => group.id === provider);
+      return { provider, label: provider === 'openai' ? 'OpenAI' : 'DeepSeek', apiKeyRef: route.apiKeyRef,
+        models: (group?.models ?? []).flatMap(model => {
+          const policy = route.modelPolicies[model.id];
+          if (!policy) return [];
+          const efforts = (model.reasoning?.efforts ?? []).map(value => value.id)
+            .filter(value => policy.reasoningEfforts.includes(value));
+          return efforts.length ? [{ id: model.id, label: model.name, reasoningEfforts: efforts }] : [];
+        }) };
+    });
+  };
+  const usage = provider => {
+    const source = host.get('arcfoldMeteredTransport') ?? (provider === 'deepseek-official' ? host.get('arcfoldDeepSeekTransport') : null);
+    let value; try { value = source?.summary(provider); } catch { return null; }
+    if (!value) return null;
+    if (provider === 'openai') return { accounting: 'tokens_only', scope: value.scope,
+      requests: value.requests, unknownCount: value.unknownCount, pendingCount: value.pendingCount,
+      promptTokens: value.promptTokens, completionTokens: value.completionTokens, cachedTokens: value.cachedTokens };
+    return { accounting: 'cny', scope: value.scope, requests: value.requests, unknownCount: value.unknownCount,
+      spentCny: value.spentCny, reservedCny: value.reservedCny, ceilingCny: value.ceilingCny };
+  };
+  return Object.freeze({ assertLearningSelection, assertMainSelection,
+    async read() {
+      const defaults = host.get('arcfoldLearningDefaults');
+      const main = choice(host.agentDefaultModel.currentSelection()), learn = defaults?.read();
+      let list = [], mainAvailability, learnAvailability;
+      try { list = await catalog(); } catch { /* A stopped/failed catalog has no executable choices. */ }
+      try { mainAvailability = await runtimeMainAvailability(host.llm, config, main); }
+      catch { mainAvailability = unavailable('selected-model-controls-unavailable'); }
+      learnAvailability = config.learn && learn ? runtimeRouteAvailability({ ...config,
+        learn: { ...config.learn, ...choice(learn) } }).learn : unavailable('learn-not-configured');
+      const presence = {};
+      for (const [provider, route] of Object.entries(routes)) {
+        try { presence[provider] = (await host.credentials.describe(route.apiKeyRef)).configured === true; }
+        catch { presence[provider] = false; }
+      }
+      const withCredential = (available, selected) => available.available && !presence[selected?.provider]
+        ? unavailable('native-credential-not-configured') : available;
+      mainAvailability = withCredential(mainAvailability, main); learnAvailability = withCredential(learnAvailability, learn);
+      const gate = guard.snapshot(), currentMain = choice(host.agentDefaultModel.currentSelection()), currentLearn = defaults?.read();
+      if (JSON.stringify(currentMain) !== JSON.stringify(main)) mainAvailability = unavailable('native-selection-changed-during-status');
+      if (currentLearn?.revision !== learn?.revision) learnAvailability = unavailable('learning-selection-changed-during-status');
+      if (gate.phase !== 'ready') mainAvailability = learnAvailability = unavailable('runtime-not-ready');
+      return { gate, main: { defaultSelection: currentMain, availability: mainAvailability },
+        learning: { enabled: Boolean(config.learn && defaults), defaults: defaultView(currentLearn), availability: learnAvailability },
+        routes: list.map(route => ({ ...route, usage: usage(route.provider) })) };
+    },
+    async saveLearning(request, assertCaller = () => {}) {
+      assertCaller(); assertReady();
+      const defaults = host.get('arcfoldLearningDefaults');
+      if (!config.learn || !defaults) fail('learning_configuration_unavailable', '当前部署尚未启用独立学习。');
+      // The default service owns exact field/revision checks. Catalog reads may
+      // await, so current authorization and revision are checked again at save.
+      const list = await catalog();
+      const model = list.find(route => route.provider === request?.provider)?.models.find(model => model.id === request?.model);
+      if (!model?.reasoningEfforts.includes(request?.reasoningEffort))
+        fail('learning_configuration_unavailable', '所选模型或思考强度不在当前可用目录中。');
+      assertCaller(); assertReady();
+      return defaultView(defaults.save(request));
+    },
+  });
+}
+
+export const name = 'arcfold-runtime-model-settings';
+export const inject = ['arcfoldRuntimeGuard', 'arcfoldBusiness', 'sessions', 'sessionController',
+  'agentDefaultModel', 'llm', 'credentials', 'configEditor'];
+export function apply(ctx, { runtime } = {}) {
+  const config = structuredClone(runtime), guard = getRuntimeGuard(ctx);
+  const service = createRuntimeModelSettings(ctx, config, guard);
+  const handler = createModelSelectionHandler({ sessions: ctx.sessions, defaults: ctx.agentDefaultModel,
+    assertSelection: service.assertMainSelection });
+  let active = true;
+  const dispose = ctx.on('session/select-model', payload => handler(payload));
+  ctx.effect(() => () => { active = false; dispose(); }, 'remove native idle model selection');
+  ctx.provide('arcfoldRuntimeModels', Object.freeze({ ...service,
+    identity: Object.freeze({ fiber: ctx.fiber, controller: serviceIdentity(ctx.sessionController),
+      defaults: serviceIdentity(ctx.agentDefaultModel), sessions: serviceIdentity(ctx.sessions),
+      hookActive: () => active }) }));
+}

package/src/runtime-readiness.mjs

@@ -0,0 +1,285 @@
+import { assertPreparationComposition } from './preparation-plugin.mjs';
+import * as NativeGoalDriver from '@deepseek-ai/dsh-goal-round-driver';
+import { readFileSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './store.mjs';
+import { assertOpenAIIdentity, serviceIdentity } from './runtime-guard.mjs';
+import { canonicalRuntimePath, runtimeProviderDefaults, runtimeRouteAvailability, runtimeTransport } from './runtime-config.mjs';
+
+const CORE = '@arcfold/dsh', UI = '@arcfold/dsh-method-ui';
+const ACTIVE = 2;
+const SERVICES = ['llm', 'sessions', 'sessionPersistence', 'arcfoldBusiness', 'arcfoldBridge', 'arcfoldWork',
+  'arcfoldOpportunities', 'arcfoldPreparation', 'arcfoldOpportunityWeb', 'arcfoldMethods', 'arcfoldGoals', 'arcfoldMethodWeb', 'arcfoldGoalWeb', 'agentPresets', 'pluginPackages',
+  'clientModules', 'webApp', 'connection', 'credentials', 'agentDefaultModel', 'sessionController', 'configEditor', 'settings',
+  'arcfoldRuntimeWorkspace', 'workspaceRegistry', 'workspaceController', 'arcfoldRuntimeModels', 'arcfoldModelWeb'];
+const required = (condition, message) => { if (!condition) throw new Error(message); };
+
+/** Loader keeps the thenable returned by registry.plugin; ownership belongs to its underlying Fiber. */
+export function actualRuntimeFiber(entry, root) {
+  const wrapper = entry?.fiber, actual = wrapper?.ctx.fiber;
+  required(!entry?.disabled && actual?.state === ACTIVE && actual.ctx.root === root && actual.entry === entry &&
+    (wrapper === actual || Object.getPrototypeOf(wrapper) === actual),
+  `Required component is not active in this host: ${entry?.options.id ?? 'unknown'}`);
+  return actual;
+}
+
+// The official driver is global on loading/teardown, even when mounted in a
+// scoped preset. Require exactly its root entry and reject every preset copy.
+export async function inspectNativeContinuationDriver(ctx, entries, compositions) {
+  const name = '@deepseek-ai/dsh-goal-round-driver';
+  const drivers = entries.filter(entry => entry.options.id === 'goal-round-driver' ||
+    entry.options.name === name || entry.moduleNamespace?.apply === NativeGoalDriver.apply);
+  required(drivers.length === 1, 'Expected one root native goal driver');
+  const entry = drivers[0];
+  required(entry.options.id === 'goal-round-driver' && entry.options.name === name &&
+    entry.moduleNamespace?.apply === NativeGoalDriver.apply,
+  'Native goal driver does not use the verified official module');
+  for (const composition of compositions) for (const module of composition.modules) {
+    required(module.moduleName !== name, 'A preset must not contain another native goal driver');
+    // Preset inspection exposes its original specifier/base, not its private
+    // Loader tree. Use the same public loader import/normalization for aliases.
+    const owner = module.baseUrl ? ctx.extend({ baseUrl: module.baseUrl }) : ctx;
+    const loaded = await owner.loader.import(module.moduleName);
+    const plugin = owner.loader.unwrapExports(loaded);
+    required(plugin !== NativeGoalDriver.apply && plugin?.apply !== NativeGoalDriver.apply,
+      'A preset must not contain another native goal driver through a module alias');
+  }
+  const actual = actualRuntimeFiber(entry, ctx.root);
+  for (const service of ['agents', 'goals', 'sessions'])
+    required(actual.committed?.[service]?.value === serviceIdentity(ctx.get(service)),
+      'Native goal driver is bound to a different host service');
+  return actual;
+}
+
+/** Resolve only the verified local adapter's defaults; unknown routes are never probed. */
+export async function runtimeMainAvailability(llm, config, selection) {
+  if (!selection?.provider || !selection?.model) return { available: false, reason: 'main-not-configured' };
+  if (!Object.hasOwn(runtimeTransport(config).routes[selection.provider]?.modelPolicies ?? {}, selection.model))
+    return { available: false, reason: 'selected-route-not-supported' };
+  const defaults = runtimeProviderDefaults(config, selection.provider);
+  if (!defaults.available) return { available: false, reason: defaults.reason };
+  let resolved;
+  try { resolved = await llm.resolveCallConfig(selection); }
+  catch { return { available: false, reason: 'selected-model-controls-unavailable' }; }
+  required(resolved.provider === selection.provider && resolved.model === selection.model,
+    'The model capability lookup replaced the selected route');
+  if (config.main && resolved.maxTokens !== config.main.maxTokens)
+    return { available: false, reason: 'main-output-limit-unavailable',
+      requestedMaxTokens: config.main.maxTokens, resolvedMaxTokens: resolved.maxTokens ?? null };
+  return runtimeRouteAvailability({ ...config, main: resolved }).main;
+}
+
+/** Fresh status projection only: no arm, config write, retry, or secret resolution. */
+export async function refreshRuntimeReadiness(ctx, plan) {
+  const unavailable = reason => ({ available: false, reason });
+  const gateView = guard => guard?.snapshot() ?? { phase: 'unavailable', reason: 'guard-unavailable' };
+  const blocked = (gate, reason = gate.phase === 'requires-restart' ? 'runtime-restart-required' : 'runtime-not-ready') => ({
+    mode: 'configuration-only', modelGate: gate,
+    routeAvailability: { main: unavailable(reason), learn: unavailable(reason), credentialConfigured: false,
+      providerCredentialValidated: false, mainSelectionScope: 'native-default' }, issues: [reason],
+  });
+  let guard;
+  try {
+    guard = ctx.get('arcfoldRuntimeGuard');
+    let gate = gateView(guard);
+    if (gate.phase !== 'ready') return blocked(gate);
+    const defaults = ctx.get('agentDefaultModel'), llm = ctx.get('llm'), credentials = ctx.get('credentials');
+    required(defaults && llm && credentials, 'Runtime model settings are unavailable');
+    const selection = defaults.currentSelection();
+    const selectionKey = value => JSON.stringify([value.provider, value.model, value.reasoningEffort]);
+    const before = selectionKey(selection);
+    let main = await runtimeMainAvailability(llm, plan.config, selection);
+    const learningDefaults = ctx.get('arcfoldLearningDefaults');
+    const savedLearn = learningDefaults?.read();
+    const learnSelection = savedLearn && plan.config.learn ? { ...plan.config.learn,
+      provider: savedLearn.provider, model: savedLearn.model, reasoningEffort: savedLearn.reasoningEffort } : null;
+    let learn = runtimeRouteAvailability({ ...plan.config, learn: learnSelection }).learn;
+    const routes = runtimeTransport(plan.config).routes;
+    const providers = {};
+    for (const [provider, route] of Object.entries(routes)) providers[provider] = {
+      credentialConfigured: (await credentials.describe(route.apiKeyRef)).configured === true, providerCredentialValidated: false,
+    };
+    const credentialConfigured = providers[selection.provider]?.credentialConfigured === true;
+    const withCredential = (value, selected) => value.available && !providers[selected?.provider]?.credentialConfigured
+      ? { ...value, available: false, reason: 'native-credential-not-configured', credentialConfigured: false }
+      : { ...value, credentialConfigured: providers[selected?.provider]?.credentialConfigured === true };
+    main = withCredential(main, selection); learn = withCredential(learn, learnSelection);
+    // An asynchronous metadata read cannot advertise the earlier topology or
+    // selection after a live native edit. The next status call may read again.
+    gate = gateView(guard);
+    if (ctx.get('arcfoldRuntimeGuard') !== guard || gate.phase !== 'ready') return blocked(gate);
+    const latestSelection = ctx.get('agentDefaultModel')?.currentSelection();
+    if (!latestSelection || selectionKey(latestSelection) !== before)
+      main = unavailable('native-selection-changed-during-status');
+    if (learningDefaults !== ctx.get('arcfoldLearningDefaults') || learningDefaults?.read()?.revision !== savedLearn?.revision)
+      learn = unavailable('learning-selection-changed-during-status');
+    const issues = [!main.available && main.reason, !learn.available && learn.reason,
+      plan.config.transport && !credentialConfigured && 'native-credential-not-configured'].filter(Boolean);
+    return { mode: main.available && credentialConfigured ? 'execution-ready' : 'configuration-only', modelGate: gate,
+      routeAvailability: { main, learn, credentialConfigured, providerCredentialValidated: false,
+        mainSelectionScope: 'native-default', providers }, issues };
+  } catch {
+    return blocked(gateView(guard), 'runtime-readiness-unavailable');
+  }
+}
+
+/** Verify only fixed local modules and receipts, not model endpoints or secrets.
+ * Shared by full startup and the real-plugin focused ownership fixtures. */
+export async function inspectRuntimeProviders(ctx, plan, criticalFibers) {
+  const routes = runtimeTransport(plan.config).routes;
+  const providers = Object.keys(routes).filter(provider => runtimeProviderDefaults(plan.config, provider).available).sort();
+  required(canonicalJson(ctx.llm.listProviders().map(value => value.id).sort()) === canonicalJson(providers),
+    'The running model routes differ from the installed metered routes');
+  const shared = plan.config.schema === 'arcfold-local-v2';
+  for (const provider of providers) {
+    const openai = provider === 'openai';
+    const proof = plan.installation.providers?.[provider] ?? (!openai ? plan.installation.provider : undefined);
+    required(proof?.path, `The installation has no actual consuming-copy proof for ${provider}`);
+    const importer = pathToFileURL(join(plan.installation.coreRoot, 'src', openai ? 'openai-provider.mjs' : 'deepseek-provider.mjs')).href;
+    const packageName = openai ? '@deepseek-ai/dsh-llm-pi-ai' : '@deepseek-ai/dsh-llm-deepseek';
+    const actual = ctx.pluginPackages.packageOf(packageName, importer);
+    required(actual && realpathSync(actual.dir) === realpathSync(proof.path), `The ${provider} wrapper resolves to an unverified copy`);
+    const moduleURL = pathToFileURL(join(actual.dir, 'lib/index.js')).href;
+    const loaded = await import(moduleURL);
+    if (openai) {
+      required(shared && typeof proof.receiptSHA256 === 'string' && /^[a-f0-9]{64}$/.test(proof.receiptSHA256) && proof.receipt,
+        'OpenAI requires a new exact installation patch receipt');
+      const receiptBytes = readFileSync(proof.receipt);
+      required(createHash('sha256').update(receiptBytes).digest('hex') === proof.receiptSHA256, 'The OpenAI installation receipt changed');
+      const inspector = await import(new URL('../scripts/patch-pi-ai-transport.mjs', import.meta.url));
+      required(inspector.inspectPiAiPatch(actual.dir).state === 'patched' && proof.patchId === inspector.patchSpec.id &&
+        loaded.PiAiAdapter.transportSeam === 'pi-ai-create-transport-v2', 'The actual OpenAI consuming copy lacks the exact loaded interface');
+      const wrapper = criticalFibers['arcfold-openai-provider'];
+      const llm = [...criticalFibers.llm.provisions].find(record => record.name === 'llm');
+      const metered = [...criticalFibers['arcfold-shared-metered-host'].provisions].find(record => record.name === 'arcfoldMeteredTransport');
+      const identity = assertOpenAIIdentity(ctx.root, wrapper, llm, metered);
+      required(realpathSync(fileURLToPath(identity.moduleURL)) === realpathSync(fileURLToPath(moduleURL)) &&
+        identity.nativeFiber.runtime.callback === loaded.apply,
+        'The running native OpenAI child is not the verified installed module');
+      criticalFibers['arcfold-openai-native'] = identity.nativeFiber;
+    } else {
+      const inspector = await import(new URL('../scripts/patch-deepseek-transport.mjs', import.meta.url));
+      required(inspector.inspectDeepSeekPatch(actual.dir).state === 'patched' && proof.patchId === inspector.patchSpec.id &&
+        loaded.registerDeepSeekProvider.transportSeam === 'deepseek-messages-create-transport-v1', 'The loaded DeepSeek provider lacks metered dispatch');
+    }
+  }
+  return providers;
+}
+
+
+/** Check the actual official profile consumer and the one owned settings hook. */
+export async function inspectRuntimeModelSelection(ctx, plan, criticalFibers) {
+  const proof = plan.installation.modelSelection;
+  required(proof?.path && proof.receipt && /^[a-f0-9]{64}$/.test(proof.receiptSHA256 ?? ''),
+    'This installed version has no native model-selection patch proof');
+  const parent = pathToFileURL(join(plan.installation.profileDir, 'cordis.yml')).href;
+  const actual = ctx.pluginPackages.packageOf('@deepseek-ai/dsh-api-session-controller', parent);
+  required(actual && realpathSync(actual.dir) === realpathSync(proof.path), 'The native controller uses an unverified consuming copy');
+  required(createHash('sha256').update(readFileSync(proof.receipt)).digest('hex') === proof.receiptSHA256,
+    'The native controller patch receipt changed');
+  const inspector = await import(new URL('../scripts/patch-model-selection.mjs', import.meta.url));
+  const loaded = await import(pathToFileURL(join(actual.dir, 'lib/index.js')).href);
+  required(inspector.inspectModelSelectionPatch(actual.dir).state === 'patched' && proof.patchId === inspector.patchSpec.id &&
+    loaded.SessionController.modelSelectionSeam === 'session-model-selection-commit-v1' &&
+    serviceIdentity(ctx.sessionController).constructor === loaded.SessionController,
+    'The running native controller lacks the verified model-selection interface');
+  const modelFiber = criticalFibers['arcfold-runtime-model-settings'];
+  const matches = [...modelFiber.provisions].filter(value => value.name === 'arcfoldRuntimeModels');
+  const models = serviceIdentity(ctx.arcfoldRuntimeModels), identity = models.identity;
+  required(matches.length === 1 && matches[0].value === models && Object.isFrozen(identity) &&
+    identity.fiber === modelFiber && identity.hookActive() === true &&
+    identity.controller === serviceIdentity(ctx.sessionController) && identity.defaults === serviceIdentity(ctx.agentDefaultModel) &&
+    identity.sessions === serviceIdentity(ctx.sessions), 'The required native model selection handler is not owned by this runtime');
+  const defaults = criticalFibers['agent-default-model'];
+  required(defaults.entry && ctx.configEditor.entries().includes(defaults.entry) &&
+    canonicalRuntimePath(ctx.configEditor.documentPath) === canonicalRuntimePath(join(plan.nativeHome, 'arcfold.patch.yml')),
+    'The native model default has no verified persistent profile editor');
+}
+
+/** Observe the actual official host; this does not send a model or resolve a secret. */
+export async function inspectRuntimeReady(ctx, plan) {
+  const guard = ctx.get('arcfoldRuntimeGuard');
+  required(guard, 'The root-owned model guard is absent');
+  try {
+    const expectedAdapterUpdates = guard.snapshot().adapterUpdates;
+    const services = Object.fromEntries(SERVICES.map(name => [name, ctx.get(name)]));
+    for (const name of SERVICES) required(services[name], `Required runtime service is not active: ${name}`);
+    const loader = ctx.get('loader'); required(loader, 'Official loader is absent');
+    const entries = [...loader.entries()];
+    const entry = id => {
+      const matches = entries.filter(value => value.options.id === id);
+      required(matches.length === 1, `Expected one actual component: ${id}`);
+      return matches[0];
+    };
+    const fiber = id => actualRuntimeFiber(entry(id), ctx.root);
+    const profile = ctx.get('profileContext');
+    required(profile && realpathSync(profile.dir) === plan.installation.profileDir &&
+      realpathSync(profile.installAnchor) === plan.installation.installAnchor &&
+      realpathSync(profile.home) === plan.nativeHome && realpathSync(profile.cwd) === plan.workspace,
+    'The host is using a different profile, data home, installation or workspace');
+    const parent = pathToFileURL(join(plan.installation.profileDir, 'package.json')).href;
+    const packages = services.pluginPackages;
+    for (const [name, directory] of [[CORE, plan.installation.coreRoot], [UI, plan.installation.uiRoot]])
+      required(realpathSync(packages.packageOf(name, parent)?.dir ?? '') === directory, `Actual loaded package differs: ${name}`);
+    const uiPath = services.clientModules.clientPath(UI);
+    required(uiPath && realpathSync(uiPath).startsWith(plan.installation.uiRoot + '/'), 'The installed UI client is absent');
+    required(services.clientModules.graph().entries.filter(value => value.id === UI).length === 1, 'The UI module is absent or duplicated');
+    const typert = ctx.get('typert');
+    for (const endpoint of ['arcfoldMethods/list', 'arcfoldMethods/decide', 'arcfoldGoals/list', 'arcfoldGoals/decide',
+      'arcfoldOpportunities/list', 'arcfoldOpportunities/savePermission', 'arcfoldOpportunities/prepare', 'arcfoldOpportunities/continue',
+      'session/modelCatalog', 'session/selectModel', 'arcfoldModels/read', 'arcfoldModels/saveLearning'])
+      required(typert?.local.get(endpoint), `The actual UI endpoint is missing: ${endpoint}`);
+    const presets = await services.agentPresets.list();
+    for (const id of ['arcfold-main', 'arcfold-learning', 'arcfold-preparation'])
+      required(presets.filter(value => value.id === id && !value.broken).length === 1, `Required preset is missing: ${id}`);
+    const compositions = services.agentPresets.inspectCompositions();
+    required(compositions.find(value => value.id === 'arcfold-main')?.modules.some(value => value.moduleName === '@arcfold/dsh/agent'),
+      'The native main preset lacks Arcfold ownership');
+    required(!compositions.find(value => value.id === 'arcfold-main')?.modules.some(value =>
+      ['@deepseek-ai/dsh-tool-goal', '@deepseek-ai/dsh-command-goal'].includes(value.moduleName)),
+    'Native goal mutations must not bypass Arcfold stage control');
+    required(ctx.get('arcfoldWork'), 'Arcfold execution-stage control is missing');
+    required(compositions.find(value => value.id === 'arcfold-learning')?.modules.length === 0, 'Learn acquired tool-bearing modules');
+    assertPreparationComposition(compositions.find(value => value.id === 'arcfold-preparation'),
+      entry('preset-arcfold-preparation').fiber.ctx.fiber.rawConfig.plugins);
+    const nativeDriver = await inspectNativeContinuationDriver(ctx, entries, compositions);
+    const configured = runtimeRouteAvailability(plan.config);
+    required(services.arcfoldRuntimeWorkspace.requestedPath === plan.workspace,
+      'The native workspace initialization used a different deployment directory');
+    const criticalFibers = Object.fromEntries(['llm', 'arcfold-business', 'preset-arcfold-main', 'arcfold-preparation', 'preset-arcfold-preparation',
+      'fs-observation-policy', 'fs-sandbox', 'tool-executor-native',
+      'arcfold-runtime-workspace', 'workspace-controller', 'arcfold-runtime-model-settings',
+      'session', 'session-controller', 'agent-default-model', 'config-editor', 'arcfold-ui'].map(id => [id, fiber(id)]));
+    criticalFibers['goal-round-driver'] = nativeDriver;
+    criticalFibers.goal = fiber('goal');
+    await inspectRuntimeModelSelection(ctx, plan, criticalFibers);
+    let identifyRequest;
+    const routes = runtimeTransport(plan.config).routes;
+    const enabled = Object.keys(routes).filter(provider => runtimeProviderDefaults(plan.config, provider).available);
+    if (enabled.length) {
+      for (const id of ['credentials', 'session']) criticalFibers[id] = fiber(id);
+      if (plan.config.schema === 'arcfold-local-v2') criticalFibers['arcfold-shared-metered-host'] = fiber('arcfold-shared-metered-host');
+      else criticalFibers['arcfold-metered-budget'] = fiber('arcfold-metered-budget');
+      if (enabled.includes('deepseek-official')) criticalFibers['arcfold-metered-provider'] = fiber('arcfold-metered-provider');
+      if (enabled.includes('openai')) criticalFibers['arcfold-openai-provider'] = fiber('arcfold-openai-provider');
+      const { nativeRequestIdentity } = await import(pathToFileURL(join(plan.installation.coreRoot, 'src/native-request-authority.mjs')).href);
+      identifyRequest = options => nativeRequestIdentity(services.arcfoldBusiness, services.sessions, options);
+    }
+    await inspectRuntimeProviders(ctx, plan, criticalFibers);
+    if (configured.learn.available) {
+      required(ctx.get('arcfoldLearning'), 'Configured independent learning is not active');
+      criticalFibers['arcfold-learning'] = fiber('arcfold-learning');
+      criticalFibers['preset-arcfold-learning'] = fiber('preset-arcfold-learning');
+    }
+    const rawUrl = new URL(services.webApp.getAdvertisedUrl());
+    required(rawUrl.hostname === '127.0.0.1' && rawUrl.protocol === 'http:', 'Unexpected local web listener');
+    rawUrl.username = ''; rawUrl.password = ''; rawUrl.search = ''; rawUrl.hash = '';
+    // No HTTP inference: each required service, actual module and native preset was inspected above.
+    guard.arm({ criticalFibers, identifyRequest, expectedAdapterUpdates });
+    return { url: rawUrl.href, identity: { sourceCommit: plan.installation.sourceCommit, profile: plan.installation.profileName,
+        core: plan.installation.coreRoot, ui: plan.installation.uiRoot },
+      ...await refreshRuntimeReadiness(ctx, plan) };
+  } catch (error) { guard.fail(error); throw error; }
+}