@logicseek/hello-cc 1.1.0-rc.8 → 1.1.0

package/lib/mcp/tools.mjs

@@ -20,6 +20,7 @@ import { captureLockAcquireSubject, sameLockAcquireSubject, observeLockOwnerEvid
 import { runOptimisticEvidenceMutation } from '../core/coordination/optimistic-evidence.mjs';
 import { normalizeListText } from '../handoff.mjs';
 import { listTaskResults, recordTaskResult } from '../core/coordination/results.mjs';
+import { acquireNativeOwnerWrite } from '../runtime/native/store.mjs';
 
 const string = (maxLength = 4096) => ({ type: 'string', minLength: 1, maxLength });
 const integer = (maximum = Number.MAX_SAFE_INTEGER) => ({ type: 'integer', minimum: 1, maximum });
@@ -81,7 +82,9 @@ function validate(value, schema, label) {
 
 export function createScopedMcpTools({ ctx, authority, connect: baseConnect, touchPeer, now, addEvent }) {
   const peer = authority.scope.peer, scopedCtx = { ...ctx, cwd: authority.scope.root,
-    root: authority.scope.root, dbPath: authority.scope.dbPath, json: true };
+    root: authority.scope.root, dbPath: authority.scope.dbPath, json: true,
+    rootIdentity: authority.scope.rootIdentity || ctx.rootIdentity,
+    initialRootIdentity: authority.scope.rootIdentity || ctx.initialRootIdentity };
   let captured, databases = [], active = false, taskGuard = null;
   function assertWrite(db) {
     authority.assertOwnership(db);
@@ -91,6 +94,7 @@ export function createScopedMcpTools({ ctx, authority, connect: baseConnect, tou
     }
   }
   function connect() {
+    authority.assertValid();
     const db = baseConnect(scopedCtx, { create: false, migrateRegistered: false });
     databases.push(db);
     authority.assertOwnership(db);
@@ -178,10 +182,16 @@ export function createScopedMcpTools({ ctx, authority, connect: baseConnect, tou
     async call(name, args) {
       if (active) return { isError: true, content: [{ type: 'text', text: 'A scoped tool call is already running' }] };
       active = true; captured = undefined; databases = []; taskGuard = null;
+      let finishNative;
       try {
         if (!byName.has(name)) throw new CliError('BAD_ARGS', 'Unknown scoped tool');
         validate(args, byName.get(name).inputSchema, 'arguments');
         authority.assertValid();
+        // The state owner lock precedes connect(), which may initialize the
+        // mesh schema, and stays held through every nested command transaction.
+        if (authority.scope.nativeOwnerGeneration) {
+          finishNative = acquireNativeOwnerWrite(scopedCtx, authority.scope.nativeOwnerGeneration);
+        }
         const direct = await execute(name, args);
         const structuredContent = redactSecrets({ ok: true, peer, data: captured === undefined ? direct : captured });
         return { content: [{ type: 'text', text: JSON.stringify(structuredContent) }], structuredContent, isError: false };
@@ -191,7 +201,10 @@ export function createScopedMcpTools({ ctx, authority, connect: baseConnect, tou
           message: error instanceof CliError ? error.message : 'The scoped tool call failed'
         } });
         return { content: [{ type: 'text', text: JSON.stringify(structuredContent) }], structuredContent, isError: true };
-      } finally { for (const db of databases) { try { db.close(); } catch {} } active = false; }
+      } finally {
+        for (const db of databases) { try { db.close(); } catch {} }
+        try { finishNative?.(); } finally { active = false; }
+      }
     }
   };
 }

package/lib/process/pinned-cwd.mjs

@@ -144,6 +144,25 @@ function pinnedBootstrap() {
 
 export const PINNED_CWD_BOOTSTRAP_SOURCE = '(' + pinnedBootstrap.toString() + ')()';
 
+export const PINNED_LAUNCH_MODE_ENV = 'HCC_PINNED_LAUNCH_MODE';
+
+export function assertPinnedSessionLaunchAllowed(options = {}) {
+  if (options.purpose === 'maintenance') return;
+  // Provider child environments may deliberately strip HCC_* variables. The
+  // parent rollout setting must still govern the launch in that case; a
+  // per-launch environment can only make the gate stricter, never clear it.
+  const modes = [process.env[PINNED_LAUNCH_MODE_ENV], options.env?.[PINNED_LAUNCH_MODE_ENV]]
+    .filter(value => value !== undefined && value !== '');
+  if (modes.some(mode => mode !== 'pinned' && mode !== 'hold')) {
+    throw new CliError('PINNED_LAUNCH_MODE_INVALID',
+      `${PINNED_LAUNCH_MODE_ENV} must be pinned or hold`);
+  }
+  if (modes.includes('hold')) {
+    throw new CliError('PINNED_LAUNCH_PAUSED',
+      'New session launches are paused; existing processes remain running');
+  }
+}
+
 function sameIdentity(left, right) {
   return left.dev === right.dev && left.ino === right.ino &&
     left.birthtimeNs === right.birthtimeNs;
@@ -169,6 +188,50 @@ function bootstrapDirectory(override) {
   return ensurePrivateGlobalSubdirectory('launches');
 }
 
+// Capture a directory descriptor for helpers that can pass it across a
+// process boundary with SCM_RIGHTS. Unlike the Node bootstrap, the consumer
+// never has to resolve the pathname again after this function returns.
+export function captureTrustedDirectoryFd(cwd, expectedIdentity = null) {
+  assertPinnedSessionLaunchAllowed();
+  if (process.platform !== 'darwin' && process.platform !== 'linux') {
+    throw new CliError('PINNED_CWD_UNAVAILABLE', 'Trusted directory handoff requires macOS or Linux');
+  }
+  const requested = path.resolve(cwd);
+  let canonical;
+  try { canonical = fs.realpathSync.native(requested); }
+  catch { throw new CliError('PROJECT_PATH_FORBIDDEN', 'Selected working directory is unavailable'); }
+
+  let fd;
+  try {
+    fd = fs.openSync(canonical,
+      fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+    const stat = fs.fstatSync(fd, { bigint: true });
+    const current = fs.statSync(requested, { bigint: true });
+    if (!stat.isDirectory() || !sameIdentity(stat, current)) {
+      throw new CliError('PROJECT_PATH_CHANGED', 'Selected working directory changed during capture');
+    }
+    const identity = directoryIdentity(stat, canonical, requested, 'descriptor');
+    if (expectedIdentity &&
+        (identity.cwd !== expectedIdentity.canonical ||
+          identity.dev !== expectedIdentity.identity?.dev ||
+          identity.ino !== expectedIdentity.identity?.ino ||
+          identity.birthtimeNs !== expectedIdentity.identity?.birthtimeNs)) {
+      throw new CliError('PROJECT_PATH_CHANGED', 'Selected working directory changed before launch');
+    }
+    return {
+      fd,
+      identity,
+      release() {
+        if (fd !== undefined) { fs.closeSync(fd); fd = undefined; }
+      }
+    };
+  } catch (error) {
+    if (fd !== undefined) fs.closeSync(fd);
+    if (error instanceof CliError) throw error;
+    throw new CliError('PROJECT_PATH_FORBIDDEN', 'Selected working directory cannot be pinned');
+  }
+}
+
 function acknowledgementState(ack) {
   if (!ack) return null;
   let fd;
@@ -198,6 +261,7 @@ function removeOwnedAcknowledgement(ack) {
 // only when the child has established its cwd or exited; retaining it while a
 // child starts prevents inode reuse from satisfying a stale dev/ino snapshot.
 export function preparePinnedCwdLaunch(cwd, command, args = [], options = {}) {
+  assertPinnedSessionLaunchAllowed(options);
   if (process.platform === 'win32') {
     throw new CliError('PINNED_CWD_UNAVAILABLE', 'Pinned cwd launch requires POSIX directory identity');
   }

package/lib/process/pinned-guidance.mjs

@@ -97,6 +97,7 @@ function runPinnedGuidance(root, mode, content = '', {
   if (expectedSnapshot) assertSelectedCwdSnapshot(expectedSnapshot);
   const binding = preparePinnedCwdLaunch(root, process.execPath,
     ['-e', GUIDANCE_WORKER_SOURCE, mode, content], {
+      purpose: 'maintenance',
       // The worker needs only built-ins. Do not permit inherited Node preload
       // hooks to run before it can operate on relative names.
       env: { PATH: '/usr/bin:/bin', NODE_OPTIONS: '', NODE_NO_WARNINGS: '1' }

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

@@ -63,6 +63,7 @@ function runPinnedStateWorker(cwd, mode, expectedCwd, targetIdentity, content, s
   expectedCwd.assertUnchanged();
   const binding = preparePinnedCwdLaunch(cwd, process.execPath,
     ['-e', PROJECT_STATE_WORKER_SOURCE, mode, JSON.stringify(targetIdentity), content], {
+      purpose: 'maintenance',
       env: { PATH: '/usr/bin:/bin', NODE_OPTIONS: '', NODE_NO_WARNINGS: '1' }
     });
   try {

package/lib/process/tmux-cwd-handoff.mjs

@@ -0,0 +1,277 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { spawn } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { CliError } from '../shared/errors.mjs';
+import { assertPinnedSessionLaunchAllowed, captureTrustedDirectoryFd } from './pinned-cwd.mjs';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const BROKER_TIMEOUT_MS = 25_000;
+const BIND_TIMEOUT_MS = 6_000;
+const bindSleep = new Int32Array(new SharedArrayBuffer(4));
+
+function writeBrokerAuthorizationSync(broker, message) {
+  // The Web launch API is synchronous. A Writable.end(message) can queue its
+  // pipe write on the Node event loop, which is blocked while waiting for the
+  // native bind receipt. Require an actual child-stdin descriptor and send the
+  // tiny ALLOW line synchronously; if this Node runtime stops exposing it,
+  // refuse the launch rather than hang or admit an unbound pane.
+  const fd = broker.stdin?._handle?.fd;
+  if (!Number.isSafeInteger(fd) || fd < 0) {
+    throw new CliError('PINNED_CWD_UNAVAILABLE', 'Trusted tmux broker stdin is unavailable');
+  }
+  const bytes = Buffer.from(message, 'ascii');
+  const deadline = Date.now() + 250;
+  let offset = 0;
+  while (offset < bytes.length) {
+    try {
+      const written = fs.writeSync(fd, bytes, offset, bytes.length - offset);
+      if (written <= 0) throw new Error('Broker authorization pipe made no progress');
+      offset += written;
+    } catch (error) {
+      if (!['EAGAIN', 'EINTR'].includes(error?.code) || Date.now() >= deadline) {
+        throw new CliError('PINNED_CWD_UNAVAILABLE',
+          'Could not authorize the trusted tmux broker synchronously');
+      }
+      Atomics.wait(bindSleep, 0, 0, 5);
+    }
+  }
+  broker.stdin.end();
+}
+
+function killStartedBroker(broker) {
+  // ChildProcess.kill() is unsafe for a failed spawn with pid === undefined:
+  // some Node/libuv versions may signal the calling process instead.
+  if (Number.isSafeInteger(broker?.pid) && broker.pid > 0 &&
+      broker.exitCode === null && broker.signalCode === null) broker.kill();
+}
+
+export function trustedCwdHandoffBinary() {
+  if (!['darwin', 'linux'].includes(process.platform)) {
+    throw new CliError('PINNED_CWD_UNAVAILABLE', 'Trusted tmux directory handoff requires macOS or Linux');
+  }
+  const binary = path.join(packageRoot, 'native', 'bin',
+    `${process.platform}-${process.arch}`, 'hcc-cwd-handoff');
+  let stat;
+  try { stat = fs.lstatSync(binary); }
+  catch {
+    throw new CliError('PINNED_CWD_UNAVAILABLE',
+      `Trusted tmux directory helper is not packaged for ${process.platform}-${process.arch}`);
+  }
+  if (!stat.isFile() || (stat.mode & 0o022) !== 0) {
+    throw new CliError('PINNED_CWD_UNAVAILABLE', 'Trusted tmux directory helper is unsafe');
+  }
+  try { fs.accessSync(binary, fs.constants.X_OK); }
+  catch { throw new CliError('PINNED_CWD_UNAVAILABLE', 'Trusted tmux directory helper is not executable'); }
+  // A source checkout can contain an old prebuilt helper after a C edit. The
+  // release gate checks all four targets; also fail closed during local use.
+  try {
+    const source = fs.readFileSync(path.join(packageRoot, 'native', 'cwd-handoff', 'hcc-cwd-handoff.c'));
+    const marker = Buffer.from('HCC_SOURCE_SHA256:' + createHash('sha256').update(source).digest('hex'));
+    if (!fs.readFileSync(binary).includes(marker)) throw new Error('source hash mismatch');
+  } catch {
+    throw new CliError('PINNED_CWD_UNAVAILABLE', 'Trusted tmux directory helper does not match packaged source');
+  }
+  return binary;
+}
+
+function removeOwnedSocketDirectory(directory, identity) {
+  try {
+    const current = fs.lstatSync(directory);
+    if (!current.isDirectory() || current.dev !== identity.dev || current.ino !== identity.ino) return;
+    const socket = path.join(directory, 's');
+    try {
+      if (fs.lstatSync(socket).isSocket()) fs.unlinkSync(socket);
+    } catch (error) { if (error?.code !== 'ENOENT') return; }
+    for (const name of ['s.bound', 's.bound.tmp']) {
+      const receipt = path.join(directory, name);
+      try {
+        const stat = fs.lstatSync(receipt);
+        if (!stat.isFile() || stat.uid !== process.getuid?.() || stat.nlink !== 1) return;
+        fs.unlinkSync(receipt);
+      } catch (error) { if (error?.code !== 'ENOENT') return; }
+    }
+    fs.rmdirSync(directory);
+  } catch {}
+}
+
+function executableFromPinnedCwd(command, identity) {
+  if (!path.isAbsolute(command)) return command;
+  for (const root of [identity.cwd, identity.requestedCwd]) {
+    const relative = path.relative(root, command);
+    if (relative === '') return '.';
+    if (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)) {
+      return `.${path.sep}${relative}`;
+    }
+  }
+  return command;
+}
+
+function handoffEnvironment(env) {
+  const safe = { ...env };
+  // The client is a native executable. Dynamic-loader hooks would execute
+  // before its peer authentication and fchdir, so they cannot be inherited
+  // across this boundary. PWD is published only by the client after binding.
+  for (const key of Object.keys(safe)) {
+    if (key === 'PWD' || key.startsWith('LD_') || key.startsWith('DYLD_')) delete safe[key];
+  }
+  return safe;
+}
+
+// The broker inherits the already-validated directory as fd 3. The tmux pane
+// sees only a trusted helper and a private socket path; it never resolves the
+// user's pathname. No directory fd is sent until the parent authorizes the
+// immutable pane PID returned by tmux new-session -P.
+export function prepareTmuxCwdHandoff({ cwd, expectedIdentity, shell, command, env }, {
+  binary,
+  spawnBroker = spawn,
+  tempRoot = '/tmp'
+} = {}) {
+  assertPinnedSessionLaunchAllowed({ env });
+  if (typeof shell !== 'string' || !shell || typeof command !== 'string') {
+    throw new CliError('BAD_ARGS', 'Trusted tmux launch requires shell and command');
+  }
+  binary ||= trustedCwdHandoffBinary();
+  const captured = captureTrustedDirectoryFd(cwd, expectedIdentity);
+  const nonce = randomBytes(32).toString('hex');
+  let directory;
+  let broker;
+  let failed = false;
+  try {
+    directory = fs.mkdtempSync(path.join(tempRoot, 'hccfd-'));
+    fs.chmodSync(directory, 0o700);
+    const socket = path.join(directory, 's');
+    const receipt = `${socket}.bound`;
+    if (Buffer.byteLength(socket) >= 100) {
+      throw new CliError('PINNED_CWD_UNAVAILABLE', 'Private helper socket path is too long');
+    }
+    const directoryStat = fs.lstatSync(directory);
+    const brokerArgs = [
+      'broker', '--socket', socket, '--dir-fd', '3',
+      '--dev', captured.identity.dev, '--ino', captured.identity.ino,
+      '--nonce', nonce
+    ];
+    broker = spawnBroker(binary, brokerArgs, {
+      cwd: '/',
+      env: { PATH: '/usr/bin:/bin' },
+      stdio: ['pipe', 'pipe', 'pipe', captured.fd]
+    });
+    // spawn() can return a ChildProcess without a PID and emit ENOENT on the
+    // next tick. Install both listeners before validating the returned child
+    // so a failed helper launch cannot crash the Web runtime afterward.
+    broker?.on?.('error', () => { failed = true; });
+    broker?.stdin?.on?.('error', () => { failed = true; });
+    if (!broker?.pid || !broker.stdin || !broker.stdout) {
+      throw new CliError('PINNED_CWD_UNAVAILABLE', 'Trusted tmux directory broker did not start');
+    }
+    // The child now owns its independent copy; the parent no longer needs to
+    // retain A's fd. The broker's native timeout bounds any ambiguous launch.
+    captured.release();
+    let bound = false;
+    let released = false;
+    let authorized = false;
+    let output = '';
+    const timer = setTimeout(() => {
+      failed = true;
+      killStartedBroker(broker);
+    }, BROKER_TIMEOUT_MS);
+    timer.unref?.();
+    broker.stdout.on('data', chunk => {
+      output += chunk.toString('utf8');
+      if (output.length > 1024) { failed = true; killStartedBroker(broker); return; }
+      for (;;) {
+        const end = output.indexOf('\n');
+        if (end < 0) break;
+        const line = output.slice(0, end);
+        output = output.slice(end + 1);
+        if (line === 'READY') continue;
+        if (line === 'BOUND' && authorized) { bound = true; continue; }
+        failed = true;
+        killStartedBroker(broker);
+        break;
+      }
+    });
+    broker.on('close', () => {
+      if (!bound) failed = true;
+      clearTimeout(timer);
+      removeOwnedSocketDirectory(directory, directoryStat);
+    });
+    return {
+      cwd: '/',
+      command: binary,
+      args: ['client', '--socket', socket,
+        '--dev', captured.identity.dev, '--ino', captured.identity.ino,
+        '--nonce', nonce, '--', executableFromPinnedCwd(shell, captured.identity), '-c', command],
+      env: handoffEnvironment(env),
+      identity: captured.identity,
+      authorize(panePid) {
+        if (authorized || failed || !Number.isSafeInteger(panePid) || panePid <= 0) {
+          throw new CliError('PINNED_CWD_UNAVAILABLE', 'Cannot authorize trusted tmux pane');
+        }
+        authorized = true;
+        writeBrokerAuthorizationSync(broker, `ALLOW ${panePid} ${nonce}\n`);
+      },
+      waitBoundSync(timeoutMs = BIND_TIMEOUT_MS) {
+        if (!authorized || failed || released) {
+          throw new CliError('PINNED_CWD_UNAVAILABLE', 'Trusted tmux pane is not authorized for directory handoff');
+        }
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() <= deadline) {
+          try {
+            const parent = fs.lstatSync(directory);
+            if (!parent.isDirectory() || parent.isSymbolicLink() ||
+                parent.dev !== directoryStat.dev || parent.ino !== directoryStat.ino ||
+                parent.uid !== process.getuid?.() || (parent.mode & 0o077) !== 0) {
+              throw new CliError('PINNED_CWD_UNAVAILABLE', 'Private directory handoff parent changed');
+            }
+            const before = fs.lstatSync(receipt);
+            if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 ||
+                before.uid !== process.getuid?.() || (before.mode & 0o777) !== 0o600 ||
+                before.size !== 65) {
+              throw new CliError('PINNED_CWD_UNAVAILABLE', 'Private directory handoff receipt is unsafe');
+            }
+            const fd = fs.openSync(receipt, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_CLOEXEC);
+            let data;
+            try {
+              const opened = fs.fstatSync(fd);
+              if (opened.dev !== before.dev || opened.ino !== before.ino || opened.size !== 65) {
+                throw new CliError('PINNED_CWD_UNAVAILABLE', 'Private directory handoff receipt changed');
+              }
+              data = fs.readFileSync(fd, 'ascii');
+            } finally { fs.closeSync(fd); }
+            if (data !== `${nonce}\n`) {
+              throw new CliError('PINNED_CWD_UNAVAILABLE', 'Private directory handoff receipt does not match');
+            }
+            fs.unlinkSync(receipt);
+            bound = true;
+            return true;
+          } catch (error) {
+            if (error?.code !== 'ENOENT') throw error;
+          }
+          Atomics.wait(bindSleep, 0, 0, 20);
+        }
+        throw new CliError('PINNED_CWD_UNAVAILABLE', 'Trusted tmux pane did not confirm directory binding');
+      },
+      acknowledged() { return bound; },
+      failed() { return failed; },
+      release() {
+        if (released) return;
+        released = true;
+        clearTimeout(timer);
+        if (!bound) killStartedBroker(broker);
+        if (broker.exitCode !== null || broker.signalCode !== null) {
+          removeOwnedSocketDirectory(directory, directoryStat);
+        }
+      }
+    };
+  } catch (error) {
+    captured.release();
+    killStartedBroker(broker);
+    if (directory) {
+      try { fs.rmdirSync(directory); } catch {}
+    }
+    throw error;
+  }
+}

package/lib/runtime/native/cli-submissions.mjs

@@ -0,0 +1,220 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { CliError } from '../../shared/errors.mjs';
+import { ensurePrivateProjectStateSubdirectory } from '../project-path.mjs';
+import { readPrivateTextFile } from '../private-file.mjs';
+import { unsafeDirectoryAcl } from '../project-trust.mjs';
+import { nativePaths } from './store.mjs';
+
+const DIRECTORY = 'native-cli-submissions';
+const UUID = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
+const UUID_VALUE = new RegExp(`^${UUID}$`);
+const PREPARED = new RegExp(`^submission-(${UUID})\\.json$`);
+
+function journalDirectory(ctx, create) {
+  const native = nativePaths(ctx, { create });
+  if (!native) return null;
+  const directory = ensurePrivateProjectStateSubdirectory(ctx.root, DIRECTORY, { create });
+  if (directory && path.dirname(directory) !== path.dirname(native.dir)) {
+    throw new CliError('PROJECT_PATH_CHANGED', 'CLI submissions do not match the selected native state');
+  }
+  if (directory && create) syncDirectory(path.dirname(directory));
+  return directory ? { directory, meshDbRelative: path.relative(path.dirname(native.dir), native.meshDb) } : null;
+}
+
+function syncDirectory(directory) {
+  if (process.platform === 'win32') return;
+  const fd = fs.openSync(directory, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY |
+    (fs.constants.O_NOFOLLOW || 0));
+  try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+}
+
+function writeRecord(directory, name, value) {
+  const file = path.join(directory, name);
+  const temporaryName = `.${name}.tmp.${randomBytes(12).toString('hex')}`;
+  const temporary = path.join(directory, temporaryName);
+  let fd;
+  let opened;
+  try {
+    fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT |
+      fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW || 0), 0o600);
+    opened = fs.fstatSync(fd);
+    if (process.platform !== 'win32') fs.fchmodSync(fd, 0o600);
+    const secured = fs.fstatSync(fd);
+    if (!secured.isFile() || secured.nlink !== 1 || secured.dev !== opened.dev || secured.ino !== opened.ino ||
+        (typeof process.geteuid === 'function' && secured.uid !== process.geteuid()) ||
+        (process.platform !== 'win32' && (secured.mode & 0o777) !== 0o600) ||
+        unsafeDirectoryAcl(temporary, secured)) {
+      throw new Error('Unsafe CLI submission journal file');
+    }
+    fs.writeFileSync(fd, JSON.stringify(value) + '\n');
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    const ready = fs.lstatSync(temporary);
+    if (!ready.isFile() || ready.isSymbolicLink() || ready.nlink !== 1 ||
+        ready.dev !== opened.dev || ready.ino !== opened.ino) {
+      throw new Error('CLI submission journal temporary file changed before publication');
+    }
+    fs.linkSync(temporary, file);
+    try { fs.unlinkSync(temporary); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    syncDirectory(directory);
+    const published = fs.lstatSync(file);
+    if (!published.isFile() || published.isSymbolicLink() || published.nlink !== 1 ||
+        published.dev !== opened.dev || published.ino !== opened.ino) {
+      throw new Error('CLI submission journal file changed after publication');
+    }
+  } catch (error) {
+    if (fd !== undefined) try { fs.closeSync(fd); } catch { /* Preserve the write failure. */ }
+    if (opened) {
+      try {
+        const current = fs.lstatSync(temporary);
+        if (current.dev === opened.dev && current.ino === opened.ino) fs.unlinkSync(temporary);
+      } catch { /* The failed write must never authorize a send. */ }
+    }
+    throw new CliError('NATIVE_CLI_JOURNAL_FAILED', 'Cannot durably save the native CLI submission record',
+      { cause: error.code || 'WRITE_FAILED' });
+  }
+}
+
+function repairPublishedLink(directory, name) {
+  const file = path.join(directory, name);
+  const published = fs.lstatSync(file);
+  if (published.nlink === 1) return;
+  if (!published.isFile() || published.isSymbolicLink() || published.nlink !== 2) {
+    throw new CliError('NATIVE_CLI_JOURNAL_INVALID', 'Native CLI submission journal has an unexpected hard link');
+  }
+  const prefix = `.${name}.tmp.`;
+  for (const candidate of fs.readdirSync(directory)) {
+    if (!candidate.startsWith(prefix)) continue;
+    const temporary = path.join(directory, candidate);
+    let stat;
+    try { stat = fs.lstatSync(temporary); }
+    catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.dev !== published.dev || stat.ino !== published.ino) continue;
+    try { fs.unlinkSync(temporary); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    syncDirectory(directory);
+    const repaired = fs.lstatSync(file);
+    if (repaired.dev === published.dev && repaired.ino === published.ino && repaired.nlink === 1) return;
+    break;
+  }
+  // Another reader may have removed the matching temp link after our first stat.
+  const repaired = fs.lstatSync(file);
+  if (repaired.dev === published.dev && repaired.ino === published.ino && repaired.nlink === 1) return;
+  throw new CliError('NATIVE_CLI_JOURNAL_INVALID', 'Native CLI submission journal has an unresolved hard link');
+}
+
+function readRecord(directory, name) {
+  repairPublishedLink(directory, name);
+  const raw = readPrivateTextFile(path.join(directory, name), { maxBytes: 4096 });
+  if (raw === null) throw new CliError('NATIVE_CLI_JOURNAL_INVALID', 'Native CLI submission journal changed during inspection');
+  try { return JSON.parse(raw); }
+  catch { throw new CliError('NATIVE_CLI_JOURNAL_INVALID', 'Native CLI submission journal is invalid'); }
+}
+
+function optionalRecord(directory, name) {
+  try { fs.lstatSync(path.join(directory, name)); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  return readRecord(directory, name);
+}
+
+function validatePrepared(record, id, root, meshDbRelative) {
+  if (record?.version !== 1 || record.submission_id !== id ||
+      record.root !== root || record.mesh_db_relative !== meshDbRelative ||
+      typeof record.peer !== 'string' || !record.peer || typeof record.from !== 'string' || !record.from ||
+      !(record.task_id === null || (Number.isSafeInteger(record.task_id) && record.task_id > 0)) ||
+      !/^[a-f0-9]{64}$/.test(record.body_sha256) ||
+      !Number.isFinite(Date.parse(record.created_at))) {
+    throw new CliError('NATIVE_CLI_JOURNAL_INVALID', 'Native CLI submission journal does not match this project');
+  }
+  return record;
+}
+
+export function prepareCliSubmission(ctx, input) {
+  const { directory, meshDbRelative } = journalDirectory(ctx, true);
+  const record = {
+    version: 1, submission_id: randomUUID(), root: fs.realpathSync(ctx.root), mesh_db_relative: meshDbRelative,
+    peer: input.peer, from: input.from, task_id: input.taskId || null,
+    body_sha256: createHash('sha256').update(input.body).digest('hex'), created_at: new Date().toISOString()
+  };
+  writeRecord(directory, `submission-${record.submission_id}.json`, record);
+  return record;
+}
+
+export function recordCliSubmissionReceipt(ctx, record, receipt) {
+  if (!Number.isSafeInteger(receipt?.message_id) || receipt.message_id < 1 ||
+      receipt.submission_id !== record.submission_id || typeof receipt.state !== 'string') {
+    throw new CliError('NATIVE_RESPONSE_INVALID', 'Native queue receipt does not match the prepared CLI submission',
+      { uncertain: true });
+  }
+  const { directory } = journalDirectory(ctx, true);
+  const name = `receipt-${record.submission_id}.json`;
+  const existing = optionalRecord(directory, name);
+  if (existing) {
+    if (existing.version !== 1 || existing.submission_id !== record.submission_id ||
+        existing.message_id !== receipt.message_id || typeof existing.state !== 'string') {
+      throw new CliError('NATIVE_CLI_JOURNAL_INVALID', 'Native CLI submission receipt conflicts with the saved receipt');
+    }
+    return;
+  }
+  try {
+    writeRecord(directory, name, {
+      version: 1, submission_id: record.submission_id, message_id: receipt.message_id, state: receipt.state
+    });
+  } catch (error) {
+    if (error.code !== 'NATIVE_CLI_JOURNAL_FAILED' || error.extra?.cause !== 'EEXIST') throw error;
+    const winner = optionalRecord(directory, name);
+    if (!winner) throw error;
+    if (winner.version !== 1 || winner.submission_id !== record.submission_id ||
+        winner.message_id !== receipt.message_id || typeof winner.state !== 'string') {
+      throw new CliError('NATIVE_CLI_JOURNAL_INVALID', 'Native CLI submission receipt conflicts with the saved receipt');
+    }
+  }
+}
+
+export function matchingCliSubmission(ctx, input) {
+  if (!UUID_VALUE.test(input.submissionId)) return null;
+  const journal = journalDirectory(ctx, false);
+  if (!journal) return null;
+  const { directory, meshDbRelative } = journal;
+  const saved = optionalRecord(directory, `submission-${input.submissionId}.json`);
+  if (!saved) return null;
+  const record = validatePrepared(saved, input.submissionId, fs.realpathSync(ctx.root), meshDbRelative);
+  if (record.peer !== input.peer || record.from !== input.from ||
+      record.task_id !== (input.taskId || null) ||
+      record.body_sha256 !== createHash('sha256').update(input.body).digest('hex')) {
+    throw new CliError('NATIVE_SUBMISSION_MISMATCH', 'Retry must keep the prepared CLI peer, sender, task and body');
+  }
+  return record;
+}
+
+export function listCliSubmissions(ctx, { peer = null } = {}) {
+  const journal = journalDirectory(ctx, false);
+  if (!journal) return [];
+  const { directory, meshDbRelative } = journal;
+  const root = fs.realpathSync(ctx.root);
+  const entries = [];
+  for (const name of fs.readdirSync(directory)) {
+    const match = name.match(PREPARED);
+    if (!match) continue;
+    const record = validatePrepared(readRecord(directory, name), match[1], root, meshDbRelative);
+    if (peer && record.peer !== peer) continue;
+    const receiptName = `receipt-${record.submission_id}.json`;
+    let receipt = optionalRecord(directory, receiptName);
+    if (receipt) {
+      if (receipt?.version !== 1 || receipt.submission_id !== record.submission_id ||
+          !Number.isSafeInteger(receipt.message_id) || receipt.message_id < 1 || typeof receipt.state !== 'string') {
+        throw new CliError('NATIVE_CLI_JOURNAL_INVALID', 'Native CLI submission receipt is invalid');
+      }
+      receipt = { message_id: receipt.message_id, submission_id: receipt.submission_id, state: receipt.state };
+    }
+    entries.push({ submission_id: record.submission_id, peer: record.peer, from: record.from,
+      task_id: record.task_id, body_sha256: record.body_sha256, created_at: record.created_at,
+      confirmation: receipt ? 'received' : 'unconfirmed', receipt });
+  }
+  return entries.sort((a, b) => b.created_at.localeCompare(a.created_at) ||
+    b.submission_id.localeCompare(a.submission_id));
+}