@logicseek/hello-cc 1.1.0-rc.1 → 1.1.0-rc.3

package/lib/process/pinned-project-state.mjs

@@ -0,0 +1,105 @@
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+import { CliError } from '../shared/errors.mjs';
+import { preparePinnedCwdLaunch } from './pinned-cwd.mjs';
+
+// The bootstrap enters the checked directory inode before this worker runs.
+// All destructive names below are relative to that cwd, never to a project
+// pathname that could have been rebound after validation.
+function projectStateWorker() {
+  const fs = require('node:fs');
+  const mode = process.argv[1];
+  const expected = JSON.parse(process.argv[2]);
+  const content = process.argv[3] || '';
+  const sameDirectory = (stat) => stat.isDirectory() &&
+    stat.dev.toString() === expected.dev && stat.ino.toString() === expected.ino &&
+    (expected.birthtimeNs === null ||
+      stat.birthtimeNs?.toString() === expected.birthtimeNs);
+  let fd;
+  let temporary;
+  try {
+    if (mode === 'write-guidance') {
+      if (!sameDirectory(fs.statSync('.', { bigint: true }))) {
+        throw new Error('STATE_DIRECTORY_CHANGED');
+      }
+      temporary = `HCC.md.tmp.${process.pid}.${require('node:crypto').randomBytes(16).toString('hex')}`;
+      fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT |
+        fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+      fs.writeFileSync(fd, content);
+      fs.fsyncSync(fd);
+      fs.closeSync(fd);
+      fd = undefined;
+      /* PINNED_STATE_TEST_BEFORE_RENAME */
+      fs.renameSync(temporary, 'HCC.md');
+    } else if (mode === 'purge-legacy') {
+      const state = fs.lstatSync('.hello-cc', { bigint: true });
+      if (!sameDirectory(state)) throw new Error('STATE_DIRECTORY_CHANGED');
+      /* PINNED_STATE_TEST_BEFORE_PURGE */
+      fs.rmSync('.hello-cc', { recursive: true, force: true });
+    } else throw new Error('STATE_OPERATION_INVALID');
+    process.stdout.write('ok');
+  } catch (error) {
+    process.stderr.write('HCC_PINNED_STATE_FAILED:' + (error?.code || error?.message || 'unknown') + '\n');
+    process.exitCode = 1;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    if (temporary) {
+      try { fs.unlinkSync(temporary); } catch {}
+    }
+  }
+}
+
+const PROJECT_STATE_WORKER_SOURCE = '(' + projectStateWorker.toString() + ')()';
+
+function sameBinding(actual, expected) {
+  return actual.identity.cwd === expected.canonical &&
+    actual.identity.dev === expected.identity.dev &&
+    actual.identity.ino === expected.identity.ino &&
+    actual.identity.birthtimeNs === expected.identity.birthtimeNs;
+}
+
+function runPinnedStateWorker(cwd, mode, expectedCwd, targetIdentity, content, spawnProcess) {
+  expectedCwd.assertUnchanged();
+  const binding = preparePinnedCwdLaunch(cwd, process.execPath,
+    ['-e', PROJECT_STATE_WORKER_SOURCE, mode, JSON.stringify(targetIdentity), content], {
+      env: { PATH: '/usr/bin:/bin', NODE_OPTIONS: '', NODE_NO_WARNINGS: '1' }
+    });
+  try {
+    if (!sameBinding(binding, expectedCwd)) {
+      throw new CliError('PROJECT_PATH_CHANGED', 'Project state directory changed before pinned operation');
+    }
+    const result = spawnProcess(binding.command, binding.args, {
+      cwd: binding.cwd, env: binding.env, encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'], timeout: 300000, maxBuffer: 64 * 1024
+    });
+    if (result.error || result.status !== 0 || result.stdout !== 'ok') {
+      const marker = String(result.stderr || '');
+      if (/HCC_PINNED_CWD_CHANGED:|HCC_PINNED_STATE_FAILED:STATE_DIRECTORY_CHANGED/.test(marker)) {
+        throw new CliError('PROJECT_PATH_CHANGED', 'Project state directory changed during pinned operation');
+      }
+      throw new CliError('PROJECT_STATE_OPERATION_FAILED',
+        `Pinned project state operation failed: ${result.error?.code || marker.trim() || `exit ${result.status}`}`);
+    }
+  } finally { binding.release(); }
+}
+
+export function writePinnedProjectGuidance(stateDir, content, expectedState, {
+  spawnProcess = spawnSync
+} = {}) {
+  runPinnedStateWorker(stateDir, 'write-guidance', expectedState, expectedState.identity,
+    content, spawnProcess);
+  return path.join(stateDir, 'HCC.md');
+}
+
+export function purgePinnedLegacyProjectState(root, stateDir, expectedRoot, expectedState, {
+  spawnProcess = spawnSync
+} = {}) {
+  if (path.resolve(stateDir) !== path.join(expectedRoot.canonical, '.hello-cc')) {
+    throw new CliError('PROJECT_PATH_FORBIDDEN', 'Legacy state is not under the selected project root');
+  }
+  expectedState.assertUnchanged();
+  runPinnedStateWorker(root, 'purge-legacy', expectedRoot, expectedState.identity,
+    '', spawnProcess);
+  return stateDir;
+}

