@logicseek/hello-cc 1.1.0-rc.7 → 1.1.0-rc.9

package/lib/integrations/native/dsh-acp.mjs

@@ -205,7 +205,7 @@ export function createDshAcpAdapter(options = {}) {
         cwdBinding.assertUnchanged();
         const config = {
           binary: options.binary || 'dsh', args: ['--profile', 'acp'],
-          cwd, env: options.env, timeoutMs: options.timeoutMs,
+          cwd, env: options.env, expectedIdentity: cwdBinding, timeoutMs: options.timeoutMs,
           onNotification, onRequest, onExit, onError: onTransportError
         };
         rpc = options.rpcFactory ? options.rpcFactory(config) : new JsonRpcProcess(config);

package/lib/integrations/native/jsonrpc.mjs

@@ -40,10 +40,10 @@ export class JsonRpcProcess {
 
   async start() {
     if (this.child || this.closed) throw new CliError('NATIVE_TRANSPORT_STATE', 'Transport cannot be started twice');
-    const { binary, args = [], cwd, env } = this.options;
+    const { binary, args = [], cwd, env, expectedIdentity } = this.options;
     assertExecutableAvailable(binary, cwd || process.cwd(), env);
     this.child = spawnPinnedCwdProcess(binary, args, {
-      cwd: cwd || process.cwd(), env, shell: false, stdio: ['pipe', 'pipe', 'pipe']
+      cwd: cwd || process.cwd(), env, expectedIdentity, shell: false, stdio: ['pipe', 'pipe', 'pipe']
     });
     this.child.stdout.setEncoding('utf8');
     this.child.stdout.on('data', (chunk) => this.read(chunk));

package/lib/mcp/scope.mjs

@@ -6,6 +6,9 @@ import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { CliError } from '../shared/errors.mjs';
 import { inspectProcessIdentity } from '../process/identity.mjs';
+import { assertSelectedCwdSnapshot, captureSelectedCwdSnapshot,
+  sameSelectedCwdIdentity } from '../process/selected-cwd-identity.mjs';
+import { nativeOwnerGeneration } from '../runtime/native/store.mjs';
 
 const PATH_KEY = 'HCC_MCP_BOOTSTRAP_PATH';
 const TOKEN_KEY = 'HCC_MCP_BOOTSTRAP_TOKEN';
@@ -20,23 +23,54 @@ function validIdentity(value) {
 function sameIdentity(a, b) {
   return a?.pid === b?.pid && a?.startToken === b?.startToken && a?.commandHash === b?.commandHash;
 }
+function validRootIdentity(value) {
+  const identity = value?.identity;
+  return typeof value?.requested === 'string' && path.isAbsolute(value.requested) &&
+    typeof value.canonical === 'string' && path.isAbsolute(value.canonical) &&
+    typeof identity?.dev === 'string' && /^\d+$/.test(identity.dev) &&
+    typeof identity.ino === 'string' && /^\d+$/.test(identity.ino) &&
+    (identity.birthtimeNs === null ||
+      (typeof identity.birthtimeNs === 'string' && /^\d+$/.test(identity.birthtimeNs)));
+}
+function assertLaunchRoot(root, rootIdentity) {
+  if (!validRootIdentity(rootIdentity)) fail();
+  if (typeof rootIdentity.assertUnchanged === 'function') rootIdentity.assertUnchanged();
+  else assertSelectedCwdSnapshot(rootIdentity);
+  const selected = captureSelectedCwdSnapshot(root);
+  if (!sameSelectedCwdIdentity(rootIdentity, selected)) {
+    throw new CliError('PROJECT_PATH_CHANGED', 'Selected project directory changed');
+  }
+  return { requested: selected.canonical, canonical: selected.canonical,
+    identity: { ...rootIdentity.identity } };
+}
+function assertCapabilityRoot(receipt, root) {
+  if (!validRootIdentity(receipt) || receipt.requested !== root || receipt.canonical !== root) fail();
+  try { assertSelectedCwdSnapshot(receipt); }
+  catch { fail(); }
+}
 
 // Per executor only: callers pass this entry to its thread configuration. No
 // user/global Codex configuration is read or written.
-export function createScopedMcpConfig({ root, dbPath, peer, executorId, ownerIdentity,
+export function createScopedMcpConfig({ root, dbPath, peer, executorId, ownerIdentity, rootIdentity,
   binding = { transport: 'app-server', runtimeSessionId: peer },
   cliPath = fileURLToPath(new URL('../../bin/hcc.mjs', import.meta.url)) }) {
   if (typeof peer !== 'string' || !peer.trim() || peer.length > 256 || /[\r\n\0]/.test(peer) ||
       typeof executorId !== 'string' || !executorId || executorId.length > 256 || !validIdentity(ownerIdentity) ||
-      (binding.transport === 'native' && (binding.runtimeTarget !== executorId || binding.runtimeSessionId !== peer))) fail();
-  const scope = { root: canonical(root), dbPath: canonical(dbPath), peer, executorId,
+      (binding.transport === 'native' && (binding.runtimeTarget !== executorId || binding.runtimeSessionId !== peer ||
+        !nativeOwnerGeneration(executorId)))) fail();
+  const launchRoot = assertLaunchRoot(root, rootIdentity);
+  const scope = { root: launchRoot.canonical, dbPath: canonical(dbPath), peer, executorId,
+    rootIdentity: launchRoot,
     ownerIdentity: { ...ownerIdentity }, binding: { ...binding } };
+  if (typeof rootIdentity.assertUnchanged === 'function') rootIdentity.assertUnchanged();
+  assertCapabilityRoot(scope.rootIdentity, scope.root);
   const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'hcc-mcp-'));
   fs.chmodSync(directory, 0o700);
   const bootstrapPath = path.join(directory, 'scope.json');
   const token = randomBytes(32).toString('base64url');
   try {
-    fs.writeFileSync(bootstrapPath, JSON.stringify({ version: 1, ...scope, tokenHash: digest(token) }),
+    assertCapabilityRoot(scope.rootIdentity, scope.root);
+    fs.writeFileSync(bootstrapPath, JSON.stringify({ version: 2, ...scope, tokenHash: digest(token) }),
       { flag: 'wx', mode: 0o600 });
   } catch (error) { fs.rmSync(directory, { recursive: true, force: true }); throw error; }
   let disposed = false;
@@ -64,13 +98,16 @@ export function loadScopedMcpBootstrap(ctx, peer, env = process.env) {
           (process.platform !== 'win32' && (stat.mode & 0o077)) ||
           (process.getuid && stat.uid !== process.getuid())) fail();
       const value = JSON.parse(fs.readFileSync(fd, 'utf8'));
-      if (value.version !== 1 || typeof value.tokenHash !== 'string' || !/^[a-f0-9]{64}$/.test(value.tokenHash) ||
-          !timingSafeEqual(Buffer.from(value.tokenHash, 'hex'), Buffer.from(digest(token), 'hex')) ||
+      if (value.version !== 2 || typeof value.tokenHash !== 'string' || !/^[a-f0-9]{64}$/.test(value.tokenHash) ||
+          !timingSafeEqual(Buffer.from(value.tokenHash, 'hex'), Buffer.from(digest(token), 'hex'))) fail();
+      assertCapabilityRoot(value.rootIdentity, value.root);
+      if (
           value.root !== canonical(ctx.root) || value.dbPath !== canonical(ctx.dbPath) ||
           value.peer !== peer || !validIdentity(value.ownerIdentity) ||
           typeof value.executorId !== 'string' || !value.executorId || !value.binding ||
           typeof value.binding.transport !== 'string' ||
-          (value.binding.transport === 'native' && (value.binding.runtimeTarget !== value.executorId || value.binding.runtimeSessionId !== peer))) fail();
+          (value.binding.transport === 'native' && (value.binding.runtimeTarget !== value.executorId || value.binding.runtimeSessionId !== peer ||
+            !nativeOwnerGeneration(value.executorId)))) fail();
       return value;
     } catch { fail(); } finally { if (fd !== undefined) fs.closeSync(fd); }
   }
@@ -99,6 +136,11 @@ export function loadScopedMcpBootstrap(ctx, peer, env = process.env) {
     }
   }
   assertValid();
+  const rootIdentity = Object.freeze({ requested: original.rootIdentity.requested,
+    canonical: original.rootIdentity.canonical,
+    identity: Object.freeze({ ...original.rootIdentity.identity }) });
   return { scope: Object.freeze({ root: original.root, dbPath: original.dbPath, peer,
-    executorId: original.executorId }), assertValid, assertOwnership };
+    executorId: original.executorId, rootIdentity,
+    nativeOwnerGeneration: original.binding.transport === 'native' ? nativeOwnerGeneration(original.executorId) : null }),
+    assertValid, assertOwnership };
 }

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;
+  }
+}