@logicseek/hello-cc 1.0.1 → 1.0.2

package/lib/integrations/native/jsonrpc.mjs

@@ -0,0 +1,185 @@
+import { spawn } from 'node:child_process';
+import { CliError } from '../../shared/errors.mjs';
+
+// Each transport owns the child it starts. It never connects to a desktop
+// application's private server or signals a process supplied by the caller.
+export class JsonRpcProcess {
+  constructor(options = {}) {
+    this.options = options;
+    this.pending = new Map();
+    this.nextId = 1;
+    this.buffer = '';
+    this.closed = false;
+    this.child = null;
+    this.closePromise = null;
+    this.lastCloseError = null;
+  }
+
+  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;
+    this.child = spawn(binary, args, { cwd, env, shell: false, stdio: ['pipe', 'pipe', 'pipe'] });
+    this.child.stdout.setEncoding('utf8');
+    this.child.stdout.on('data', (chunk) => this.read(chunk));
+    // Drain stderr without putting credentials or unbounded provider logs into
+    // the shared message bus. Protocol errors are reported through requests.
+    this.child.stderr.resume();
+    this.child.stdin.on('error', (error) => this.fail(error));
+    this.child.on('error', (error) => this.fail(new CliError('NATIVE_SPAWN_FAILED', `Cannot start ${binary}: ${error.message}`)));
+    this.child.once('exit', (code, signal) => {
+      const error = new CliError('NATIVE_PROCESS_EXITED', 'Native provider process exited', { code, signal, uncertain: true });
+      this.fail(error);
+      this.options.onExit?.({ code, signal, expected: this.closed });
+    });
+    await new Promise((resolve, reject) => {
+      this.child.once('spawn', resolve);
+      this.child.once('error', reject);
+    });
+    return this;
+  }
+
+  read(chunk) {
+    this.buffer += chunk;
+    const maxBytes = this.options.maxFrameBytes || 4 * 1024 * 1024;
+    let newline;
+    while ((newline = this.buffer.indexOf('\n')) >= 0) {
+      const line = this.buffer.slice(0, newline).trim();
+      this.buffer = this.buffer.slice(newline + 1);
+      if (!line) continue;
+      if (Buffer.byteLength(line) > maxBytes) return this.protocolFailure('Native protocol frame is too large');
+      let frame;
+      try { frame = JSON.parse(line); } catch { return this.protocolFailure('Invalid JSON from native provider'); }
+      if (!frame || typeof frame !== 'object' || Array.isArray(frame)) return this.protocolFailure('Invalid native protocol frame');
+      if (frame.method) {
+        if (Object.hasOwn(frame, 'id')) void this.handleRequest(frame);
+        else Promise.resolve().then(() => this.options.onNotification?.(frame.method, frame.params || {}))
+          .catch(() => this.protocolFailure('Native notification handler failed'));
+      } else if (Object.hasOwn(frame, 'id')) {
+        const request = this.pending.get(frame.id);
+        if (!request) continue; // Late response to an uncertain, timed-out request.
+        this.pending.delete(frame.id);
+        clearTimeout(request.timer);
+        if (frame.error) request.reject(new CliError('NATIVE_RPC_ERROR', frame.error.message || 'Native provider rejected request', {
+          method: request.method, rpc_code: frame.error.code, data: frame.error.data
+        }));
+        else if (Object.hasOwn(frame, 'result')) request.resolve(frame.result);
+        else request.reject(new CliError('NATIVE_PROTOCOL_ERROR', 'Native response contains neither result nor error'));
+      }
+    }
+    if (Buffer.byteLength(this.buffer) > maxBytes) this.protocolFailure('Native protocol frame is too large');
+  }
+
+  async handleRequest(frame) {
+    try {
+      if (!this.options.onRequest) throw new Error('Unsupported native server request');
+      const result = await this.options.onRequest(frame.method, frame.params || {}, frame.id);
+      this.write({ id: frame.id, result: result ?? null });
+    } catch (error) {
+      if (!this.closed) {
+        try { this.write({ id: frame.id, error: { code: -32601, message: error.message || 'Unsupported server request' } }); } catch {}
+      }
+    }
+  }
+
+  protocolFailure(message) {
+    if (this.closed) return;
+    const error = new CliError('NATIVE_PROTOCOL_ERROR', message, { uncertain: true });
+    this.fail(error);
+    this.reportError(error);
+    // Retain a rejected closePromise for explicit callers without making an
+    // asynchronous protocol failure produce an unhandled rejection.
+    void this.close().catch((closeError) => {
+      this.lastCloseError = closeError;
+      this.reportError(closeError);
+    });
+  }
+
+  reportError(error) {
+    try {
+      const delivery = this.options.onError?.(error);
+      delivery?.catch?.(() => {});
+    } catch {}
+  }
+
+  fail(error) {
+    for (const request of this.pending.values()) {
+      clearTimeout(request.timer);
+      request.reject(error);
+    }
+    this.pending.clear();
+  }
+
+  write(frame) {
+    if (this.closed || !this.child || this.child.exitCode !== null || this.child.signalCode !== null || !this.child.stdin.writable) {
+      throw new CliError('NATIVE_TRANSPORT_CLOSED', 'Native provider connection is closed');
+    }
+    this.child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', ...frame })}\n`);
+  }
+
+  request(method, params = {}, options = {}) {
+    const id = this.nextId++;
+    const timeoutMs = options.timeoutMs ?? this.options.timeoutMs ?? 30000;
+    return new Promise((resolve, reject) => {
+      const timer = timeoutMs > 0 ? setTimeout(() => {
+        this.pending.delete(id);
+        reject(new CliError('NATIVE_REQUEST_TIMEOUT', `Native request timed out: ${method}`, { method, uncertain: true }));
+      }, timeoutMs) : null;
+      this.pending.set(id, { resolve, reject, timer, method });
+      try { this.write({ id, method, params }); }
+      catch (error) { this.pending.delete(id); clearTimeout(timer); reject(error); }
+    });
+  }
+
+  notify(method, params = {}) { this.write({ method, params }); }
+
+  close() {
+    if (this.closePromise) return this.closePromise;
+    this.closed = true;
+    this.fail(new CliError('NATIVE_TRANSPORT_CLOSED', 'Native provider connection closed', { uncertain: true }));
+    const child = this.child;
+    // A failed spawn has no PID and emits close/error, but never exit.
+    if (!child?.pid || child.exitCode !== null || child.signalCode !== null) {
+      this.closePromise = Promise.resolve();
+      return this.closePromise;
+    }
+    this.closePromise = new Promise((resolve, reject) => {
+      let termTimer;
+      let killTimer;
+      const cleanup = () => {
+        clearTimeout(termTimer);
+        clearTimeout(killTimer);
+        child.removeListener('exit', exited);
+        child.removeListener('error', failed);
+      };
+      const exited = () => { cleanup(); resolve(); };
+      const failed = (error) => {
+        cleanup();
+        this.lastCloseError = new CliError('NATIVE_CLOSE_FAILED', 'Cannot confirm native provider process termination', {
+          pid: child.pid, uncertain: true, cause: error.code || error.message
+        });
+        reject(this.lastCloseError);
+      };
+      const signal = (name) => {
+        try {
+          if (!child.kill(name)) {
+            failed(new CliError('NATIVE_SIGNAL_FAILED', `Native process did not accept ${name}`));
+            return false;
+          }
+          return true;
+        } catch (error) { failed(error); return false; }
+      };
+      child.once('exit', exited);
+      child.once('error', failed);
+      termTimer = setTimeout(() => {
+        if (child.exitCode !== null || child.signalCode !== null) return exited();
+        // Sending SIGKILL is not an exit receipt. Continue waiting for exit.
+        killTimer = setTimeout(() => failed(new CliError('NATIVE_EXIT_TIMEOUT',
+          'Native provider did not report exit after SIGKILL')), this.options.closeKillTimeoutMs ?? 2000);
+        signal('SIGKILL');
+      }, this.options.closeGraceMs ?? 2000);
+      try { child.stdin.end(); } catch {}
+      signal('SIGTERM');
+    });
+    return this.closePromise;
+  }
+}

