@arcfold/dsh 0.0.0-stage → 0.4.0

package/src/runtime-guard.mjs

@@ -0,0 +1,284 @@
+import { canonicalJson } from './store.mjs';
+import { learningExecutionConfig } from './learning-defaults.mjs';
+import { symbols } from '@deepseek-ai/cordis';
+
+const guards = new WeakMap();
+const ACTIVE = 2; // Cordis 4.1.0 FiberState.ACTIVE (the TS const enum has no JS export).
+const SERVICE = 'arcfoldRuntimeGuard';
+const REQUIRED = ['llm', 'arcfold-business', 'preset-arcfold-main'];
+const ROUTE_FIELDS = ['provider', 'model', 'reasoningEffort', 'maxTokens'];
+
+function frozen(value) {
+  if (value && typeof value === 'object') {
+    for (const child of Object.values(value)) frozen(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+function failure(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function configuration(value) {
+  return frozen(JSON.parse(canonicalJson({
+    modelSelectionRequired: value.modelSelectionRequired === true,
+    initialMain: value.initialMain ?? { provider: '', model: '' },
+    mainMaxTokens: value.mainMaxTokens ?? null,
+    routeAvailability: value.routeAvailability ?? { main: { available: false }, learn: { available: false } },
+    learn: value.learn ?? null,
+    modelPolicies: value.modelPolicies ?? {},
+    ...(value.routes === undefined ? {} : { routes: value.routes }),
+  })));
+}
+
+function provision(fiber, name) {
+  const matches = [...(fiber?.provisions ?? [])].filter(item => item.name === name);
+  if (matches.length !== 1 || matches[0].ctx.fiber !== fiber)
+    throw failure('ARCFOLD_RUNTIME_IDENTITY', `The runtime has no unique owned ${name} service`);
+  return matches[0];
+}
+
+// Cordis exports this read-only tracing identity symbol. Event callbacks see
+// caller-scoped proxies, not the raw service retained by Fiber.provisions.
+export function serviceIdentity(value) {
+  const seen = new Set();
+  while (value && value[symbols.original]) {
+    if (seen.has(value)) return null;
+    seen.add(value); value = value[symbols.original];
+  }
+  return value;
+}
+
+/** Read the real optional child, never a guessed Loader entry or provider label. */
+export function assertOpenAIIdentity(root, wrapper, llm, metered) {
+  const record = provision(wrapper, 'arcfoldOpenAIProviderIdentity'), identity = record.value;
+  const child = identity?.nativeFiber;
+  if (!Object.isFrozen(identity) || !Object.isFrozen(identity.configuration) || identity.wrapperFiber !== wrapper ||
+      !child || child.state !== ACTIVE || child.ctx.root !== root || child.parent.fiber !== wrapper ||
+      child.committed?.llm !== llm || wrapper.committed?.llm !== llm || wrapper.committed?.arcfoldMeteredTransport !== metered ||
+      typeof identity.moduleURL !== 'string' || typeof identity.transportHookActive !== 'function' || identity.transportHookActive() !== true ||
+      canonicalJson(child.rawConfig) !== canonicalJson(identity.configuration))
+    throw failure('ARCFOLD_RUNTIME_IDENTITY', 'The actual OpenAI child, fixed profile or owned transport callback changed.');
+  return identity;
+}
+
+/** Root ownership deliberately survives profile-entry disposal. No entry may re-arm it. */
+export function getRuntimeGuard(ctx) {
+  return guards.get(ctx.root) ?? ctx.root.get(SERVICE);
+}
+
+export const name = 'arcfold-runtime-guard';
+// No injection: the official llm entry depends on the root service this installs.
+export function apply(ctx, input = {}) {
+  const root = ctx.root, config = configuration(input), existing = getRuntimeGuard(root);
+  if (existing) {
+    if (canonicalJson(existing.configuration) !== canonicalJson(config)) existing.requireRestart('guard-configuration-changed');
+    return; // Never return a root-owned disposer to the replaceable plugin fiber.
+  }
+
+  let phase = 'starting', reason = null, armed = false, adapterUpdates = 0;
+  let releaseReady;
+  const ready = new Promise(resolve => { releaseReady = resolve; });
+  let pinned = [], identifyRequest, transport, rootLlm, openAI, business, models;
+  const providerIdentitiesCurrent = () => {
+    if (models && models.identity.hookActive() !== true) return false;
+    if (openAI) { try { if (assertOpenAIIdentity(root, openAI.wrapper, rootLlm, transport) !== openAI.identity) return false; } catch { return false; } }
+    return true;
+  };
+  const identitiesCurrent = () => providerIdentitiesCurrent() && pinned.every(saved => saved.fiber.uid === saved.uid && saved.fiber.state === ACTIVE &&
+    saved.provisions.every(item => saved.fiber.provisions.has(item.record) && item.record.value === item.value && item.record.uid === item.uid) &&
+    Object.entries(saved.committed).every(([key, item]) => saved.fiber.committed?.[key] === item.record &&
+      item.record.value === item.value && item.record.uid === item.uid));
+  const snapshot = () => Object.freeze(phase === 'ready' && !identitiesCurrent()
+    ? { phase: 'requires-restart', reason: 'critical-component-changed', armed, adapterUpdates }
+    : { phase, reason, armed, adapterUpdates });
+  const stop = (next, why) => {
+    if (phase === 'closed' || phase === 'failed' || phase === 'requires-restart') return;
+    phase = next; reason = why; releaseReady();
+  };
+  const requireRestart = why => stop('requires-restart', why);
+  const rejectState = () => {
+    if (phase !== 'ready') throw failure(
+      phase === 'requires-restart' ? 'ARCFOLD_RUNTIME_RESTART_REQUIRED' : 'ARCFOLD_RUNTIME_NOT_READY',
+      phase === 'requires-restart' ? 'The model configuration changed; restart Arcfold through its launcher before sending another request.'
+        : 'Arcfold is not ready to send model requests. Its configuration page remains available.',
+    );
+  };
+  const assertIdentities = () => {
+    if (!identitiesCurrent()) { requireRestart('critical-component-changed'); rejectState(); }
+  };
+  const assertInput = options => {
+    rejectState(); assertIdentities();
+    options.signal?.throwIfAborted();
+    if (!transport) throw failure('ARCFOLD_ROUTE_UNAVAILABLE', 'No supported metered model route is configured.');
+    if (!Object.isFrozen(options)) throw failure('ARCFOLD_RUNTIME_INPUT', 'Only a frozen native session request may use this runtime.');
+    const policies = config.routes === undefined ? (options.provider === 'deepseek-official' ? config.modelPolicies : undefined) : config.routes[options.provider]?.modelPolicies;
+    const policy = policies?.[options.model];
+    if (!policy ||
+        !policy.reasoningEfforts?.includes(options.reasoningEffort) ||
+        !Number.isSafeInteger(options.maxTokens) || options.maxTokens < 1 ||
+        options.maxTokens > (policy.requestMaxTokens ?? policy.maxOutputTokens))
+      throw failure('ARCFOLD_ROUTE_UNAVAILABLE', 'The selected model or request controls are not supported by this metered runtime.');
+  };
+  // Full business ownership is checked at the owned transport, after the
+  // learning middleware has validated and recorded its single-call intent.
+  const assertDispatch = options => {
+    assertInput(options);
+    const identity = identifyRequest(options);
+    if (identity && typeof identity.then === 'function') {
+      void Promise.resolve(identity).catch(() => {});
+      throw failure('ARCFOLD_RUNTIME_IDENTITY', 'Native request identity must be checked synchronously.');
+    }
+    const role = identity?.metadata?.role;
+    if (!['main', 'learning', 'preparation'].includes(role)) throw failure('ARCFOLD_RUNTIME_IDENTITY', 'The request has no supported Arcfold owner.');
+    if (role === 'main' && config.mainMaxTokens !== null && options.maxTokens !== config.mainMaxTokens)
+      throw failure('ARCFOLD_ROUTE_UNAVAILABLE', 'The native model default cannot represent the explicitly configured main output limit. Update the main configuration before sending.');
+    if (role === 'learning') {
+      const run = business?.get('learning_runs', identity.metadata.learningPendingId);
+      if (!config.routeAvailability.learn?.available || !run || run.sessionId !== options.sessionId ||
+          run.inputHash !== identity.metadata.learningInputHash)
+        throw failure('ARCFOLD_ROUTE_UNAVAILABLE', 'This learning request has no matching saved execution configuration.');
+      const execution = learningExecutionConfig(run);
+      if (ROUTE_FIELDS.some(key => options[key] !== execution[key]))
+        throw failure('ARCFOLD_ROUTE_UNAVAILABLE', 'This learning request does not match its independently configured model saved at start.');
+    }
+    if (role === 'preparation') {
+      const run = business?.get('preparation_runs', identity.metadata.preparationRunId);
+      if (!run || run.sessionId !== options.sessionId || run.inputHash !== identity.metadata.preparationInputHash ||
+          run.state !== 'submitted' || ROUTE_FIELDS.some(key => options[key] !== run.executionConfig?.[key]) ||
+          !root.get('arcfoldPreparation'))
+        throw failure('ARCFOLD_ROUTE_UNAVAILABLE', 'Preparation has no matching bounded native owner.');
+    }
+    return identity;
+  };
+  const waitReady = async signal => {
+    signal?.throwIfAborted();
+    if (phase === 'starting') {
+      if (!signal) await ready;
+      else await new Promise((resolve, reject) => {
+        const abort = () => { signal.removeEventListener('abort', abort); reject(signal.reason); };
+        signal.addEventListener('abort', abort, { once: true });
+        ready.then(() => { signal.removeEventListener('abort', abort); resolve(); });
+        if (signal.aborted) abort();
+      });
+    }
+    signal?.throwIfAborted(); rejectState();
+  };
+
+  const guard = Object.freeze({
+    configuration: config, snapshot, requireRestart, assertDispatch,
+    assertReady() { rejectState(); assertIdentities(); },
+    fail: () => stop('failed', 'startup-failed'),
+    close: () => stop('closed', 'runtime-closed'),
+    arm({ criticalFibers, identifyRequest: identify, expectedAdapterUpdates = adapterUpdates } = {}) {
+      if (armed || phase !== 'starting') throw failure('ARCFOLD_RUNTIME_ARM', 'A runtime guard can be armed only once, by startup readiness.');
+      try {
+        if (!criticalFibers || typeof criticalFibers !== 'object' || Array.isArray(criticalFibers))
+          throw failure('ARCFOLD_RUNTIME_IDENTITY', 'Startup must supply the actual critical plugin fibers.');
+        for (const id of REQUIRED) if (!criticalFibers[id]) throw failure('ARCFOLD_RUNTIME_IDENTITY', `Startup is missing ${id}.`);
+        pinned = Object.entries(criticalFibers).map(([id, fiber]) => {
+          if (fiber?.state !== ACTIVE || !Number.isSafeInteger(fiber.uid) || fiber.uid < 1 || fiber.ctx.root !== root)
+            throw failure('ARCFOLD_RUNTIME_IDENTITY', `The ${id} plugin is not an active child of this host.`);
+          const pin = record => ({ record, value: record.value, uid: record.uid });
+          return { id, fiber, uid: fiber.uid, provisions: [...fiber.provisions].map(pin),
+            committed: Object.fromEntries(Object.entries(fiber.committed ?? {}).map(([key, record]) => [key, pin(record)])) };
+        });
+        rootLlm = provision(criticalFibers.llm, 'llm');
+        business = provision(criticalFibers['arcfold-business'], 'arcfoldBusiness').value;
+        if (config.modelSelectionRequired) {
+          const modelFiber = criticalFibers['arcfold-runtime-model-settings'];
+          models = provision(modelFiber, 'arcfoldRuntimeModels').value;
+          const expected = { sessionController: 'session-controller', agentDefaultModel: 'agent-default-model', sessions: 'session', configEditor: 'config-editor' };
+          for (const [name, id] of Object.entries(expected))
+            if (modelFiber.committed?.[name] !== provision(criticalFibers[id], name))
+              throw failure('ARCFOLD_RUNTIME_IDENTITY', 'Native model settings uses an unverified service.');
+          const identity = models.identity;
+          if (!Object.isFrozen(identity) || identity.fiber !== modelFiber || identity.hookActive() !== true ||
+              identity.controller !== provision(criticalFibers['session-controller'], 'sessionController').value ||
+              identity.defaults !== provision(criticalFibers['agent-default-model'], 'agentDefaultModel').value ||
+              identity.sessions !== provision(criticalFibers.session, 'sessions').value)
+            throw failure('ARCFOLD_RUNTIME_IDENTITY', 'The mandatory native model selection handler is absent or changed.');
+        }
+        const provider = criticalFibers['arcfold-metered-provider'];
+        const shared = criticalFibers['arcfold-shared-metered-host'];
+        const expectedProviders = config.routes === undefined ? (provider ? ['deepseek-official'] : []) : Object.keys(config.routes).sort();
+        if (canonicalJson(rootLlm.value.listProviders().map(p => p.id).sort()) !== canonicalJson(expectedProviders) ||
+            serviceIdentity(root.get('llm')) !== rootLlm.value || expectedAdapterUpdates !== adapterUpdates)
+          throw failure('ARCFOLD_RUNTIME_IDENTITY', 'The actual model topology changed before the final readiness check.');
+        if (config.routes !== undefined) {
+          if (Boolean(shared) !== Boolean(expectedProviders.length)) throw failure('ARCFOLD_RUNTIME_IDENTITY', 'Shared accounting and actual model routes must be mounted together.');
+          if (shared) {
+            transport = provision(shared, 'arcfoldMeteredTransport');
+            if (shared.committed?.llm !== rootLlm || typeof transport.value?.createTransport !== 'function' ||
+                canonicalJson(transport.value.configuration.routes) !== canonicalJson(config.routes))
+              throw failure('ARCFOLD_RUNTIME_IDENTITY', 'The shared accounting policies or LLM ownership differ from startup configuration.');
+            const business = provision(criticalFibers['arcfold-business'], 'arcfoldBusiness');
+            const sessions = provision(criticalFibers.session, 'sessions');
+            if (shared.committed?.arcfoldBusiness !== business || shared.committed?.sessions !== sessions)
+              throw failure('ARCFOLD_RUNTIME_IDENTITY', 'The shared host uses a different business or native session service.');
+          }
+          const deepseek = config.routes['deepseek-official'];
+          if (Boolean(provider) !== Boolean(deepseek)) throw failure('ARCFOLD_RUNTIME_IDENTITY', 'The configured DeepSeek wrapper is absent or unexpected.');
+          if (provider && (provider.committed?.llm !== rootLlm || provider.committed?.arcfoldDeepSeekTransport !== provision(shared, 'arcfoldDeepSeekTransport')))
+            throw failure('ARCFOLD_RUNTIME_IDENTITY', 'The DeepSeek wrapper is not owned by the shared host.');
+          const wrapper = criticalFibers['arcfold-openai-provider'];
+          if (Boolean(wrapper) !== Boolean(config.routes.openai)) throw failure('ARCFOLD_RUNTIME_IDENTITY', 'The configured OpenAI wrapper is absent or unexpected.');
+          if (wrapper) {
+            const identity = assertOpenAIIdentity(root, wrapper, rootLlm, transport);
+            if (criticalFibers['arcfold-openai-native'] !== identity.nativeFiber)
+              throw failure('ARCFOLD_RUNTIME_IDENTITY', 'Readiness did not pin the actual native OpenAI child.');
+            openAI = { wrapper, identity };
+          }
+          if (expectedProviders.length) {
+            const credentials = provision(criticalFibers.credentials, 'credentials');
+            for (const wrapper of [provider, criticalFibers['arcfold-openai-provider']].filter(Boolean))
+              if (wrapper.committed?.credentials !== credentials) throw failure('ARCFOLD_RUNTIME_IDENTITY', 'A provider uses a foreign credential service.');
+          }
+        } else {
+          const budget = criticalFibers['arcfold-metered-budget'];
+          if (Boolean(budget) !== Boolean(provider)) throw failure('ARCFOLD_RUNTIME_IDENTITY', 'The model provider and its accounting service must be mounted together.');
+          if (provider) {
+            transport = provision(budget, 'arcfoldDeepSeekTransport');
+            if (provider.committed?.llm !== rootLlm || provider.committed?.arcfoldDeepSeekTransport !== transport || budget.committed?.llm !== rootLlm ||
+                transport.value?.configuration?.provider !== 'deepseek-official' || canonicalJson(transport.value.configuration.modelPolicies) !== canonicalJson(config.modelPolicies))
+              throw failure('ARCFOLD_RUNTIME_IDENTITY', 'The metered provider is not bound to the verified LLM and accounting instances.');
+          }
+        }
+        if (expectedProviders.length && typeof identify !== 'function') throw failure('ARCFOLD_RUNTIME_IDENTITY', 'A native request identity check is required.');
+        if (config.routeAvailability.learn?.available && (!transport || !criticalFibers['arcfold-learning'] || !criticalFibers['preset-arcfold-learning']))
+          throw failure('ARCFOLD_RUNTIME_IDENTITY', 'The independently configured learning route is incomplete.');
+        identifyRequest = identify; armed = true; phase = 'ready'; releaseReady();
+        return snapshot();
+      } catch (error) { stop('failed', 'startup-identity-failed'); throw error; }
+    },
+  });
+  guards.set(root, guard);
+  root.on('llm/adapters-updated', () => {
+    adapterUpdates++;
+    if (armed) requireRestart('model-topology-changed');
+  }, { global: true });
+  root.on('internal/status', fiber => {
+    if (armed && pinned.some(item => item.fiber === fiber) && fiber.state !== ACTIVE) requireRestart('critical-component-changed');
+  }, { global: true });
+  root.on('loader/volatile-update', function () {
+    // Native default fields are explicitly volatile; a normal daily selection
+    // retains the same service and must not tear down an active learning run.
+    if (armed && pinned.some(item => item.fiber === this.fiber && item.id !== 'agent-default-model')) requireRestart('critical-configuration-changed');
+  }, { global: true });
+  root.on('llm/stream', function (options, next) {
+    const sender = serviceIdentity(this);
+    return (async function* () {
+      await waitReady(options.signal);
+      if (sender !== rootLlm.value) requireRestart('llm-instance-changed');
+      // The outer gate runs before downstream learning validation. It
+      // checks host/route readiness, not a dispatch intent that does not yet exist.
+      assertInput(options);
+      yield* next();
+    })();
+  }, { global: true, prepend: true });
+  root.effect(() => () => guard.close(), 'close the model gate with the official host');
+  root.provide(SERVICE, guard);
+}

package/src/runtime-host.mjs

@@ -0,0 +1,212 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { mkdir, readFile } from 'node:fs/promises';
+import { writeFileSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { isDeepStrictEqual } from 'node:util';
+import { RUNTIME_PROTOCOL, acquireRuntimeLease, lifecycleError, writeRuntimeRecord } from './runtime-lifecycle.mjs';
+
+const errorView = error => ({ code: error.code || 'runtime_failure', message: String(error.message || error) });
+const launchBrowser = (command, args) => new Promise((resolveDone, reject) => {
+  execFile(command, args, { timeout:5000, maxBuffer:65536 }, error => error ? reject(error) : resolveDone());
+});
+
+/** The URL is obtained from this host only and never leaves the opener boundary. */
+export async function openRuntimeBrowser(ctx, { platform = process.platform, opener = launchBrowser } = {}) {
+  if (platform !== 'darwin') throw lifecycleError('unsupported_platform', 'Opening the authenticated page is currently supported only on macOS.');
+  try {
+    const url = ctx.get('connection').authenticatedUrl(ctx.get('webApp').getAdvertisedUrl());
+    await opener('/usr/bin/open', [url]);
+    return { opened:true };
+  } catch { throw lifecycleError('browser_open_failed', 'The authenticated page could not be opened.'); }
+}
+
+/** Own one host lifetime. Injected functions isolate lifecycle tests, not a CLI plugin hook. */
+export async function runOwnedRuntime({ plan, runId, runDirectory }, { prepareBoot, loadOfficialHost, inspectReady, refreshReady }) {
+  const lease = await acquireRuntimeLease(plan.runtimeDirectory);
+  let server, controlAddress, official, stopping, cancelled = false, phase = 'starting', ready, failure, bootStarted = false;
+  const controlToken = randomBytes(32);
+  let officialClosed = false, shutdownEvidence = 'unconfirmed', teardownError;
+  const sockets = new Set();
+  const state = observation => {
+    const view = { ...(ready ?? {}), ...(observation ?? {}) };
+    if (ready && (phase !== 'ready' || cancelled)) {
+      const reason = 'runtime-' + phase;
+      view.mode = 'configuration-only';
+      view.routeAvailability = { ...view.routeAvailability, main:{available:false,reason}, learn:{available:false,reason} };
+      view.issues = [...new Set([...(view.issues ?? []),reason])];
+      delete view.modelGate;
+    }
+    // Observation fields cannot replace the owned process identity or phase.
+    return { ...view, schema:RUNTIME_PROTOCOL, dataRoot:plan.dataRoot, runId, pid:process.pid,
+      phase, configurationHash:plan.configurationHash, controlAddress,
+      ...(failure ? {error:failure} : {}), ...(teardownError ? {teardownError} : {}), shutdownEvidence };
+  };
+  const status = async () => {
+    if (phase !== 'ready' || cancelled || !official) return state();
+    const observedHost = official; let observation, timer;
+    try {
+      observation = await Promise.race([
+        Promise.resolve().then(() => refreshReady(observedHost.ctx, plan)),
+        new Promise((_, reject) => { timer = setTimeout(() => reject(lifecycleError('readiness_refresh_timeout', 'Readiness observation timed out.')), 750); }),
+      ]);
+      if (!observation || !['execution-ready','configuration-only'].includes(observation.mode) ||
+          typeof observation.routeAvailability?.main?.available !== 'boolean' ||
+          typeof observation.routeAvailability?.learn?.available !== 'boolean' || !Array.isArray(observation.issues))
+        throw lifecycleError('readiness_refresh_failed', 'Invalid readiness observation.');
+      observation = { mode:observation.mode, routeAvailability:observation.routeAvailability,
+        issues:observation.issues, modelGate:observation.modelGate ?? null };
+    } catch (error) {
+      const code = error.code === 'readiness_refresh_timeout' ? error.code : 'readiness_refresh_failed';
+      observation = { mode:'configuration-only', modelGate:null,
+        routeAvailability:{main:{available:false,reason:code},learn:{available:false,reason:code},credentialConfigured:null,providerCredentialValidated:false},
+        issues:[code], statusObservationError:{code,message:'Current runtime readiness could not be confirmed.'} };
+    } finally { clearTimeout(timer); }
+    // A delayed read is never allowed to restore availability after stop/fail.
+    if (phase !== 'ready' || cancelled || official !== observedHost) return state();
+    return state(observation);
+  };
+  let writes = Promise.resolve();
+  const publish = () => { const value = state(); return writes = writes.catch(() => {}).then(async () => {
+    await writeRuntimeRecord(join(runDirectory, 'state.json'), value);
+    await writeRuntimeRecord(join(plan.runtimeDirectory, 'current.json'), value);
+  }); };
+  let resolveStopped;
+  const stopped = new Promise(resolveDone => { resolveStopped = resolveDone; });
+  const stop = () => {
+    cancelled = true;
+    if (stopping) return stopping;
+    // Before runProfile returns, the startup path will observe cancellation and
+    // join this same shutdown operation once the official handle is available.
+    if (!official) { phase = 'stopping'; void publish().catch(() => {}); return null; }
+    phase = failure ? 'failed' : 'stopping';
+    stopping = (async () => {
+      try { official.ctx.get?.('arcfoldRuntimeGuard')?.close(); }
+      catch (error) { failure ??= errorView(error); }
+      await publish().catch(error => { failure ??= errorView(error); });
+      await official.shutdown.shutdown(0);
+      officialClosed = true;
+      await writeRuntimeRecord(join(runDirectory, 'official-shutdown-returned.json'), {
+        kind: 'official-shutdown-returned', schema: RUNTIME_PROTOCOL, runId, dataRoot: plan.dataRoot,
+        returnedAt: new Date().toISOString(), scope: 'official profile teardown returned; user work and unknown outcomes are not declared successful',
+      }, { exclusive: true });
+      shutdownEvidence = 'official-shutdown-returned';
+      phase = failure ? 'failed' : 'stopped'; await publish(); resolveStopped();
+    })();
+    void stopping.catch(error => { failure ??= errorView(error); teardownError = errorView(error); resolveStopped(); });
+    return stopping;
+  };
+  // Do not call shutdown again in this listener. runProfile installs its own
+  // SIGTERM handler; repeated interrupt would force an early process exit.
+  const onTerm = () => { cancelled = true; };
+  process.on('SIGTERM', onTerm);
+  const exitReceipt = code => {
+    try { writeFileSync(join(runDirectory, 'process-exit.json'), JSON.stringify({ runId, code, phase, at: new Date().toISOString() }) + '\n', { flag: 'wx', mode: 0o600 }); } catch {}
+  };
+  process.once('exit', exitReceipt);
+  try {
+    await mkdir(runDirectory, { recursive: true, mode: 0o700 });
+    server = createServer(socket => {
+      if (socket.remoteAddress !== '127.0.0.1') { socket.destroy(); return; }
+      sockets.add(socket); socket.on('close', () => sockets.delete(socket)); socket.on('error', () => {});
+      socket.setTimeout(2000, () => socket.destroy()); let input = '', handled = false;
+      socket.on('data', chunk => {
+        if (handled) return; input += chunk;
+        if (Buffer.byteLength(input) > 2048) { socket.destroy(); return; }
+        if (!input.includes('\n')) return; handled = true;
+        try {
+          const request = JSON.parse(input.slice(0, input.indexOf('\n')));
+          if (request.schema !== RUNTIME_PROTOCOL || request.runId !== runId || request.dataRoot !== plan.dataRoot || !['status', 'stop', 'open'].includes(request.method) ||
+              Object.keys(request).some(key => !['schema','runId','dataRoot','method','token'].includes(key)) ||
+              typeof request.token !== 'string' || !/^[a-f0-9]{64}$/.test(request.token) ||
+              !timingSafeEqual(Buffer.from(request.token, 'hex'), controlToken)) { socket.destroy(); return; }
+          if (request.method === 'open') {
+            socket.setTimeout(7000, () => socket.destroy());
+            const opening = phase === 'ready' && official && !cancelled ? openRuntimeBrowser(official.ctx)
+              : Promise.reject(lifecycleError('runtime_not_ready', 'The runtime is not ready to open its page.'));
+            void opening.then(() => socket.end(JSON.stringify({schema:RUNTIME_PROTOCOL,runId,dataRoot:plan.dataRoot,opened:true})+'\n'),
+              error => socket.end(JSON.stringify({schema:RUNTIME_PROTOCOL,runId,dataRoot:plan.dataRoot,
+                controlError:{code:['unsupported_platform','runtime_not_ready'].includes(error.code) ? error.code : 'browser_open_failed'}})+'\n'));
+            return;
+          }
+          if (request.method === 'status') {
+            void status().then(value => { if (!socket.destroyed) socket.end(JSON.stringify(value)+'\n'); }, () => socket.destroy());
+            return;
+          }
+          if (request.method === 'stop') { cancelled = true; phase = failure ? 'failed' : 'stopping'; }
+          socket.end(JSON.stringify(state()) + '\n');
+          if (request.method === 'stop') void stop();
+        } catch { socket.destroy(); }
+      });
+    });
+    server.maxConnections = 16;
+    await new Promise((listening, reject) => { server.once('error', reject); server.listen({ host:'127.0.0.1', port:0, exclusive:true }, listening); });
+    controlAddress = { host:'127.0.0.1', port:server.address().port };
+    // Only this 0600 record contains the independent control secret. Public
+    // state, logs, errors, and command responses never include it.
+    await writeRuntimeRecord(join(runDirectory, 'control.json'), { schema:RUNTIME_PROTOCOL, runId, dataRoot:plan.dataRoot,
+      address:controlAddress, token:controlToken.toString('hex') }, { exclusive:true });
+    await publish();
+    if (!cancelled) {
+      await mkdir(plan.nativeHome, { recursive: true, mode: 0o700 });
+      const options = await prepareBoot(plan, runDirectory);
+      if (!cancelled) {
+        const { runProfile } = await loadOfficialHost(plan);
+        if (!cancelled) { bootStarted = true; official = await runProfile(options); }
+      }
+    }
+    if (official) {
+      if (cancelled) await stop();
+      else {
+        ready = await inspectReady(official.ctx, plan);
+        if (cancelled) await stop();
+        else { phase = 'ready'; await writeRuntimeRecord(join(runDirectory, 'ready.json'), state(), { exclusive: true }); await publish(); await stopped; await stopping; }
+      }
+    } else { phase = 'cancelled'; await publish(); }
+  } catch (error) {
+    failure = errorView(error); phase = 'failed';
+    try { official?.ctx.get?.('arcfoldRuntimeGuard')?.fail(error); }
+    catch (guardError) { teardownError = errorView(guardError); }
+    await writeRuntimeRecord(join(runDirectory, 'failure.json'), { ...failure, runId, bootStarted }, { exclusive: true }).catch(() => {});
+    await publish().catch(() => {});
+    if (official) try { await stop(); } catch {}
+    throw error;
+  } finally {
+    await writes.catch(() => {});
+    for (const socket of sockets) socket.destroy();
+    if (server?.listening) await new Promise(done => server.close(done));
+    process.off('SIGTERM', onTerm);
+    if (!official || officialClosed) await lease.close();
+    // An unexpected rejected teardown is not proof that the host stopped.
+    // Keep a strong reference and its kernel lock until this private child exits.
+    else process.once('exit', () => { void lease.fd; });
+  }
+  return { runId, phase, bootStarted };
+}
+
+async function main() {
+  if (process.argv.length !== 4 || process.argv[2] !== '--launch') throw new Error('Private runtime entry requires one launch record.');
+  const launch = JSON.parse(await readFile(resolve(process.argv[3]), 'utf8'));
+  if (launch.schema !== RUNTIME_PROTOCOL || typeof launch.runId !== 'string' || !/^[a-zA-Z0-9_-]{1,128}$/.test(launch.runId) || launch.runDirectory !== join(launch.plan.runtimeDirectory, 'runs', launch.runId))
+    throw new Error('Invalid runtime launch identity.');
+  // Set these before root boot helpers or any official module is imported.
+  process.chdir(launch.plan.workspace); process.env.DSH_HOME = launch.plan.nativeHome;
+  const { loadRuntimePlan, prepareRuntimeBoot } = await import('./runtime-config.mjs');
+  const plan = await loadRuntimePlan(launch.plan.configPath);
+  if (!isDeepStrictEqual(plan, launch.plan)) throw new Error('Runtime configuration or installation changed after the launch request.');
+  await runOwnedRuntime({ ...launch, plan }, { prepareBoot: prepareRuntimeBoot,
+    // The profile's Cordis peer becomes resolvable only after runProfile installs
+    // official package resolution. Keep imports inside the owned error/teardown path.
+    inspectReady: async (...args) => (await import('./runtime-readiness.mjs')).inspectRuntimeReady(...args),
+    refreshReady: async (...args) => (await import('./runtime-readiness.mjs')).refreshRuntimeReadiness(...args),
+    loadOfficialHost: async () => {
+      const require = createRequire(plan.installation.installAnchor);
+      return import(pathToFileURL(require.resolve('@deepseek-ai/dsh/profile-boot')).href);
+    } });
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try { await main(); } catch (error) { console.error(JSON.stringify(errorView(error))); process.exit(1); }
+}