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

package/lib/cli/commands/install.mjs

@@ -5,17 +5,19 @@ import { secureExistingProjectStateDirectory } from '../../runtime/project-path.
 import { legacyProjectStateDir, projectStateDir } from '../../runtime/paths.mjs';
 import { privateProjectStateDir, inspectPrivateProjectAuthority,
   purgePrivateProjectState } from '../../runtime/private-state.mjs';
+import { captureSelectedCwdIdentity } from '../../process/selected-cwd-identity.mjs';
+import { purgePinnedLegacyProjectState } from '../../process/pinned-project-state.mjs';
 
 export function createInstallCommands(deps) {
   const {
     path, fs, process, CliError, parseOpts, validateOpts, wantsHelp,
     printResult, commandPath, connect, readRuntime, runtimeRequest,
-    runtimePath, globalRuntimePath, PRODUCT_NAME, VERSION, NPM_PACKAGE_NAME,
+    globalRuntimePath, PRODUCT_NAME, VERSION, NPM_PACKAGE_NAME,
     helpInstallHooks, helpShim, helpUninstall, helpUpdate,
     loadSetup, shellCommand,
 
 
-    sameResolvedPath, writeGuidance, removeGuidanceBlocks,
+    sameResolvedPath, writeGuidance, removeGuidanceBlocks, spawnPinnedStateProcess,
   
   } = deps;
 
@@ -240,13 +242,23 @@ async function cmdUninstall(ctx, args) {
   if (opts.purge && !opts.yes) {
     throw new CliError('CONFIRM_REQUIRED', 'Refusing to purge project data without --yes');
   }
+  const selectedRoot = opts.purge ? captureSelectedCwdIdentity(ctx.root) : null;
+  let selectedLegacyState = null;
+  try {
   // Resolve before changing hooks, guidance, or runtime state. An unsafe root
   // with unmigrated legacy data must not be treated as an empty private store.
   let purgeStateDir = null;
+  let purgeIsLegacy = false;
   let missingPrivateState = false;
   if (opts.purge) {
     try {
-      purgeStateDir = secureExistingProjectStateDirectory(ctx.root).stateDir;
+      const resolved = secureExistingProjectStateDirectory(ctx.root);
+      purgeStateDir = resolved.stateDir;
+      purgeIsLegacy = path.resolve(purgeStateDir) === path.join(selectedRoot.canonical, '.hello-cc');
+      if (purgeIsLegacy && resolved.exists) {
+        selectedLegacyState = captureSelectedCwdIdentity(purgeStateDir);
+        selectedRoot.assertUnchanged();
+      }
     } catch (error) {
       if (projectStateDir(ctx.root) !== privateProjectStateDir(ctx.root)) throw error;
       const recoverablePending = error?.code === 'STATE_MIGRATION_REQUIRED' &&
@@ -261,7 +273,12 @@ async function cmdUninstall(ctx, args) {
   const lines = [];
 
   let runtime = null;
+  let runtimePointer = null;
   if (!missingPrivateState) {
+    // Keep the validated state route fixed across the asynchronous stop probe.
+    // Re-deriving it afterwards could remove another project's pointer if a
+    // user-supplied root alias is retargeted in the meantime.
+    runtimePointer = path.join(secureExistingProjectStateDirectory(ctx.root).stateDir, 'runtime.json');
     try {
       runtime = readRuntime(ctx);
     } catch (err) {
@@ -274,7 +291,7 @@ async function cmdUninstall(ctx, args) {
       lines.push('runtime stopped');
     } catch (err) {
       if (!(err instanceof CliError && err.code === 'RUNTIME_UNREACHABLE')) throw err;
-      try { fs.rmSync(runtimePath(ctx), { force: true }); } catch {}
+      try { fs.rmSync(runtimePointer, { force: true }); } catch {}
       lines.push('stale runtime file removed');
     }
   } else {
@@ -282,6 +299,7 @@ async function cmdUninstall(ctx, args) {
   }
 
   const { uninstallClaudeHooks, uninstallCodexHooks, uninstallShims, uninstallPathEntry } = await loadSetup();
+  selectedRoot?.assertUnchanged();
   const claude = uninstallClaudeHooks();
   const codex = uninstallCodexHooks();
   const shims = uninstallShims();
@@ -294,20 +312,26 @@ async function cmdUninstall(ctx, args) {
   let guidance = [];
   let purged = false;
   if (opts.purge) {
-    guidance = removeGuidanceBlocks(ctx);
+    guidance = removeGuidanceBlocks(ctx, { expectedBinding: selectedRoot });
     try {
-      if (path.resolve(purgeStateDir) === path.resolve(privateProjectStateDir(ctx.root))) {
+      selectedRoot.assertUnchanged();
+      if (!purgeIsLegacy) {
         // Revalidate and delete under the same transition lock used by init
         // and migration. An interrupted deletion remains marked purging.
         purgeStateDir = purgePrivateProjectState(ctx.root);
       } else {
         // Async shutdown and hook removal happened after the initial lookup.
         // Refuse a stale legacy target if project-state routing changed.
-        const current = secureExistingProjectStateDirectory(ctx.root).stateDir;
-        if (path.resolve(current) !== path.resolve(purgeStateDir)) {
+        const current = secureExistingProjectStateDirectory(ctx.root);
+        if (path.resolve(current.stateDir) !== path.resolve(purgeStateDir)) {
           throw new CliError('PROJECT_PATH_FORBIDDEN', 'Project state route changed during uninstall');
         }
-        fs.rmSync(purgeStateDir, { recursive: true, force: true });
+        if (selectedLegacyState) {
+          purgePinnedLegacyProjectState(ctx.root, purgeStateDir, selectedRoot, selectedLegacyState,
+            { spawnProcess: spawnPinnedStateProcess });
+        } else if (current.exists) {
+          throw new CliError('PROJECT_PATH_FORBIDDEN', 'Project state appeared during uninstall');
+        }
       }
       purged = true;
       lines.push(`project data removed: ${purgeStateDir}`);
@@ -327,6 +351,10 @@ async function cmdUninstall(ctx, args) {
   }
 
   printResult(ctx, { runtime: Boolean(runtime), claude, codex, shims, path_entry: pathEntry, purge: purged, guidance }, () => lines.join('\n'));
+  } finally {
+    selectedLegacyState?.release();
+    selectedRoot?.release();
+  }
 }
 
 // ─── hcc scan ────────────────────────────────────────────────────────────────

package/lib/cli/commands/lock.mjs

@@ -2,6 +2,7 @@
 // Factory pattern with injected deps.
 
 import { readTx } from '../../db/schema.mjs';
+import { isPeerEvidenceCompatibilityProtected } from '../../core/peers/evidence.mjs';
 import {
   findRequestedLock,
   upsertRequestedLock,
@@ -101,7 +102,8 @@ export function createLockCommands(deps) {
                 !(Number(row.expires_at) <= t && evidenceByOwner.get(row.owner)?.state === 'dead'))
             : subject.locks.filter((row) =>
                 Number(row.expires_at) > t ||
-                evidenceByOwner.get(row.owner)?.state === 'live'
+                evidenceByOwner.get(row.owner)?.state === 'live' ||
+                isPeerEvidenceCompatibilityProtected(evidenceByOwner.get(row.owner))
               );
           const conflict = activeLocks.find((row) => locksConflict(row, requested) && row.owner !== peer);
           if (conflict) {

package/lib/cli/commands/misc.mjs

@@ -1,17 +1,79 @@
 // Small utility commands extracted from bin/hcc.mjs: down, find-root, which-real.
+import { performance } from 'node:perf_hooks';
+import { resolveProjectDatabase } from '../../runtime/project-path.mjs';
 
 export function createMiscCommands(deps) {
   const {
-    path, process, CliError, parseOpts, printResult,
+    path, fs, process, CliError, parseOpts, printResult,
     readRuntime, runtimeRequest, runtimePath, globalRuntimePath,
     reclaimRuntimePointerFiles, helpDown, loadSetup,
-    waitForProcessIdentityExit,
+    waitForProcessIdentityExit, inspectProcessIdentity, compareProcessIdentity, withFileLock,
     PRODUCT_NAME
   } = deps;
 
+  function sameStopPointer(left, right) {
+    return left.raw === right.raw && ['dev', 'ino', 'size', 'mtimeMs', 'ctimeMs']
+      .every((key) => left.stat[key] === right.stat[key]);
+  }
+
+  function readStopPointer(file) {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile()) throw new Error('invalid runtime pointer');
+    const raw = fs.readFileSync(file, 'utf8');
+    const current = fs.lstatSync(file);
+    if (current.isSymbolicLink() || !current.isFile() ||
+        !sameStopPointer({ raw, stat }, { raw, stat: current })) {
+      throw new Error('runtime pointer changed');
+    }
+    return { raw, stat };
+  }
+
+  function stopOwnerEvidence(runtime, pointerFiles) {
+    try {
+      if (runtime.source === 'env') return null;
+      const source = pointerFiles.find((file) => path.resolve(file) === path.resolve(runtime.source || ''));
+      const url = new URL(runtime.base_url);
+      if (!source || !['http:', 'https:'].includes(url.protocol) ||
+          !['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname)) return null;
+      const owner = runtime.process_identity || runtime.processIdentity;
+      if (Object.hasOwn(runtime, 'process_identity') && Object.hasOwn(runtime, 'processIdentity')) return null;
+      if (owner?.pid !== Number(runtime.pid) || compareProcessIdentity(owner, owner) !== 'live') return null;
+      const observed = inspectProcessIdentity(owner.pid);
+      if (observed.state !== 'live' || compareProcessIdentity(owner, observed.identity) !== 'live' ||
+          owner.commandHash !== observed.identity.commandHash) return null;
+      const pointer = readStopPointer(source);
+      const recorded = JSON.parse(pointer.raw);
+      if (Object.hasOwn(recorded, 'process_identity') && Object.hasOwn(recorded, 'processIdentity')) return null;
+      const recordedOwner = recorded.process_identity || recorded.processIdentity;
+      if (Number(recorded.pid) !== owner.pid ||
+          compareProcessIdentity(owner, recordedOwner) !== 'live' || owner.commandHash !== recordedOwner.commandHash ||
+          ['base_url', 'token', 'tls_ca_file'].some((key) => recorded[key] !== runtime[key])) return null;
+      return { source, owner, pointer };
+    } catch {
+      return null;
+    }
+  }
+
   async function cmdDown(ctx, args) {
     if (args[0] === '--help' || args[0] === '-h') return helpDown();
-    const pointerFiles = [runtimePath(ctx), globalRuntimePath()];
+    const stopStartedAt = performance.now();
+    const elapsedSince = (startedAt) => Math.max(0, Math.round(performance.now() - startedAt));
+    function stopFailure(error, phase, state = 'unknown', confirmationMs = null) {
+      // Retain the original error and transport context. Only fixed phase/state
+      // vocabulary and monotonic durations describe the local confirmation.
+      error.extra = {
+        ...error.extra,
+        stopPhase: phase,
+        state: ['live', 'dead', 'unknown'].includes(state) ? state : 'unknown',
+        stopElapsedMs: elapsedSince(stopStartedAt),
+        ...(confirmationMs === null ? {} : { confirmationMs })
+      };
+      return error;
+    }
+    const localPointer = ctx.root
+      ? path.join(resolveProjectDatabase({ root: ctx.root, createStateDir: false }).stateDir, 'runtime.json')
+      : runtimePath(ctx);
+    const pointerFiles = [localPointer, globalRuntimePath()];
     let runtime;
     try {
       runtime = readRuntime(ctx);
@@ -23,31 +85,61 @@ export function createMiscCommands(deps) {
         `${PRODUCT_NAME} stale runtime pointer removed${result.pointers === 1 ? '' : 's'}`);
       return;
     }
+    const stopEvidence = stopOwnerEvidence(runtime, pointerFiles);
     try {
       await runtimeRequest(ctx, 'POST', '/api/runtime/stop', {}, runtime);
     } catch (err) {
       if (!(err instanceof CliError && err.code === 'RUNTIME_UNREACHABLE')) throw err;
-      if (runtime.source === 'env') throw err;
-      const source = path.resolve(String(runtime.source || ''));
-      const localSource = pointerFiles.find((file) => path.resolve(file) === source);
-      if (!localSource) throw err;
-      const cleanup = reclaimRuntimePointerFiles([localSource], { reclaimUnknown: false });
-      if (cleanup.reclaimed !== 1 || cleanup.blocked) throw err;
-      printResult(ctx, { runtime: localSource }, () => `${PRODUCT_NAME} stale runtime pointer removed`);
+      if (!stopEvidence) throw stopFailure(err, 'evidence_unavailable');
+      const confirmationStartedAt = performance.now();
+      const stopped = await waitForProcessIdentityExit(stopEvidence.owner, {
+        timeoutMs: 5_000,
+        intervalMs: 25
+      });
+      const confirmationMs = elapsedSince(confirmationStartedAt);
+      if (stopped.state !== 'dead') throw stopFailure(err, 'exit_unconfirmed', stopped.state, confirmationMs);
+      let cleanup;
+      let cleanupPhase = 'pointer_cleanup_failed';
+      try {
+        cleanup = withFileLock(stopEvidence.source, (file) => {
+          let current;
+          try { current = readStopPointer(file); }
+          catch (error) {
+            if (error.code === 'ENOENT') return { reclaimed: 0, blocked: false };
+            throw error;
+          }
+          if (!sameStopPointer(stopEvidence.pointer, current)) {
+            cleanupPhase = 'pointer_changed';
+            throw err;
+          }
+          // Hold the pointer's existing lock across comparison and reclamation.
+          // A replacement owner must never be removed by this stop request.
+          return reclaimRuntimePointerFiles([file], {
+            reclaimUnknown: false,
+            withLock: (_file, operation) => operation(file)
+          });
+        }, { createParent: false });
+      } catch { throw stopFailure(err, cleanupPhase, 'dead', confirmationMs); }
+      if (cleanup.blocked || cleanup.reclaimed > 1) throw stopFailure(err, 'pointer_cleanup_failed', 'dead', confirmationMs);
+      printResult(ctx, { runtime: stopEvidence.source }, () => cleanup.reclaimed === 1
+        ? `${PRODUCT_NAME} stale runtime pointer removed`
+        : `${PRODUCT_NAME} runtime stopped`);
       return;
     }
     if (runtime.source !== 'env') {
       const processIdentity = runtime.process_identity || runtime.processIdentity || runtime.pid;
+      const confirmationStartedAt = performance.now();
       const stopped = await waitForProcessIdentityExit(processIdentity, {
         timeoutMs: 5_000,
         intervalMs: 25
       });
+      const confirmationMs = elapsedSince(confirmationStartedAt);
       if (stopped.state !== 'dead') {
-        throw new CliError(
+        throw stopFailure(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 }
-        );
+          { pid: runtime.pid || null }
+        ), 'exit_unconfirmed', stopped.state, confirmationMs);
       }
     }
     printResult(ctx, { runtime: runtime.source || runtime.base_url }, () => `${PRODUCT_NAME} runtime stopped`);

package/lib/cli/commands/native.mjs

@@ -1,13 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { spawn } from 'node:child_process';
-import { setTimeout as delay } from 'node:timers/promises';
 import { CliError } from '../../shared/errors.mjs';
 import { parseOpts, validateOpts, wantsHelp, intOpt } from '../../cli-args.mjs';
 import { printResult } from '../../format.mjs';
-import { commandPath } from '../../cli-runtime.mjs';
-import { nativePaths, readNativePointer } from '../../runtime/native/store.mjs';
-import { openPrivateAppendFile } from '../../runtime/private-file.mjs';
+import { ensureNativeRuntime } from '../../runtime/native/launcher.mjs';
 import { nativeRequest } from '../../runtime/native/client.mjs';
 import { startNativeService } from '../../runtime/native/service.mjs';
 
@@ -30,43 +26,6 @@ dsh workers use the ACP profile, not its Web-service terminal.`);
 }
 
 export function createNativeCommands(deps) {
-  async function up(ctx) {
-    if (readNativePointer(ctx)) {
-      try { return await nativeRequest(ctx, 'GET', '/status', null, { timeoutMs: 2000 }); }
-      catch (error) {
-        if (error.code !== 'NATIVE_RUNTIME_OFFLINE') throw error;
-      }
-    }
-    const paths = nativePaths(ctx, { create: true });
-    let log;
-    let child;
-    try {
-      log = openPrivateAppendFile(paths.log);
-      child = spawn(process.execPath, [commandPath(), '--root', fs.realpathSync(ctx.root), '--db', path.resolve(ctx.dbPath), 'native', 'serve'], {
-        cwd: ctx.root, env: process.env, detached: true, stdio: ['ignore', log, log]
-      });
-    } catch (error) {
-      if (error?.code === 'PROJECT_PATH_FORBIDDEN') {
-        throw new CliError('NATIVE_STATE_UNSAFE', error.message);
-      }
-      throw error;
-    } finally {
-      if (log !== undefined) fs.closeSync(log);
-    }
-    let failed;
-    child.on('error', (error) => { failed = error; });
-    child.unref();
-    const deadline = Date.now() + 10000;
-    while (Date.now() < deadline) {
-      if (failed) throw new CliError('NATIVE_RUNTIME_START_FAILED', failed.message);
-      if (readNativePointer(ctx)) {
-        try { return await nativeRequest(ctx, 'GET', '/status', null, { timeoutMs: 1000 }); } catch {}
-      }
-      await delay(100);
-    }
-    throw new CliError('NATIVE_RUNTIME_START_FAILED', `Native runtime did not become ready. Inspect ${paths.log}`);
-  }
-
   async function cmdNative(ctx, args) {
     const command = args[0];
     if (!command || wantsHelp(args)) return nativeHelp();
@@ -86,7 +45,7 @@ export function createNativeCommands(deps) {
     if (command === 'start' && opts.provider === 'claude' && opts.binary !== undefined) throw new CliError('BAD_ARGS', 'Claude workers use the Agent SDK; --binary is available for Codex and dsh');
     if (command === 'send' && !opts.body?.trim()) throw new CliError('BAD_ARGS', 'Missing --body');
     let result;
-    if (command === 'up') result = await up(ctx);
+    if (command === 'up') result = await ensureNativeRuntime(ctx);
     else if (command === 'serve') {
       const service = await startNativeService(ctx, deps);
       const shutdown = () => { void service.shutdown().catch((error) => console.error(JSON.stringify({ code: error.code, message: error.message }))); };
@@ -94,7 +53,7 @@ export function createNativeCommands(deps) {
       process.once('SIGINT', shutdown);
       return;
     } else if (command === 'start') {
-      await up(ctx);
+      await ensureNativeRuntime(ctx);
       result = await nativeRequest(ctx, 'POST', '/workers', { peer: opts.peer, provider: opts.provider,
         cwd: opts.cwd ? path.resolve(ctx.cwd, opts.cwd) : ctx.root, model: opts.model, binary: opts.binary, resume: opts.resume });
     } else if (command === 'send') {

package/lib/cli/commands/peer.mjs

@@ -4,6 +4,7 @@ import {
   RUNTIME_SESSION_MUTATION_TIMEOUT_MS,
   RUNTIME_SESSION_START_TIMEOUT_MS
 } from '../../runtime/client.mjs';
+import { captureSelectedCwdSnapshot } from '../../process/selected-cwd-identity.mjs';
 
 export function createPeerCommands(deps) {
   const {
@@ -75,6 +76,7 @@ async function peerStart(ctx, args) {
   const kind = inferPeerKind(id, opts.kind, firstCommand);
   const role = opts.role || 'peer';
   const cwd = path.resolve(opts.cwd || ctx.root);
+  const cwdIdentity = captureSelectedCwdSnapshot(cwd);
   const built = buildPeerCommand(id, kind, opts, cmdArgs);
   const command = built.command;
   const binding = { ...built.binding, transport: 'tmux', runtime_session_id: id };
@@ -139,6 +141,7 @@ async function peerStart(ctx, args) {
     role,
     command,
     cwd,
+    cwdIdentity,
     binding,
     env: childSessionEnv(),
     restartOnEnvChange: Boolean(opts['restart-env']),

package/lib/cli/commands/run.mjs

@@ -6,8 +6,9 @@ import path from 'node:path';
 import fs from 'node:fs';
 import process from 'node:process';
 import { randomBytes } from 'node:crypto';
-import { spawn } from 'node:child_process';
 import { CliError } from '../../shared/errors.mjs';
+import { spawnPinnedCwdProcess, spawnPinnedCwdPty } from '../../process/pinned-cwd.mjs';
+import { captureSelectedCwdSnapshot } from '../../process/selected-cwd-identity.mjs';
 import { tx } from '../../db/schema.mjs';
 import { parseOpts, validateOpts } from '../../cli-args.mjs';
 import { runtimeProcessIdentity } from '../../runtime/state.mjs';
@@ -57,6 +58,7 @@ async function cmdRun(ctx, args) {
   const id = identity.id;
   const role = opts.role || 'peer';
   const cwd = path.resolve(opts.cwd || ctx.cwd);
+  const expectedCwdIdentity = captureSelectedCwdSnapshot(cwd);
   const command = cmdArgs.length ? cmdArgs[0] : defaultSessionCommand(kind);
   const commandArgs = cmdArgs.length ? cmdArgs.slice(1) : [];
   const binding = bindingFromRun(id, kind, command, commandArgs, 'hcc-run');
@@ -67,6 +69,7 @@ async function cmdRun(ctx, args) {
       kind,
       role,
       cwd,
+      expectedCwdIdentity,
       command,
       commandArgs,
       binding,
@@ -131,10 +134,12 @@ async function cmdRun(ctx, args) {
     db.close();
   }
   console.error(redactedLogText(`${CLI_NAME}: running ${id} (${kind}, ${role}) -> ${command} ${commandArgs.join(' ')}`.trim()));
-  const child = spawn(command, commandArgs, {
+  const child = spawnPinnedCwdProcess(command, commandArgs, {
     cwd,
+    expectedIdentity: expectedCwdIdentity,
     stdio: 'inherit',
-    env: childSessionEnv({ HCC_PEER: id, HCC_ROOT: ctx.root, HCC_DB: ctx.dbPath })
+    env: childSessionEnv({ HCC_PEER: id, HCC_ROOT: ctx.root, HCC_DB: ctx.dbPath },
+      process.env, { rootIdentity: ctx.initialRootIdentity })
   });
   const exitCode = await new Promise((resolve) => {
     child.on('exit', (code, signal) => resolve({ code, signal }));
@@ -174,7 +179,7 @@ async function cmdRun(ctx, args) {
  * the local terminal and a shared buffer file so hcc web can stream it to
  * browsers. Input from the browser is written to a .in file that we relay.
  */
-async function cmdRunWebManaged(ctx, { id, kind, role, cwd, command, commandArgs, binding, force = false }) {
+async function cmdRunWebManaged(ctx, { id, kind, role, cwd, expectedCwdIdentity, command, commandArgs, binding, force = false }) {
   registerProjectActivity(ctx);
   const ptyModule = await import('node-pty');
   const pty = ptyModule.default || ptyModule;
@@ -265,9 +270,11 @@ async function cmdRunWebManaged(ctx, { id, kind, role, cwd, command, commandArgs
   const cols = process.stdout.columns || 120;
   const rows = process.stdout.rows || 40;
 
-  const child = pty.spawn(command, commandArgs, {
+  const child = spawnPinnedCwdPty(pty, command, commandArgs, {
     name: 'xterm-256color', cols, rows, cwd,
-    env: childSessionEnv({ HCC_PEER: id, HCC_ROOT: ctx.root, HCC_DB: ctx.dbPath, TERM: 'xterm-256color' })
+    expectedIdentity: expectedCwdIdentity,
+    env: childSessionEnv({ HCC_PEER: id, HCC_ROOT: ctx.root, HCC_DB: ctx.dbPath, TERM: 'xterm-256color' },
+      process.env, { rootIdentity: ctx.initialRootIdentity })
   });
   const childExit = trackPtyExit(child);
   const wrapperTermination = installPtyTerminationHandlers(child);

package/lib/cli/commands/tmux.mjs

@@ -2,7 +2,6 @@
 // hcc scan detects provider sessions; the tmux helpers implement DB-proven,
 // evidence-checked tmux GC (plan/validate/execute) for hcc-managed sessions.
 
-import path from 'node:path';
 import process from 'node:process';
 import { spawnSync } from 'node:child_process';
 import { CliError } from '../../shared/errors.mjs';
@@ -527,7 +526,7 @@ async function planTmuxGc(ctx, opts) {
       continue;
     }
     const hccRoot = tmuxSessionEnvironmentValue(actualSession, 'HCC_ROOT');
-    if (hccRoot && path.resolve(hccRoot) !== path.resolve(ctx.root)) {
+    if (hccRoot && rootEvidence(ctx.root, hccRoot).state !== 'match') {
       skip('hcc_root_mismatch', { hcc_root: hccRoot });
       continue;
     }

package/lib/cli-runtime.mjs

@@ -2,15 +2,32 @@ import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 import { projectDbPath } from './runtime/paths.mjs';
+import { captureSelectedCwdSnapshot } from './process/selected-cwd-identity.mjs';
 
 export function createContext(global = {}, deps = {}) {
   const cwd = deps.cwd || process.cwd();
   const detectRoot = deps.detectRoot;
   if (typeof detectRoot !== 'function') throw new TypeError('createContext requires deps.detectRoot');
-  const root = detectRoot(cwd, global.root);
+  const requestedRoot = detectRoot(cwd, global.root);
+  // Freeze an existing root's canonical pathname for this command. A symlink
+  // supplied through --root (or HCC_ROOT) may be retargeted after context
+  // construction; later state and runtime path derivations must not silently
+  // switch projects. Missing roots retain their path for commands that create
+  // a project directory.
+  let root;
+  let initialRootIdentity = null;
+  try {
+    root = fs.realpathSync.native(requestedRoot);
+    initialRootIdentity = captureSelectedCwdSnapshot(root);
+  }
+  catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+    root = requestedRoot;
+  }
   const envDb = global.root ? null : process.env.HCC_DB;
   const dbPath = path.resolve(global.db || envDb || projectDbPath(root));
-  return { cwd, root, dbPath, json: global.json, explicitRoot: Boolean(global.root || process.env.HCC_ROOT) };
+  return { cwd, root, dbPath, json: global.json,
+    explicitRoot: Boolean(global.root || process.env.HCC_ROOT), initialRootIdentity };
 }
 
 export function shellCommand(args, quoteArg) {

package/lib/core/coordination/gc-plan.mjs

@@ -2,6 +2,7 @@ import { randomBytes } from 'node:crypto';
 
 import { readTx, tx } from '../../db/schema.mjs';
 import { aggregateCleanupFailure } from '../../shared/cleanup-error.mjs';
+import { isPeerEvidenceCompatibilityProtected } from '../peers/evidence.mjs';
 import { DURABLE_RUNTIME_EVENTS } from './event-retention.mjs';
 
 export const HISTORY_GC_BATCH_SIZE = 256;
@@ -59,6 +60,10 @@ export function finalizeGcLockSubjects(db, subjects, evidenceByOwner, options =
         result.live += 1;
         continue;
       }
+      if (isPeerEvidenceCompatibilityProtected(evidenceByOwner.get(owner))) {
+        result.deferred += 1;
+        continue;
+      }
       if (dryRun || deleteExactRow(db, 'locks', planned.lock)) result.deleted += 1;
       else result.deferred += 1;
     }

package/lib/core/coordination/locks.mjs

@@ -1,4 +1,5 @@
 import { CliError } from '../../shared/errors.mjs';
+import { isPeerEvidenceCompatibilityProtected } from '../peers/evidence.mjs';
 
 export const WHOLE_LOCK_SCOPE = '*';
 
@@ -87,5 +88,6 @@ export function visibleLocksWithEvidence(locks, nowSec, {
   evidenceByOwner = new Map()
 } = {}) {
   return (locks || []).filter((lock) => graceActive || Number(lock.expires_at) > nowSec ||
-    evidenceByOwner.get(lock.owner)?.state === 'live');
+    evidenceByOwner.get(lock.owner)?.state === 'live' ||
+    isPeerEvidenceCompatibilityProtected(evidenceByOwner.get(lock.owner)));
 }

package/lib/core/peers/evidence.mjs

@@ -1,18 +1,26 @@
-import { compareProcessIdentity } from '../../process/identity.mjs';
+import { compareProcessIdentity, isProcessIdentityIncompatible } from '../../process/identity.mjs';
 
 const DEFAULT_ACTIVE_PEER_TTL = 600;
+const INCOMPATIBLE_PROCESS_REASON = 'process_identity_incompatible';
+
+export function isPeerEvidenceCompatibilityProtected(evidence = {}) {
+  return evidence.state === 'unknown' && evidence.reason === INCOMPATIBLE_PROCESS_REASON;
+}
 
 export function classifyPeerActivity(peer = {}, options = {}) {
   const activePeerTtl = Number(options.activePeerTtl ?? DEFAULT_ACTIVE_PEER_TTL);
   const graceActive = Boolean(options.graceActive);
   const evidenceState = peer.evidence_state || peer.evidence?.state || 'unknown';
+  const evidenceReason = peer.evidence_reason || peer.evidence?.reason;
   const age = Number(peer.age_sec);
   const active = evidenceState === 'live' ||
+    isPeerEvidenceCompatibilityProtected({ state: evidenceState, reason: evidenceReason }) ||
     (evidenceState !== 'dead' && (graceActive || (Number.isFinite(age) && age <= activePeerTtl)));
   return { active, stale: !active };
 }
 
 export function peerEvidenceAllowsReap(evidence = {}, options = {}) {
+  if (isPeerEvidenceCompatibilityProtected(evidence)) return false;
   if (evidence.state === 'dead') return true;
   if (evidence.state !== 'unknown') return false;
   const nowSec = Number(options.nowSec);
@@ -37,6 +45,9 @@ function processState(evidence) {
   if (evidence.current?.state === 'unknown') return 'unknown';
   if (evidence.current?.state === 'dead') return 'dead';
   if (evidence.current?.state !== 'live') return 'unknown';
+  if (isProcessIdentityIncompatible(evidence.storedIdentity, evidence.current.identity)) {
+    return 'incompatible';
+  }
   return compareProcessIdentity(evidence.storedIdentity, evidence.current.identity);
 }
 
@@ -48,6 +59,9 @@ function aggregateProcesses(processes) {
   if (states.includes('live')) {
     return { state: 'live', reason: 'process_identity_match' };
   }
+  if (states.includes('incompatible')) {
+    return { state: 'unknown', reason: INCOMPATIBLE_PROCESS_REASON };
+  }
   if (states.every((state) => state === 'dead')) {
     const missing = processes.every((item) => item?.current?.state === 'dead');
     return {
@@ -81,8 +95,14 @@ function tmuxVerifiedLive(tmux) {
 export function resolvePeerEvidence(input = {}) {
   const ordinaryProcess = aggregateProcesses(input.processes);
   if (ordinaryProcess.state === 'live') return ordinaryProcess;
+  // A live PID with incomparable Darwin generations proves neither ownership
+  // nor exit. Retain that distinction through persisted status and TTL gates.
+  if (isPeerEvidenceCompatibilityProtected(ordinaryProcess)) return ordinaryProcess;
 
   const tmux = input.tmux?.managed ? input.tmux : null;
+  if (ordinaryProcess.state === 'unknown' && tmux && tmuxProcessState(tmux) === 'incompatible') {
+    return { state: 'unknown', reason: INCOMPATIBLE_PROCESS_REASON };
+  }
   if (ordinaryProcess.state === 'unknown' && tmux && tmuxVerifiedLive(tmux)) {
     return { state: 'live', reason: 'tmux_identity_match' };
   }

package/lib/core/peers/tmux-safety.mjs

@@ -1,6 +1,7 @@
 import { compareProcessIdentity } from '../../process/identity.mjs';
 import { tx } from '../../db/schema.mjs';
 import { CliError } from '../../shared/errors.mjs';
+import { isPeerEvidenceCompatibilityProtected } from './evidence.mjs';
 
 function completeIdentity(identity) {
   return Boolean(
@@ -84,6 +85,9 @@ export function validateTmuxGcBindingEvidence(subject = {}, observed = {}, optio
   if (subject.owner_evidence?.state === 'live') {
     return { ok: false, reason: 'tmux_owner_process_live' };
   }
+  if (isPeerEvidenceCompatibilityProtected(subject.owner_evidence)) {
+    return { ok: false, reason: 'tmux_owner_process_incompatible' };
+  }
 
   const dead = validateTmuxGcDeadProcessEvidence(authority, observed, options);
   if (dead.ok) return { ok: true, mode: 'dead_process' };