package/lib/process/selected-cwd-identity.mjs

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CliError } from '../shared/errors.mjs';
+
+function changed() {
+  return new CliError('PROJECT_PATH_CHANGED', 'Selected working directory changed; create a new session from its current location');
+}
+
+function sameDirectory(left, right) {
+  return left.isDirectory() && right.isDirectory() && left.dev === right.dev &&
+    left.ino === right.ino && left.birthtimeNs === right.birthtimeNs;
+}
+
+export function sameSelectedCwdIdentity(left, right) {
+  return Boolean(left && right && left.canonical === right.canonical &&
+    left.identity?.dev === right.identity?.dev && left.identity?.ino === right.identity?.ino &&
+    left.identity?.birthtimeNs === right.identity?.birthtimeNs);
+}
+
+export function captureSelectedCwdSnapshot(cwd) {
+  const binding = captureSelectedCwdIdentity(cwd);
+  try {
+    return Object.freeze({ requested: binding.requested, canonical: binding.canonical,
+      identity: binding.identity });
+  } finally { binding.release(); }
+}
+
+export function assertSelectedCwdSnapshot(snapshot) {
+  const current = captureSelectedCwdIdentity(snapshot.requested);
+  try {
+    if (!sameSelectedCwdIdentity(snapshot, current)) throw changed();
+  } finally { current.release(); }
+}
+
+// A provider protocol may require an absolute path even after its process was
+// started in a pinned cwd. Keep the originally selected directory identifiable
+// until the adapter closes, and recheck immediately before each path handoff.
+// This does not make the subsequent provider-internal path lookup atomic.
+export function captureSelectedCwdIdentity(cwd, expectedIdentity = null) {
+  if (typeof cwd !== 'string' || !cwd) throw new CliError('BAD_ARGS', 'Selected working directory is required');
+  const requested = path.resolve(cwd);
+  let canonical;
+  try { canonical = fs.realpathSync.native(requested); }
+  catch { throw changed(); }
+
+  let fd;
+  let initial;
+  let mode = 'descriptor';
+  try {
+    fd = fs.openSync(canonical, fs.constants.O_RDONLY |
+      (fs.constants.O_DIRECTORY || 0) | (fs.constants.O_NOFOLLOW || 0));
+    initial = fs.fstatSync(fd, { bigint: true });
+  } catch (error) {
+    if (fd !== undefined) fs.closeSync(fd);
+    fd = undefined;
+    // Execute-only directories can still be valid provider workspaces. The
+    // weaker stat-only mode preserves that contract without hiding the mode.
+    if (error?.code !== 'EACCES') throw changed();
+    mode = 'stat-only';
+    try { initial = fs.statSync(canonical, { bigint: true }); }
+    catch { throw changed(); }
+  }
+  let released = false;
+  const identity = Object.freeze({ dev: initial.dev.toString(), ino: initial.ino.toString(),
+    birthtimeNs: initial.birthtimeNs?.toString() || null });
+  const binding = {
+    requested, canonical, mode, identity,
+    assertUnchanged() {
+      if (released) throw changed();
+      try {
+        const selected = fs.statSync(requested, { bigint: true });
+        const target = fs.statSync(canonical, { bigint: true });
+        const original = fd === undefined ? initial : fs.fstatSync(fd, { bigint: true });
+        if (!sameDirectory(initial, original) || !sameDirectory(initial, selected) ||
+            !sameDirectory(initial, target)) throw changed();
+      } catch { throw changed(); }
+    },
+    dropDescriptor() {
+      if (released) return;
+      if (fd !== undefined) { fs.closeSync(fd); fd = undefined; }
+      binding.mode = 'stat-only';
+    },
+    release() {
+      if (released) return;
+      released = true;
+      if (fd !== undefined) { fs.closeSync(fd); fd = undefined; }
+    }
+  };
+  try {
+    binding.assertUnchanged();
+    if (expectedIdentity && !sameSelectedCwdIdentity(expectedIdentity, binding)) throw changed();
+  }
+  catch (error) { binding.release(); throw error; }
+  return binding;
+}