package/lib/integrations/peers/identity.mjs

@@ -28,7 +28,7 @@ export function currentTtyName() {
   return tty && tty !== 'not a tty' ? tty : '';
 }
 
-let ancestorCliInfoCache = undefined;
+const ancestorCliInfoCache = new Map();
 
 function readProcCmdline(pid) {
   if (process.platform !== 'linux' || !pid) return [];
@@ -62,7 +62,27 @@ function readProcParentPid(pid) {
   }
 }
 
+// dsh is a service runtime, not a session-specific executable. Recognize its
+// actual executable or Node entry point, never a shell's arbitrary argument.
+export function argsLookLikeDsh(args) {
+  if (!Array.isArray(args) || !args.length) return false;
+  const executable = path.basename(String(args[0] || '')).toLowerCase();
+  if (executable === 'dsh') return true;
+  if (!['node', 'nodejs'].includes(executable)) return false;
+  let index = 1;
+  const valueFlags = new Set(['-r', '--require', '--import', '--loader', '--experimental-loader', '--conditions']);
+  while (index < args.length && String(args[index]).startsWith('-')) {
+    const flag = String(args[index]);
+    if (flag === '--') { index += 1; break; }
+    if (/^-[ep]/.test(flag) || ['--eval', '--print'].some((name) => flag === name || flag.startsWith(`${name}=`))) return false;
+    index += valueFlags.has(flag) ? 2 : 1;
+  }
+  const entry = String(args[index] || '').replaceAll('\\', '/');
+  return path.basename(entry) === 'dsh' || entry.endsWith('/dsh/lib/bin.js');
+}
+
 function argsLookLikeCli(args, kind) {
+  if (kind === 'dsh') return argsLookLikeDsh(args);
   return args.some((arg) => {
     const text = String(arg || '').toLowerCase();
     const base = path.basename(text);
@@ -73,6 +93,7 @@ function argsLookLikeCli(args, kind) {
 }
 
 function detectCliKindFromProcess(args, env) {
+  if (argsLookLikeDsh(args)) return 'dsh';
   if (env.CLAUDE_CODE_SESSION_ID || env.CLAUDECODE === '1' || argsLookLikeCli(args, 'claude')) return 'claude';
   if (
     env.CODEX_SESSION_ID ||
@@ -101,7 +122,7 @@ export function findLinuxAncestorCliInfo(startPid, options = {}) {
     const args = Array.isArray(row.args) ? row.args : [];
     const env = row.env && typeof row.env === 'object' && !Array.isArray(row.env) ? row.env : {};
     const kind = detectCliKindFromProcess(args, env);
-    if (kind) return { pid, kind, args, env };
+    if (kind && (!options.kind || options.kind === kind)) return { pid, kind, args, env };
     pid = Number(row.parent);
   }
   return null;
@@ -136,23 +157,28 @@ export function findMacAncestorCliInfo(startPid, options = {}) {
     seen.add(pid);
     const parsed = parseMacAncestorLine(inspect(pid));
     if (!parsed) return null;
-    const kind = detectCliKindFromProcess([parsed.command], {});
+    // ps provides a rendered command, not lossless argv. Only tokenize enough
+    // to recognize the dsh executable/Node script; resume parsing remains off.
+    const commandArgs = parsed.command.match(/"(?:\\.|[^"\\])*"|'[^']*'|\S+/g)?.map((arg) =>
+      /^("|')/.test(arg) ? arg.slice(1, -1) : arg) || [];
+    const kind = argsLookLikeDsh(commandArgs) ? 'dsh' : detectCliKindFromProcess([parsed.command], {});
     // `ps command` is sufficient for provider-kind detection but is not a
     // lossless argv encoding. Do not feed it to resume-ID parsing.
-    if (kind) return { pid, kind, args: [], env: {}, command: parsed.command };
+    if (kind && (!options.kind || options.kind === kind)) return { pid, kind, args: [], env: {}, command: parsed.command };
     pid = parsed.ppid;
   }
   return null;
 }
 
-export function readAncestorCliInfo() {
-  if (ancestorCliInfoCache !== undefined) return ancestorCliInfoCache;
-  ancestorCliInfoCache = process.platform === 'linux'
-    ? findLinuxAncestorCliInfo(process.ppid)
+export function readAncestorCliInfo(kindHint = null) {
+  if (ancestorCliInfoCache.has(kindHint)) return ancestorCliInfoCache.get(kindHint);
+  const info = process.platform === 'linux'
+    ? findLinuxAncestorCliInfo(process.ppid, { kind: kindHint })
     : process.platform === 'darwin'
-      ? findMacAncestorCliInfo(process.ppid)
+      ? findMacAncestorCliInfo(process.ppid, { kind: kindHint })
       : null;
-  return ancestorCliInfoCache;
+  ancestorCliInfoCache.set(kindHint, info);
+  return info;
 }
 
 export function resumeIdFromArgs(kind, args) {

package/lib/integrations/peers/processes.mjs

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { resumeIdFromArgs } from './identity.mjs';
+import { argsLookLikeDsh, resumeIdFromArgs } from './identity.mjs';
 
 function readProcCmdline(pid) {
   if (process.platform !== 'linux' || !pid) return [];
@@ -49,6 +49,7 @@ function readProcChildren(pid) {
 }
 
 function argsLookLikeCli(args, kind) {
+  if (kind === 'dsh') return argsLookLikeDsh(args);
   return args.some((arg) => {
     const text = String(arg || '').toLowerCase();
     const base = path.basename(text);
@@ -59,6 +60,9 @@ function argsLookLikeCli(args, kind) {
 }
 
 function detectKind(args, env, kindHint = null) {
+  if (argsLookLikeDsh(args)) return 'dsh';
+  // No service-level Claude/Codex environment can identify a dsh session.
+  if (kindHint === 'dsh') return null;
   if (kindHint && argsLookLikeCli(args, kindHint)) return kindHint;
   if (env.CLAUDE_CODE_SESSION_ID || env.CLAUDECODE === '1' || argsLookLikeCli(args, 'claude')) return 'claude';
   if (
@@ -78,7 +82,13 @@ function sessionFromEnv(kind, env) {
 }
 
 export function inspectProviderProcess(pid, kindHint = null, opts = {}) {
-  if (process.platform !== 'linux' || !pid) return null;
+  if ((process.platform !== 'linux' && typeof opts.read !== 'function') || !pid) return null;
+  const read = typeof opts.read === 'function' ? opts.read : (processPid) => ({
+    args: readProcCmdline(processPid),
+    env: readProcEnv(processPid),
+    parent: readProcParentPid(processPid),
+    children: readProcChildren(processPid)
+  });
   const maxDepth = Number.isFinite(opts.maxDepth) ? opts.maxDepth : 8;
   const queue = [{ pid: Number(pid), depth: 0 }];
   const seen = new Set();
@@ -89,10 +99,12 @@ export function inspectProviderProcess(pid, kindHint = null, opts = {}) {
     const depth = current?.depth || 0;
     if (!currentPid || currentPid <= 1 || depth > maxDepth || seen.has(currentPid)) continue;
     seen.add(currentPid);
-    const args = readProcCmdline(currentPid);
-    const env = readProcEnv(currentPid);
+    const row = read(currentPid) || {};
+    const args = Array.isArray(row.args) ? row.args : [];
+    const env = row.env || {};
     const kind = detectKind(args, env, kindHint);
     if (kind) {
+      if (kind === 'dsh') return { pid: currentPid, kind, provider_session: null, source: 'process.argv.dsh' };
       const envSession = sessionFromEnv(kind, env);
       if (envSession) {
         return {
@@ -112,7 +124,7 @@ export function inspectProviderProcess(pid, kindHint = null, opts = {}) {
         };
       }
     }
-    for (const childPid of readProcChildren(currentPid)) {
+    for (const childPid of row.children || []) {
       queue.push({ pid: childPid, depth: depth + 1 });
     }
   }
@@ -122,10 +134,12 @@ export function inspectProviderProcess(pid, kindHint = null, opts = {}) {
 
   for (let depth = 0; currentPid && currentPid > 1 && depth <= maxDepth && !seen.has(currentPid); depth += 1) {
     seen.add(currentPid);
-    const args = readProcCmdline(currentPid);
-    const env = readProcEnv(currentPid);
+    const row = read(currentPid) || {};
+    const args = Array.isArray(row.args) ? row.args : [];
+    const env = row.env || {};
     const kind = detectKind(args, env, kindHint);
     if (kind) {
+      if (kind === 'dsh') return { pid: currentPid, kind, provider_session: null, source: 'process.argv.dsh' };
       const envSession = sessionFromEnv(kind, env);
       if (envSession) {
         return {
@@ -145,7 +159,7 @@ export function inspectProviderProcess(pid, kindHint = null, opts = {}) {
         };
       }
     }
-    currentPid = readProcParentPid(currentPid);
+    currentPid = Number(row.parent);
   }
   return null;
 }

package/lib/integrations/providers.mjs

@@ -13,9 +13,10 @@ function shellCommand(args) {
 
 export function inferPeerKind(id, explicitKind, firstCommand) {
   if (explicitKind) return explicitKind;
-  if (['codex', 'claude'].includes(firstCommand)) return firstCommand;
+  if (['codex', 'claude', 'dsh'].includes(firstCommand)) return firstCommand;
   if (String(id).startsWith('codex')) return 'codex';
   if (String(id).startsWith('claude')) return 'claude';
+  if (String(id).startsWith('dsh')) return 'dsh';
   return 'shell';
 }
 
@@ -26,6 +27,9 @@ export function hasResumeOpts(opts) {
 export function defaultSessionCommand(kind) {
   if (kind === 'codex') return 'codex';
   if (kind === 'claude') return 'claude';
+  if (kind === 'dsh') {
+    throw new CliError('DSH_TUI_UNSUPPORTED', 'dsh has no bundled interactive terminal profile. Use hcc dsh web to launch its Web UI and connect sessions through hooks.');
+  }
   return process.env.SHELL || 'bash';
 }
 
@@ -49,8 +53,8 @@ export function buildPeerCommand(id, kind, opts, cmdArgs) {
   }
   if (kind === 'codex') return buildCodexCommand(id, opts);
   if (kind === 'claude') return buildClaudeCommand(id, opts);
-  if (hasResumeOpts(opts)) throw new CliError('BAD_ARGS', `Resume options are only supported for codex and claude peers`);
   const command = defaultSessionCommand(kind);
+  if (hasResumeOpts(opts)) throw new CliError('BAD_ARGS', `Resume options are only supported for codex and claude peers`);
   return {
     command,
     binding: {

package/lib/mcp/scope.mjs

@@ -0,0 +1,104 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { CliError } from '../shared/errors.mjs';
+import { inspectProcessIdentity } from '../process/identity.mjs';
+
+const PATH_KEY = 'HCC_MCP_BOOTSTRAP_PATH';
+const TOKEN_KEY = 'HCC_MCP_BOOTSTRAP_TOKEN';
+const fail = () => { throw new CliError('MCP_SCOPE_INVALID', 'The scoped MCP capability is missing, revoked, or no longer owns this peer'); };
+const digest = value => createHash('sha256').update(value).digest('hex');
+const canonical = value => fs.realpathSync(path.resolve(value));
+function validIdentity(value) {
+  return value && Number.isSafeInteger(value.pid) && value.pid > 0 &&
+    typeof value.startToken === 'string' && value.startToken.length > 0 && value.startToken.length < 512 &&
+    typeof value.commandHash === 'string' && /^[a-f0-9]{64}$/.test(value.commandHash);
+}
+function sameIdentity(a, b) {
+  return a?.pid === b?.pid && a?.startToken === b?.startToken && a?.commandHash === b?.commandHash;
+}
+
+// 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,
+  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,
+    ownerIdentity: { ...ownerIdentity }, binding: { ...binding } };
+  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) }),
+      { flag: 'wx', mode: 0o600 });
+  } catch (error) { fs.rmSync(directory, { recursive: true, force: true }); throw error; }
+  let disposed = false;
+  return {
+    config: { command: process.execPath,
+      args: [canonical(cliPath), '--root', scope.root, '--db', scope.dbPath, 'mcp', 'serve', '--peer', peer],
+      env: { [PATH_KEY]: bootstrapPath, [TOKEN_KEY]: token } },
+    dispose() { if (!disposed) { disposed = true; fs.rmSync(directory, { recursive: true, force: true }); } }
+  };
+}
+
+export function loadScopedMcpBootstrap(ctx, peer, env = process.env) {
+  const bootstrapPath = env[PATH_KEY], token = env[TOKEN_KEY];
+  if (typeof bootstrapPath !== 'string' || !path.isAbsolute(bootstrapPath) ||
+      typeof token !== 'string' || token.length < 32 || token.length > 256) fail();
+  function read() {
+    let fd;
+    try {
+      const parent = fs.lstatSync(path.dirname(bootstrapPath));
+      if (!parent.isDirectory() || parent.isSymbolicLink() ||
+          (process.platform !== 'win32' && (parent.mode & 0o077))) fail();
+      fd = fs.openSync(bootstrapPath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+      const stat = fs.fstatSync(fd);
+      if (!stat.isFile() || stat.nlink !== 1 || stat.size > 16384 ||
+          (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')) ||
+          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();
+      return value;
+    } catch { fail(); } finally { if (fd !== undefined) fs.closeSync(fd); }
+  }
+  const original = read(), originalHash = digest(JSON.stringify(original));
+  function assertValid() {
+    const value = read();
+    if (digest(JSON.stringify(value)) !== originalHash) fail();
+    const observation = inspectProcessIdentity(value.ownerIdentity.pid);
+    if (observation.state !== 'live' || !sameIdentity(value.ownerIdentity, observation.identity)) fail();
+  }
+  function assertOwnership(db) {
+    assertValid();
+    const row = db.prepare('SELECT * FROM peers WHERE id = ?').get(peer);
+    if (!row || ['exited', 'detached'].includes(row.status) || !sameIdentity(original.ownerIdentity,
+      { pid: Number(row.pid), startToken: row.pid_start_token, commandHash: row.pid_command_hash })) fail();
+    const binding = db.prepare('SELECT * FROM peer_bindings WHERE peer = ?').get(peer);
+    if (!binding || binding.transport !== original.binding.transport ||
+        (original.binding.runtimeSessionId !== undefined && binding.runtime_session_id !== original.binding.runtimeSessionId) ||
+        (original.binding.runtimeTarget !== undefined && binding.runtime_target !== original.binding.runtimeTarget)) fail();
+    if (original.binding.transport === 'app-server') {
+      const receipt = db.prepare(`SELECT payload FROM events WHERE type = 'codex.executor.started'
+        AND actor = ? ORDER BY id DESC LIMIT 1`).get(peer);
+      let executor;
+      try { executor = JSON.parse(receipt?.payload || '{}').executor_id; } catch { fail(); }
+      if (executor !== original.executorId) fail();
+    }
+  }
+  assertValid();
+  return { scope: Object.freeze({ root: original.root, dbPath: original.dbPath, peer,
+    executorId: original.executorId }), assertValid, assertOwnership };
+}

package/lib/mcp/stdio.mjs

@@ -0,0 +1,80 @@
+import process from 'node:process';
+import { once } from 'node:events';
+import { StringDecoder } from 'node:string_decoder';
+
+// Official JSONL stdio transport; batch envelopes are not part of these MCP
+// versions. Stdout contains protocol messages only, including parse errors.
+export const MCP_PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+const object = value => Boolean(value && typeof value === 'object' && !Array.isArray(value));
+const own = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+const validId = value => (typeof value === 'string' && value.length <= 256) || Number.isSafeInteger(value);
+
+export async function serveMcpStdio({ tools, input = process.stdin, output = process.stdout,
+  serverVersion = '1.0.1', maxLineBytes = 1024 * 1024 }) {
+  let initialized = false, ready = false;
+  const decoder = new StringDecoder('utf8');
+  async function send(value) {
+    if (!output.write(JSON.stringify(value) + '\n')) await once(output, 'drain');
+  }
+  const error = (id, code, message) => send({ jsonrpc: '2.0', id, error: { code, message } });
+  async function handle(line) {
+    let request;
+    try { request = JSON.parse(line); } catch { return error(null, -32700, 'Parse error'); }
+    if (!object(request) || request.jsonrpc !== '2.0' || typeof request.method !== 'string' ||
+        (own(request, 'id') && !validId(request.id)) ||
+        (request.params !== undefined && !object(request.params))) {
+      return error(validId(request?.id) ? request.id : null, -32600, 'Invalid Request');
+    }
+    const { method, params = {}, id } = request;
+    if (!own(request, 'id')) {
+      if (method === 'notifications/initialized' && initialized) ready = true;
+      return;
+    }
+    if (method === 'ping') return send({ jsonrpc: '2.0', id, result: {} });
+    if (method === 'initialize') {
+      if (initialized) return error(id, -32600, 'Already initialized');
+      if (typeof params.protocolVersion !== 'string' || !object(params.capabilities) ||
+          !object(params.clientInfo) || typeof params.clientInfo.name !== 'string' ||
+          typeof params.clientInfo.version !== 'string') return error(id, -32602, 'Invalid initialize parameters');
+      initialized = true;
+      return send({ jsonrpc: '2.0', id, result: {
+        protocolVersion: MCP_PROTOCOL_VERSIONS.includes(params.protocolVersion) ? params.protocolVersion : MCP_PROTOCOL_VERSIONS[0],
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: 'hello-cc-scoped', version: serverVersion },
+        instructions: 'Tools are restricted to the project and peer supplied by this executor. Task claiming and handoff do not complete tasks.'
+      } });
+    }
+    if (!ready) return error(id, -32002, 'Send initialize and notifications/initialized first');
+    if (method === 'tools/list') {
+      if (params.cursor !== undefined) return error(id, -32602, 'This server does not paginate tools');
+      return send({ jsonrpc: '2.0', id, result: { tools: tools.list() } });
+    }
+    if (method === 'tools/call') {
+      if (typeof params.name !== 'string' || !tools.has(params.name)) return error(id, -32602, 'Unknown tool');
+      if (params.arguments !== undefined && !object(params.arguments)) return error(id, -32602, 'Tool arguments must be an object');
+      return send({ jsonrpc: '2.0', id, result: await tools.call(params.name, params.arguments || {}) });
+    }
+    return error(id, -32601, 'Method not found');
+  }
+  let pending = '', dropping = false;
+  for await (const bytes of input) {
+    const text = typeof bytes === 'string' ? bytes : decoder.write(bytes);
+    let offset = 0;
+    for (;;) {
+      const newline = text.indexOf('\n', offset);
+      const piece = text.slice(offset, newline < 0 ? undefined : newline);
+      if (!dropping) {
+        pending += piece;
+        if (Buffer.byteLength(pending) > maxLineBytes) {
+          pending = ''; dropping = true;
+          await error(null, -32600, 'Request line is too large');
+        }
+      }
+      if (newline < 0) break;
+      if (!dropping && pending.trim()) await handle(pending);
+      pending = ''; dropping = false; offset = newline + 1;
+    }
+  }
+  pending += decoder.end();
+  if (!dropping && pending.trim()) await handle(pending);
+}