@logicseek/hello-cc 1.0.0 → 1.0.2-dsh.3

package/lib/cli/commands/hook.mjs

@@ -1,5 +1,9 @@
 // Hook command extracted from bin/hcc.mjs.
-// This is the provider hook entry point called by Claude/Codex hooks.
+// This is the provider hook entry point called by Claude/Codex/dsh hooks.
+
+import { parseOpts, validateOpts } from '../../cli-args.mjs';
+import { tx } from '../../db/schema.mjs';
+import { resolveProjectDatabase } from '../../runtime/project-path.mjs';
 
 export function createHookCommand(deps) {
   const {
@@ -18,46 +22,86 @@ export function createHookCommand(deps) {
   } = deps;
 
 async function cmdHook(ctx, args) {
-  let hookType = args[0] || 'unknown';
+  const opts = parseOpts(args);
+  let hookType = opts._.shift() || 'unknown';
+  validateOpts('hook', opts, ['provider']);
+  if (opts.provider !== undefined && !['claude', 'codex', 'dsh'].includes(opts.provider)) {
+    throw new CliError('BAD_ARGS', 'hook: --provider must be claude, codex, or dsh');
+  }
+  const kind = opts.provider || autoPeerKind('other');
+  const isDsh = kind === 'dsh';
+  const nativeOwner = process.env.HCC_NATIVE_OWNER || null;
+  if (nativeOwner && (!process.env.HCC_PEER || !process.env.HCC_ROOT || !process.env.HCC_DB)) {
+    throw new CliError('NATIVE_HOOK_OWNERSHIP_MISMATCH', 'Native hook needs an explicit worker peer, root, and database');
+  }
 
   // Read stdin with a short timeout (hooks must complete quickly)
   const raw = await new Promise((resolve) => {
     let buf = '';
-    const timer = setTimeout(() => resolve(buf), 2000);
+    const finish = () => {
+      clearTimeout(timer);
+      process.stdin.removeListener('data', onData);
+      process.stdin.removeListener('end', finish);
+      process.stdin.removeListener('error', finish);
+      process.stdin.pause();
+      resolve(buf);
+    };
+    const onData = (c) => { buf += c; };
+    const timer = setTimeout(finish, 2000);
     process.stdin.setEncoding('utf8');
-    process.stdin.on('data', (c) => { buf += c; });
-    process.stdin.on('end', () => { clearTimeout(timer); resolve(buf); });
-    process.stdin.on('error', () => { clearTimeout(timer); resolve(buf); });
+    process.stdin.on('data', onData);
+    process.stdin.on('end', finish);
+    process.stdin.on('error', finish);
   });
 
   let payload = {};
   try { payload = JSON.parse(raw); } catch {}
+  if (isDsh && (!payload || typeof payload !== 'object' || Array.isArray(payload))) {
+    throw new CliError('BAD_HOOK_PAYLOAD', 'dsh hook requires a JSON object with session_id and cwd');
+  }
+  // Keep ordinary hooks tolerant of malformed/empty input as before.
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) payload = {};
   hookType = payload.hook_event_name || payload.hookEventName || hookType;
+  if (isDsh && typeof hookType !== 'string') {
+    throw new CliError('BAD_HOOK_PAYLOAD', 'dsh hook requires a valid hook event');
+  }
   const hookEventName = formatHookEventName(hookType);
   const hookKey = hookEventName.replace(/[^a-z]/gi, '').toLowerCase();
+  if (isDsh && !['sessionstart', 'userpromptsubmit', 'pretooluse', 'posttooluse', 'stop'].includes(hookKey)) {
+    throw new CliError('BAD_HOOK_PAYLOAD', 'Unsupported dsh hook event');
+  }
 
-  // Extract session identity (Claude Code sets these in its hook JSON)
-  const kind = autoPeerKind('other');
-  const providerSession = autoPeerProviderSession(kind);
-  const sessionId  = payload.session_id || payload.sessionId || payload.conversation_id || payload.conversationId ||
-    providerSession.sessionId || '';
-  const hookCwd    = payload.cwd         || payload.workingDirectory || process.cwd();
+  // A dsh service can host many sessions and workspaces. Only its per-hook
+  // payload identifies the conversation; service environment belongs to none.
+  const providerSession = isDsh ? {} : autoPeerProviderSession(kind);
+  const sessionId = isDsh
+    ? payload.session_id
+    : payload.session_id || payload.sessionId || payload.conversation_id || payload.conversationId || providerSession.sessionId || '';
+  const hookCwd = isDsh ? payload.cwd : payload.cwd || payload.workingDirectory || process.cwd();
+  if (isDsh) validateDshHookIdentity(sessionId, hookCwd);
 
   // Hooks auto-join the exact current project path, creating its mesh.db on
-  // first use. Cross-path sharing is explicit via HCC_ROOT/HCC_DB.
-  const hccRoot = process.env.HCC_ROOT
+  // first use. Ordinary hooks allow explicit cross-path sharing via HCC_ROOT.
+  const hccRoot = (nativeOwner || !isDsh) && process.env.HCC_ROOT
     ? path.resolve(process.env.HCC_ROOT)
     : path.resolve(hookCwd);
 
+  const dshProject = isDsh && !nativeOwner ? resolveProjectDatabase({ root: hccRoot, createStateDir: false }) : null;
+  const nativeProject = nativeOwner ? resolveProjectDatabase({ root: hccRoot,
+    db: process.env.HCC_DB, createStateDir: false }) : null;
+  if (nativeProject && !fs.existsSync(nativeProject.db)) {
+    throw new CliError('NATIVE_HOOK_OWNERSHIP_MISMATCH', 'Native hook database must already be owned by its runtime');
+  }
   const hookCtx = {
     ...ctx,
-    root: hccRoot,
-    dbPath: path.join(hccRoot, '.hello-cc', 'mesh.db')
+    root: nativeProject?.root || dshProject?.root || hccRoot,
+    dbPath: nativeProject?.db || dshProject?.db || path.join(hccRoot, '.hello-cc', 'mesh.db')
   };
-  registerProjectActivity(hookCtx);
+  if (!nativeOwner) registerProjectActivity(hookCtx);
 
-  // Derive peer ID: HCC_PEER > resume ID from parent cmdline > session ID > terminal
-  let peerId = process.env.HCC_PEER;
+  // dsh uses only its true session ID. Ordinary hooks retain environment,
+  // resume, session, and terminal identity precedence.
+  let peerId = isDsh && !nativeOwner ? providerSessionPeerId(kind, sessionId) : process.env.HCC_PEER;
   let resumeId = null;
   if (!peerId) {
     resumeId = providerSession.resumeId || readParentResumeId(kind);
@@ -71,67 +115,99 @@ async function cmdHook(ctx, args) {
       : `${kind}-${shortHash(`${hookCtx.root}:${autoPeerBasis(kind)}`)}`;
   }
 
-  const db = connect(hookCtx);
+  // Hook delivery must not migrate another workspace's registered database.
+  const db = isDsh || nativeOwner ? connect(hookCtx, { migrateRegistered: false }) : connect(hookCtx);
   try {
+    if (nativeOwner) {
+      // Native delivery owns context injection and completion receipts. Hooks
+      // only renew its verified owner, never turn a native binding into a
+      // terminal binding or consume the same inbox through a second path.
+      tx(db, () => {
+        const binding = db.prepare(`
+          SELECT b.*, p.kind AS peer_kind FROM peer_bindings b
+          JOIN peers p ON p.id = b.peer WHERE b.peer = ?
+        `).get(peerId);
+        if (!binding || binding.transport !== 'native' || binding.runtime_target !== nativeOwner ||
+            binding.peer_kind !== binding.provider || (opts.provider && binding.provider !== kind)) {
+          throw new CliError('NATIVE_HOOK_OWNERSHIP_MISMATCH', 'Native hook does not match its runtime-owned peer binding');
+        }
+        const observedAt = now();
+        db.prepare('UPDATE peers SET last_seen_at = ? WHERE id = ?').run(observedAt, peerId);
+        const renewed = renewOwnedLocks(db, { owner: peerId, nowSec: observedAt,
+          ttlCap: 3600, includeExpired: true });
+        if (renewed > 0) addEvent(db, 'lock.renewed_by_hook', peerId, null, { renewed, source: 'native-hook' });
+      });
+      process.exitCode = 0;
+      return;
+    }
     const status = hookKey === 'stop' ? 'idle' : 'working';
-    const providerAncestor = readAncestorCliInfo();
+    const providerAncestor = readAncestorCliInfo(isDsh ? 'dsh' : undefined);
     const providerPid = providerAncestor?.kind === kind ? Number(providerAncestor.pid) : null;
     const providerIdentity = providerPid ? liveProcessIdentity(providerPid) : null;
-    const existing = db.prepare('SELECT id FROM peers WHERE id = ?').get(peerId);
-    if (!existing) {
-      upsertPeer(db, {
-        id: peerId, kind, role: 'peer',
-        worktree: hookCwd,
-        branch: detectBranch(hookCwd),
-        pid: providerIdentity?.pid || null,
-        processIdentity: providerIdentity,
-        status,
-        capabilities: `hook-${hookKey}`
-      });
-    } else {
-      refreshHookOwnerIdentity(db, {
-        peerId,
-        status,
-        observedAt: now(),
-        processIdentity: providerIdentity
-      });
-    }
-    const hookBinding = {
-      peer: peerId,
-      provider: kind,
-      ...providerSessionParts(resumeId || sessionId),
-      resume_mode: resumeId ? 'resume' : (sessionId ? 'detected' : 'unknown'),
-      resume_arg: resumeId || null,
-      command: null,
-      transport: 'hook',
-      runtime_session_id: peerId
-    };
-    const canonical = upsertCanonicalPeerBinding(db, hookBinding, true);
-    if (canonical.peer !== peerId) {
-      const previousPeer = peerId;
-      peerId = canonical.peer;
-      refreshHookOwnerIdentity(db, {
-        peerId,
-        status,
-        observedAt: now(),
-        processIdentity: providerIdentity
-      });
-      addEvent(db, 'provider.session.merged', peerId, null, auditPayload({
+    const registerHookIdentity = () => {
+      if (isDsh) assertDshHookBinding(db, peerId, sessionId);
+      const existing = db.prepare('SELECT id FROM peers WHERE id = ?').get(peerId);
+      if (!existing) {
+        upsertPeer(db, {
+          id: peerId, kind, role: 'peer',
+          worktree: hookCwd,
+          branch: detectBranch(hookCwd),
+          pid: providerIdentity?.pid || null,
+          processIdentity: providerIdentity,
+          status,
+          capabilities: `hook-${hookKey}`
+        });
+      } else {
+        refreshHookOwnerIdentity(db, {
+          peerId,
+          status,
+          observedAt: now(),
+          processIdentity: providerIdentity
+        });
+      }
+      const hookBinding = {
+        peer: peerId,
+        provider: kind,
+        ...(isDsh
+          ? { provider_session_id: sessionId, provider_session_name: null }
+          : providerSessionParts(resumeId || sessionId)),
+        resume_mode: resumeId ? 'resume' : (sessionId ? 'detected' : 'unknown'),
+        resume_arg: resumeId || null,
+        command: null,
+        transport: 'hook',
+        runtime_session_id: peerId
+      };
+      const canonical = upsertCanonicalPeerBinding(db, hookBinding, true);
+      if (canonical.peer !== peerId) {
+        const previousPeer = peerId;
+        peerId = canonical.peer;
+        refreshHookOwnerIdentity(db, {
+          peerId,
+          status,
+          observedAt: now(),
+          processIdentity: providerIdentity
+        });
+        addEvent(db, 'provider.session.merged', peerId, null, auditPayload({
+          actor: peerId,
+          target: peerId,
+          source: 'hook',
+          from_peer: previousPeer,
+          provider: kind,
+          session_id: sessionId || resumeId || null
+        }));
+      }
+      addEvent(db, `hook.${hookKey}`, peerId, null, auditPayload({
         actor: peerId,
         target: peerId,
         source: 'hook',
-        from_peer: previousPeer,
-        provider: kind,
-        session_id: sessionId || resumeId || null
+        session_id: sessionId,
+        cwd: hookCwd
       }));
-    }
-    addEvent(db, `hook.${hookKey}`, peerId, null, auditPayload({
-      actor: peerId,
-      target: peerId,
-      source: 'hook',
-      session_id: sessionId,
-      cwd: hookCwd
-    }));
+    };
+    // Keep the dsh conflict check and identity/binding writes atomic, so a
+    // concurrent service/session registration cannot change the inspected row.
+    if (isDsh) tx(db, registerHookIdentity);
+    else registerHookIdentity();
     // hb-06: an active hook is proof the peer is working. During clock grace,
     // renew retained locks even when the wall-clock jump made them look expired.
     const hookNow = now();
@@ -152,46 +228,118 @@ async function cmdHook(ctx, args) {
     if (hookLockRenewals > 0) {
       addEvent(db, 'lock.renewed_by_hook', peerId, null, { renewed: hookLockRenewals });
     }
-    try {
-      reconcileRunningPeerBindings(db, hookCtx, {
-        inspectProcess: inspectProviderProcess,
-        latestProviderSessionForPeer: (peer) => latestHookProviderSession(db, peer),
-        addEvent,
-        now
-      });
-    } catch {}
+    if (!isDsh) {
+      try {
+        reconcileRunningPeerBindings(db, hookCtx, {
+          inspectProcess: inspectProviderProcess,
+          latestProviderSessionForPeer: (peer) => latestHookProviderSession(db, peer),
+          addEvent,
+          now
+        });
+      } catch {}
+    }
 
     if (['sessionstart', 'userpromptsubmit'].includes(hookKey)) {
       const snapshot = buildHookCoordinationContext(db, hookCtx, peerId);
-      ackMessages(db, peerId, snapshot.messages);
-      process.stdout.write(JSON.stringify({
+      await writeHookOutput({
         hookSpecificOutput: {
           hookEventName,
           additionalContext: snapshot.text
         }
-      }) + '\n');
-    } else if (['posttooluse', 'stop'].includes(hookKey)) {
+      });
+      ackMessages(db, peerId, snapshot.messages);
+    } else if (hookKey === 'posttooluse') {
       const snapshot = buildHookCoordinationContext(db, hookCtx, peerId);
       if (snapshot.messages.length > 0) {
-        ackMessages(db, peerId, snapshot.messages);
-        process.stdout.write(JSON.stringify({
+        await writeHookOutput({
           hookSpecificOutput: {
             hookEventName,
             additionalContext: snapshot.text
           }
-        }) + '\n');
+        });
+        ackMessages(db, peerId, snapshot.messages);
+      }
+    } else if (hookKey === 'stop' && payload.stop_hook_active !== true) {
+      // A blocking Stop hook causes another model turn. Do not block that
+      // continuation again; newly arrived messages stay unread for the next
+      // SessionStart, UserPromptSubmit, PostToolUse, or independent Stop.
+      const snapshot = buildHookCoordinationContext(db, hookCtx, peerId);
+      if (snapshot.messages.length > 0) {
+        await writeHookOutput({
+          decision: 'block',
+          reason: snapshot.text
+        });
+        ackMessages(db, peerId, snapshot.messages);
       }
     }
   } finally {
     try { db.close(); } catch {}
   }
-  process.exit(0);
+  // Let Node exit after the hook output has flushed instead of truncating a
+  // pipe with process.exit(). A successful write is not provider acceptance.
+  process.exitCode = 0;
 }
 
-// ─── hcc install-hooks ───────────────────────────────────────────────────────
+function writeHookOutput(output) {
+  return new Promise((resolve, reject) => {
+    const stdout = process.stdout;
+    const onError = (error) => reject(error);
+    stdout.once('error', onError);
+    try {
+      stdout.write(JSON.stringify(output) + '\n', (error) => {
+        if (error) {
+          // Writable emits its error after invoking the callback. Keep the
+          // once listener until that event so a failed pipe is handled.
+          reject(error);
+        } else {
+          stdout.removeListener('error', onError);
+          resolve();
+        }
+      });
+    } catch (error) {
+      stdout.removeListener('error', onError);
+      reject(error);
+    }
+  });
+}
 
+function validateDshHookIdentity(sessionId, cwd) {
+  if (typeof sessionId !== 'string' || !sessionId || sessionId.length > 1024 ||
+      sessionId.trim() !== sessionId || /[\u0000-\u001f\u007f]/.test(sessionId)) {
+    throw new CliError('BAD_HOOK_PAYLOAD', 'dsh hook requires a nonempty string session_id');
+  }
+  if (typeof cwd !== 'string' || !cwd || /[\u0000-\u001f\u007f]/.test(cwd) || !path.isAbsolute(cwd)) {
+    throw new CliError('BAD_HOOK_PAYLOAD', 'dsh hook requires an absolute cwd directory');
+  }
+  let isDirectory = false;
+  try { isDirectory = fs.statSync(cwd).isDirectory(); } catch {}
+  if (!isDirectory) throw new CliError('BAD_HOOK_PAYLOAD', 'dsh hook cwd must be an existing directory');
+}
 
-  return { cmdHook };
+function assertDshHookBinding(db, peerId, sessionId) {
+  const conflict = (reason, boundPeer = peerId) => {
+    throw new CliError('DSH_PEER_BINDING_CONFLICT',
+      `dsh hook session ${sessionId} conflicts with existing peer binding ${boundPeer}`, {
+        peer: peerId, bound_peer: boundPeer, session_id: sessionId, reason
+      });
+  };
+  const peer = db.prepare('SELECT kind FROM peers WHERE id = ?').get(peerId);
+  if (peer && peer.kind !== 'dsh') conflict('peer_provider_mismatch');
+  const binding = db.prepare('SELECT * FROM peer_bindings WHERE peer = ?').get(peerId);
+  if (binding) {
+    if (binding.provider !== 'dsh') conflict('binding_provider_mismatch');
+    if (binding.transport !== 'hook' || binding.runtime_target !== null) conflict('runtime_binding');
+    if (binding.provider_session_id !== sessionId || binding.provider_session_name !== null) {
+      conflict('session_id_mismatch');
+    }
+  }
+  const alias = db.prepare(`
+    SELECT peer FROM peer_bindings
+    WHERE provider = 'dsh' AND peer <> ?
+      AND (provider_session_id = ? OR provider_session_name = ?)
+    LIMIT 1
+  `).get(peerId, sessionId, sessionId);
+  if (alias) conflict('session_bound_to_another_peer', alias.peer);
 }
 
 function readParentResumeId(kind) {
@@ -203,3 +351,6 @@ function readParentResumeId(kind) {
   } catch {}
   return null;
 }
+
+  return { cmdHook };
+}

package/lib/cli/commands/lock.mjs

@@ -1,6 +1,13 @@
 // Lock CLI commands extracted from bin/hcc.mjs.
 // Factory pattern with injected deps.
 
+import { readTx } from '../../db/schema.mjs';
+import {
+  findRequestedLock,
+  upsertRequestedLock,
+  visibleLocksWithEvidence
+} from '../../core/coordination/locks.mjs';
+
 export function createLockCommands(deps) {
   const {
     connect,
@@ -109,21 +116,11 @@ export function createLockCommands(deps) {
           }
           const existing = subject.locks.find((row) => row.resource === requested.resource) || null;
           const expiresAt = leaseDeadline(t, ttl);
-          db.prepare(`
-            INSERT INTO locks(resource, base_resource, scope, owner, task_id, reason, expires_at, created_at, ttl_sec)
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-            ON CONFLICT(resource) DO UPDATE SET
-              base_resource = excluded.base_resource,
-              scope = excluded.scope,
-              owner = excluded.owner,
-              task_id = excluded.task_id,
-              reason = excluded.reason,
-              expires_at = excluded.expires_at,
-              created_at = excluded.created_at,
-              ttl_sec = excluded.ttl_sec
-          `).run(requested.resource, requested.base_resource, requested.scope, peer, taskId, reason, expiresAt, t, ttl);
+          const acquired = upsertRequestedLock(db, requested, {
+            owner: peer, task_id: taskId, reason, expires_at: expiresAt, created_at: t, ttl_sec: ttl
+          });
           addEvent(db, 'lock.acquired', peer, taskId, { resource: requested.base_resource, lock_resource: requested.resource, scope: requested.scope, ttl, previous_owner: existing ? existing.owner : null });
-          return { lock: db.prepare('SELECT * FROM locks WHERE resource = ?').get(requested.resource) };
+          return { lock: acquired };
         }
       });
       if (outcome.error) throw outcome.error;
@@ -143,7 +140,7 @@ export function createLockCommands(deps) {
     const db = connect(ctx);
     touchCurrentPeer(db, ctx, identity, null, 'shell');
     const result = tx(db, () => {
-      const existing = db.prepare('SELECT * FROM locks WHERE resource = ?').get(requested.resource);
+      const existing = findRequestedLock(db, requested);
       if (!existing) return { released: false, ...requested };
       if (existing.owner !== peer && !opts.force) {
         throw new CliError('LOCK_OWNED', `Lock is owned by ${existing.owner}`, { owner: existing.owner });
@@ -166,7 +163,7 @@ export function createLockCommands(deps) {
     const db = connect(ctx);
     touchCurrentPeer(db, ctx, identity, 'working', 'shell');
     const lock = tx(db, () => {
-      const existing = db.prepare('SELECT * FROM locks WHERE resource = ?').get(requested.resource);
+      const existing = findRequestedLock(db, requested);
       if (!existing) throw new CliError('NOT_FOUND', `No lock for ${lockLabel(requested)}`);
       if (existing.owner !== peer) throw new CliError('LOCK_OWNED', `Lock is owned by ${existing.owner}`, { owner: existing.owner });
       db.prepare('UPDATE locks SET expires_at = ?, ttl_sec = ? WHERE resource = ?').run(expiresAt, ttl, requested.resource);
@@ -180,9 +177,27 @@ export function createLockCommands(deps) {
     const opts = parseOpts(args, { booleans: ['all'] });
     const db = connect(ctx);
     const t = now();
-    const rows = opts.all || clockGraceSuppressed(t, readClockGraceUntil(db))
-      ? db.prepare('SELECT * FROM locks ORDER BY resource ASC').all()
-      : db.prepare('SELECT * FROM locks WHERE expires_at > ? ORDER BY resource ASC').all(t);
+    const { locks, owners, graceUntil } = readTx(db, () => {
+      const locks = db.prepare('SELECT * FROM locks ORDER BY resource ASC').all();
+      const graceUntil = readClockGraceUntil(db);
+      const expired = opts.all || clockGraceSuppressed(t, graceUntil)
+        ? [] : locks.filter((lock) => Number(lock.expires_at) <= t);
+      const owners = [...new Set(expired
+        .map((lock) => lock.owner))].map((owner) => ({
+        owner,
+        peer: db.prepare('SELECT * FROM peers WHERE id = ?').get(owner) || null,
+        binding: db.prepare('SELECT * FROM peer_bindings WHERE peer = ?').get(owner) || null
+      }));
+      return { locks, owners, graceUntil };
+    });
+    const evidenceByOwner = new Map(owners.map(({ owner, peer, binding }) => [
+      owner,
+      peer ? observePeerEvidence(ctx, peer, binding) : { state: 'unknown', reason: 'peer_missing' }
+    ]));
+    const rows = opts.all ? locks : visibleLocksWithEvidence(locks, t, {
+      graceActive: clockGraceSuppressed(t, graceUntil),
+      evidenceByOwner
+    });
     printResult(ctx, rows, (data) => table(data, [
       { label: 'resource', value: (r) => lockBaseResource(r) },
       { label: 'scope', value: (r) => lockScope(r) },

package/lib/cli/commands/mcp.mjs

@@ -0,0 +1,28 @@
+import { CliError } from '../../shared/errors.mjs';
+import { parseOpts, required, validateOpts, wantsHelp } from '../../cli-args.mjs';
+import { loadScopedMcpBootstrap } from '../../mcp/scope.mjs';
+import { createScopedMcpTools } from '../../mcp/tools.mjs';
+import { serveMcpStdio } from '../../mcp/stdio.mjs';
+
+export function mcpHelp() {
+  console.log(`Usage: hcc --root PROJECT --db DATABASE mcp serve --peer PEER
+
+Serve project/peer-scoped coordination tools over MCP stdio. The executor must
+supply a private, temporary capability; --peer alone does not grant ownership.
+No global Codex configuration is changed. Task claiming and handoff never mark
+tasks done. Errors from tools are returned as MCP tool results.`);
+}
+
+export function createMcpCommands(dependencies) {
+  async function cmdMcp(ctx, args) {
+    if (!args[0] || wantsHelp(args)) return mcpHelp();
+    if (args[0] !== 'serve') throw new CliError('BAD_ARGS', 'Unknown MCP command');
+    const options = parseOpts(args.slice(1));
+    validateOpts('mcp serve', options, ['peer']);
+    const peer = required(options, 'peer');
+    const authority = loadScopedMcpBootstrap(ctx, peer);
+    const tools = createScopedMcpTools({ ...dependencies, ctx, authority });
+    await serveMcpStdio({ tools });
+  }
+  return { cmdMcp };
+}

package/lib/cli/commands/misc.mjs

@@ -5,6 +5,7 @@ export function createMiscCommands(deps) {
     path, process, CliError, parseOpts, printResult,
     readRuntime, runtimeRequest, runtimePath, globalRuntimePath,
     reclaimRuntimePointerFiles, helpDown, loadSetup,
+    waitForProcessIdentityExit,
     PRODUCT_NAME
   } = deps;
 
@@ -35,6 +36,20 @@ export function createMiscCommands(deps) {
       printResult(ctx, { runtime: localSource }, () => `${PRODUCT_NAME} stale runtime pointer removed`);
       return;
     }
+    if (runtime.source !== 'env') {
+      const processIdentity = runtime.process_identity || runtime.processIdentity || runtime.pid;
+      const stopped = await waitForProcessIdentityExit(processIdentity, {
+        timeoutMs: 5_000,
+        intervalMs: 25
+      });
+      if (stopped.state !== 'dead') {
+        throw new CliError(
+          'RUNTIME_STOP_TIMEOUT',
+          `Runtime accepted the stop request, but process ${runtime.pid || 'unknown'} did not exit within 5s.`,
+          { pid: runtime.pid || null, state: stopped.state }
+        );
+      }
+    }
     printResult(ctx, { runtime: runtime.source || runtime.base_url }, () => `${PRODUCT_NAME} runtime stopped`);
   }