package/lib/runtime/buffer-evidence.mjs

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
 
-import { resolvePeerEvidence } from '../core/peers/evidence.mjs';
+import { isPeerEvidenceCompatibilityProtected, resolvePeerEvidence } from '../core/peers/evidence.mjs';
 import { inspectProcessIdentity } from '../process/identity.mjs';
 import { resolveProjectDatabase } from './project-path.mjs';
 
@@ -262,6 +262,9 @@ export function collectBufferEvidence({
       if (evidence.state === 'live') {
         recordKnownEvidence(unknownTracker, file, 'live', monotonicNowMs);
         addExternalGroup(protectedPaths, directory, id);
+      } else if (isPeerEvidenceCompatibilityProtected(evidence)) {
+        recordKnownEvidence(unknownTracker, file, 'incompatible', monotonicNowMs);
+        addExternalGroup(protectedPaths, directory, id);
       } else if (evidence.state === 'unknown' &&
           boundedUnknown(file, { nowMs, monotonicNowMs, unknownGraceMs, unknownTracker, gcCutoffs })) {
         addExternalGroup(unknownPaths, directory, id);
@@ -303,6 +306,9 @@ export function collectBufferEvidence({
         if (evidence.state === 'live') {
           recordKnownEvidence(unknownTracker, file, 'live', monotonicNowMs);
           protectedPaths.add(file);
+        } else if (isPeerEvidenceCompatibilityProtected(evidence)) {
+          recordKnownEvidence(unknownTracker, file, 'incompatible', monotonicNowMs);
+          protectedPaths.add(file);
         } else if (evidence.state === 'unknown' &&
             boundedUnknown(file, { nowMs, monotonicNowMs, unknownGraceMs, unknownTracker, gcCutoffs })) {
           unknownPaths.add(file);

package/lib/runtime/client.mjs

@@ -2,6 +2,8 @@ import { CliError } from '../shared/errors.mjs';
 import { readRuntime } from './state.mjs';
 import { runtimeApiUrl, runtimeHttpRequest } from '../web/runtime.mjs';
 import { withRuntimeApiVersionHeader } from '../web/api-version.mjs';
+import { assertSelectedCwdSnapshot } from '../process/selected-cwd-identity.mjs';
+import { performance } from 'node:perf_hooks';
 
 const DEFAULT_CLI_NAME = 'hcc';
 export const RUNTIME_SESSION_START_TIMEOUT_MS = 60_000;
@@ -46,17 +48,27 @@ function waitForAbort(promise, signal) {
 }
 
 export async function runtimeRequest(ctx, method, route, body = null, runtime = null, opts = {}) {
+  const expectedRootIdentity = ctx.initialRootIdentity || ctx.rootIdentity;
+  if (expectedRootIdentity) assertSelectedCwdSnapshot(expectedRootIdentity);
   const cliName = opts.cliName || DEFAULT_CLI_NAME;
   const rt = runtime || readRuntime(ctx, { cliName, localOnly: Boolean(opts.localOnly) });
   const url = runtimeApiUrl(rt, route);
   const headers = withRuntimeApiVersionHeader({ 'Content-Type': 'application/json' });
   headers['X-HCC-Root'] = ctx.root;
   headers['X-HCC-DB'] = ctx.dbPath;
+  if (expectedRootIdentity) {
+    headers['X-HCC-Root-Identity'] = Buffer.from(JSON.stringify({
+      canonical: expectedRootIdentity.canonical,
+      identity: expectedRootIdentity.identity
+    })).toString('base64url');
+  }
   if (rt.token) headers.Authorization = `Bearer ${rt.token}`;
   let res;
   let text;
   const abortScope = requestAbortScope(opts.signal, opts.timeoutMs);
+  const startedAt = performance.now();
   try {
+    abortScope.signal.throwIfAborted();
     res = await waitForAbort(runtimeHttpRequest(rt, route, {
       method,
       headers,
@@ -68,7 +80,12 @@ export async function runtimeRequest(ctx, method, route, body = null, runtime =
   } catch (err) {
     throw new CliError('RUNTIME_UNREACHABLE', `Runtime is not reachable at ${rt.base_url}. Start ${cliName} web again.`, {
       runtime: rt.source || rt.base_url,
-      message: err.message
+      message: err.message,
+      method,
+      path: url.pathname,
+      elapsedMs: Math.round(performance.now() - startedAt),
+      timeoutMs: opts.timeoutMs === undefined ? 8000 : opts.timeoutMs,
+      errorName: err.name || 'Error'
     });
   } finally {
     abortScope.cleanup();

package/lib/runtime/native/client.mjs

@@ -10,7 +10,10 @@ export function nativeRequest(ctx, method, route, body = null, { timeoutMs = 350
     let timer;
     const fail = (error) => { clearTimeout(timer); reject(error); };
     const invalid = (message) => new CliError('NATIVE_RESPONSE_INVALID', message, { uncertain: method !== 'GET' });
-    const request = http.request({ host: '127.0.0.1', port: pointer.port, method, path: route,
+    // Synchronous CLI work can delay processing an idle socket's remote close.
+    // Use a fresh loopback connection for each request instead of reusing it;
+    // uncertain mutations must not be repaired by replaying the request.
+    const request = http.request({ host: '127.0.0.1', port: pointer.port, method, path: route, agent: false,
       headers: { authorization: `Bearer ${pointer.token}`, ...(payload ? { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) } : {}) }
     }, (response) => {
       let data = '';

package/lib/runtime/native/history.mjs

@@ -0,0 +1,140 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { DatabaseSync } from 'node:sqlite';
+import { CliError } from '../../shared/errors.mjs';
+import { redactSecrets } from '../../shared/redact.mjs';
+import { projectStateDir, legacyProjectStateDir } from '../paths.mjs';
+import { ensurePrivateProjectStateDir } from '../private-state.mjs';
+import { unsafeDirectoryAcl } from '../project-trust.mjs';
+import { nativePaths } from './store.mjs';
+
+const PAGE_SIZE = 100;
+const WORKER_COLUMNS = 'peer, provider, session_id, cwd, status, updated_at';
+
+function missing(file) {
+  try { return fs.lstatSync(file); }
+  catch (error) { if (error?.code === 'ENOENT') return null; throw error; }
+}
+
+function unavailable() {
+  return new CliError('NATIVE_HISTORY_UNAVAILABLE', 'Stored native history cannot be read; inspect the native state before retrying');
+}
+
+function validateEntry(file, directory = false) {
+  const stat = missing(file);
+  if (!stat) return null;
+  if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile() || stat.nlink !== 1) ||
+      (typeof process.getuid === 'function' && stat.uid !== process.getuid()) ||
+      (process.platform !== 'win32' && (stat.mode & 0o022) !== 0) || unsafeDirectoryAcl(file, stat)) {
+    throw new CliError('NATIVE_STATE_UNSAFE', 'Stored native history must use owned state without symlinks or writable aliases');
+  }
+  return stat;
+}
+
+function historyPaths(ctx) {
+  const root = fs.realpathSync(ctx.root), state = projectStateDir(root);
+  if (state === legacyProjectStateDir(root)) {
+    // History is project-state scoped, not an authority to follow a caller's
+    // arbitrary --db path into another project. The live runtime validates
+    // its selected DB separately before it may write.
+    return nativePaths({ root: ctx.root, dbPath: path.join(root, '.hello-cc', 'mesh.db'),
+      initialRootIdentity: ctx.initialRootIdentity });
+  }
+  // The general resolver repairs missing/pending private authority markers.
+  // History must not perform that transition or tighten existing permissions.
+  const existing = ensurePrivateProjectStateDir(root, { create: false });
+  if (!existing) return null;
+  const dir = path.join(existing, 'native');
+  if (!validateEntry(dir, true)) return null;
+  for (const name of ['runtime.json', 'state.db', 'state.db-wal', 'state.db-shm', 'runtime.log']) {
+    try { validateEntry(path.join(dir, name)); }
+    catch (error) {
+      if ((name === 'state.db-wal' || name === 'state.db-shm') && !missing(path.join(dir, name))) continue;
+      throw error;
+    }
+  }
+  return { dir, db: path.join(dir, 'state.db') };
+}
+
+function withHistory(ctx, read, absent) {
+  let db;
+  try {
+    const paths = historyPaths(ctx);
+    if (!paths) return absent();
+    const before = validateEntry(paths.db);
+    if (!before) return absent();
+    // A read-only SQLite connection preserves committed data still in WAL.
+    // SQLite may maintain its own WAL/SHM sidecars; never initialize a store,
+    // run migrations, chmod state, or alter project records here.
+    db = new DatabaseSync(paths.db, { readOnly: true, timeout: 1000 });
+    const after = validateEntry(paths.db);
+    if (!after || before.dev !== after.dev || before.ino !== after.ino) throw unavailable();
+    db.exec('BEGIN'); // Keep the worker and its retained rows in one read snapshot.
+    const result = read(db);
+    const current = validateEntry(paths.db);
+    if (!current || before.dev !== current.dev || before.ino !== current.ino) throw unavailable();
+    const safe = redactSecrets(result);
+    for (const row of safe.workers || (safe.worker ? [safe.worker] : [])) {
+      if (row.capabilities_json !== undefined && row.capabilities_json !== null) row.capabilities_json = JSON.stringify(row.capabilities_json);
+    }
+    for (const row of safe.deliveries || []) {
+      if (row.detail !== undefined && row.detail !== null) row.detail = JSON.stringify(row.detail);
+    }
+    return safe;
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw unavailable();
+  } finally { if (db) db.close(); }
+}
+
+function workerColumns(db) {
+  const columns = db.prepare('PRAGMA table_info(workers)').all();
+  return WORKER_COLUMNS + (columns.some(column => column.name === 'cwd_identity')
+    ? ', cwd_identity' : ', NULL AS cwd_identity') +
+    (columns.some(column => column.name === 'capabilities_json') ? ', capabilities_json' : '');
+}
+
+function parseStored(value) {
+  if (value === null || value === undefined) return value;
+  try { return JSON.parse(value); }
+  catch { throw new CliError('NATIVE_HISTORY_INVALID', 'Stored native history contains invalid event data'); }
+}
+
+function workerRow(row) {
+  if (row && row.capabilities_json !== undefined && row.capabilities_json !== null) {
+    return { ...row, capabilities_json: parseStored(row.capabilities_json) };
+  }
+  return row;
+}
+
+export function readNativeHistory(ctx, { limit = PAGE_SIZE } = {}) {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > PAGE_SIZE) {
+    throw new CliError('BAD_ARGS', 'Native history limit must be an integer from 1 to 100');
+  }
+  return withHistory(ctx, db => {
+    const rows = db.prepare('SELECT ' + workerColumns(db) + ' FROM workers ORDER BY updated_at DESC, peer LIMIT ?').all(limit + 1);
+    return { workers: rows.slice(0, limit).map(workerRow), truncated: rows.length > limit };
+  }, () => ({ workers: [], truncated: false }));
+}
+
+export function readNativeWorkerHistory(ctx, peer, { after = 0 } = {}) {
+  if (typeof peer !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(peer) || peer.toLowerCase() === 'all') {
+    throw new CliError('BAD_ARGS', 'Native history requires one valid worker name');
+  }
+  if (!Number.isSafeInteger(after) || after < 0) throw new CliError('BAD_ARGS', 'Native history cursor must be a nonnegative safe integer');
+  const absent = () => { throw new CliError('NATIVE_HISTORY_NOT_FOUND', 'No retained native history exists for this worker'); };
+  return withHistory(ctx, db => {
+    const worker = workerRow(db.prepare('SELECT ' + workerColumns(db) + ' FROM workers WHERE peer = ?').get(peer));
+    if (!worker) return absent();
+    const rows = db.prepare('SELECT id, peer, payload, created_at FROM provider_events WHERE peer = ? AND id > ? ORDER BY id LIMIT ?')
+      .all(peer, after, PAGE_SIZE + 1);
+    const deliveries = db.prepare('SELECT * FROM deliveries WHERE peer = ? ORDER BY id DESC LIMIT ?').all(peer, PAGE_SIZE + 1);
+    const events = rows.slice(0, PAGE_SIZE).map(row => ({ ...row, payload: parseStored(row.payload) }));
+    return { worker, events,
+      deliveries: deliveries.slice(0, PAGE_SIZE).map(row => ({ ...row,
+        detail: parseStored(row.detail) })),
+      truncated: rows.length > PAGE_SIZE, deliveriesTruncated: deliveries.length > PAGE_SIZE,
+      nextAfter: events.at(-1)?.id ?? after };
+  }, absent);
+}

package/lib/runtime/native/launcher.mjs

@@ -0,0 +1,106 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import net from 'node:net';
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { CliError } from '../../shared/errors.mjs';
+import { fileLockEndpoint } from '../../shared/file-lock.mjs';
+import { openPrivateAppendFile } from '../private-file.mjs';
+import { nativePaths, readNativePointer } from './store.mjs';
+import { nativeRequest } from './client.mjs';
+import { spawnPinnedCwdProcess } from '../../process/pinned-cwd.mjs';
+import { assertSelectedCwdSnapshot, captureSelectedCwdSnapshot } from '../../process/selected-cwd-identity.mjs';
+
+// Shared by CLI and Web. The in-process promise and short-lived loopback lock
+// prevent concurrent launchers from spawning competing project daemons.
+export function createNativeLauncher({ spawnProcess = spawn, request = nativeRequest,
+  env = process.env, startupTimeoutMs = 10000, pollMs = 100 } = {}) {
+  const starting = new Map();
+
+  async function readReady(ctx) {
+    if (!readNativePointer(ctx)) return null;
+    try {
+      const status = await request(ctx, 'GET', '/status', null, { timeoutMs: 2000 });
+      if (!status || status.root !== ctx.root || status.meshDb !== ctx.dbPath ||
+          typeof status.generation !== 'string' || !status.generation) {
+        throw new CliError('NATIVE_RESPONSE_INVALID', 'Native runtime does not match this project');
+      }
+      if (status.stopping) throw new CliError('NATIVE_RUNTIME_STOPPING', 'Native runtime is stopping; finish its shutdown before creating another worker');
+      return status;
+    } catch (error) {
+      if (error.code === 'NATIVE_RUNTIME_OFFLINE') return null;
+      throw error;
+    }
+  }
+
+  async function launch(ctx) {
+    const ready = await readReady(ctx);
+    if (ready) return ready;
+    const paths = nativePaths(ctx, { create: true });
+    const endpoint = fileLockEndpoint(path.join(paths.dir, 'launcher-owner'));
+    const deadline = Date.now() + startupTimeoutMs;
+    let lock;
+    while (!lock && Date.now() < deadline) {
+      const candidate = net.createServer(socket => socket.end());
+      const acquired = await new Promise((resolve, reject) => {
+        candidate.once('error', error => error.code === 'EADDRINUSE' ? resolve(false) : reject(error));
+        candidate.listen(endpoint.port, '127.0.0.1', () => resolve(true));
+      });
+      if (acquired) lock = candidate;
+      else {
+        const existing = await readReady(ctx);
+        if (existing) return existing;
+        await delay(pollMs);
+      }
+    }
+    if (!lock) throw new CliError('NATIVE_RUNTIME_START_FAILED', 'Another native launcher is still starting; inspect native status before retrying');
+    try {
+      const existing = await readReady(ctx);
+      if (existing) return existing;
+      let log, child;
+      try {
+        log = openPrivateAppendFile(paths.log);
+        child = spawnPinnedCwdProcess(process.execPath, [fileURLToPath(new URL('../../../bin/hcc.mjs', import.meta.url)), '--root', ctx.root, '--db', ctx.dbPath, 'native', 'serve'], {
+          cwd: ctx.root, expectedIdentity: ctx.initialRootIdentity,
+          env, detached: true, stdio: ['ignore', log, log]
+        }, spawnProcess);
+      } catch (error) {
+        if (error?.code === 'PROJECT_PATH_FORBIDDEN') throw new CliError('NATIVE_STATE_UNSAFE', error.message);
+        throw error;
+      } finally {
+        if (log !== undefined) fs.closeSync(log);
+      }
+      let failed;
+      let exited;
+      child.on('error', error => { failed = error; });
+      child.once('exit', (code, signal) => { exited = { code, signal }; });
+      child.unref();
+      while (Date.now() < deadline) {
+        if (failed) throw new CliError('NATIVE_RUNTIME_START_FAILED', failed.message);
+        if (exited) throw new CliError('NATIVE_RUNTIME_START_FAILED',
+          `Native runtime exited before it became ready (code=${exited.code ?? ''}${exited.signal ? ` signal=${exited.signal}` : ''}). Inspect ${paths.log}`);
+        const status = await readReady(ctx);
+        if (status) return status;
+        await delay(pollMs);
+      }
+      throw new CliError('NATIVE_RUNTIME_START_FAILED', `Native runtime did not become ready. Inspect native status and ${paths.log} before retrying`);
+    } finally { await new Promise(resolve => lock.close(resolve)); }
+  }
+
+  return function ensureNativeRuntime(ctx) {
+    const expectedRootIdentity = ctx.initialRootIdentity || ctx.rootIdentity || captureSelectedCwdSnapshot(ctx.root);
+    assertSelectedCwdSnapshot(expectedRootIdentity);
+    const canonical = { ...ctx, root: expectedRootIdentity.canonical,
+      initialRootIdentity: expectedRootIdentity, dbPath: path.resolve(ctx.dbPath) };
+    const key = `${canonical.root}\0${canonical.dbPath}`;
+    if (starting.has(key)) return starting.get(key);
+    const pending = launch(canonical).finally(() => {
+      if (starting.get(key) === pending) starting.delete(key);
+    });
+    starting.set(key, pending);
+    return pending;
+  };
+}
+
+export const ensureNativeRuntime = createNativeLauncher();