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

package/lib/cli/commands/native.mjs

@@ -1,20 +1,17 @@
 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';
 
 export function nativeHelp() {
   console.log(`Usage: hcc native up|status|down
-       hcc native start --peer NAME --provider codex|claude|dsh [--cwd DIR] [--model MODEL] [--binary PATH] [--resume last]
-       hcc native send --peer NAME --body TEXT [--from NAME] [--task ID]
+       hcc native start --peer NAME --provider codex|claude|dsh [--cwd DIR] [--model MODEL] [--binary PATH] [--resume last] [--sandbox read-only|workspace-write]
+       hcc native fork --parent NAME --peer NEW_NAME [--model MODEL] [--binary PATH]
+       hcc native send --peer NAME --body TEXT [--from NAME] [--task ID] [--submission-id ID]
        hcc native events --peer NAME [--after ID]
        hcc native deliveries [--peer NAME]
        hcc native requests --peer NAME
@@ -24,69 +21,51 @@ export function nativeHelp() {
 
 Native workers share the project task/message/lock bus. Only HCC-owned saved
 sessions can resume. Existing TUI/Desktop sessions keep their own transport.
+Use a unique --submission-id for each new message and reuse it only for an
+exact retry after an uncertain receipt.
 Providers retain their permission checks; interactive requests await an explicit Web or local response.
+Codex alone accepts --sandbox. New sessions default to workspace-write; resumed and forked sessions inherit their saved policy.
+read-only disables permission escalation and HCC scoped MCP tools. It is a provider file sandbox, not an all-tools/network guarantee.
 Claude workers require the optional @anthropic-ai/claude-agent-sdk package.
 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);
+  function requireSandboxRuntime(runtime) {
+    if (runtime?.sandboxPolicyVersion !== 1) {
+      throw new CliError('NATIVE_SANDBOX_RUNTIME_UNSUPPORTED',
+        'This native runtime cannot preserve Codex sandbox policies. Stop the project native runtime after its work has finished, then start it with this HCC version. No worker was created.');
     }
-    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);
+    if (typeof runtime?.generation !== 'string' ||
+        !runtime.generation.trim() || runtime.generation.length > 128) {
+      throw new CliError('NATIVE_OWNER_CHANGED', 'Native runtime did not report a verifiable generation. No worker was created.');
     }
-    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();
     const opts = parseOpts(args.slice(1));
     const allowed = {
       up: [], serve: [], down: [], status: [],
-      start: ['peer', 'provider', 'cwd', 'model', 'binary', 'resume'],
-      send: ['peer', 'body', 'from', 'task'],
+      start: ['peer', 'provider', 'cwd', 'model', 'binary', 'resume', 'sandbox'],
+      send: ['peer', 'body', 'from', 'task', 'submission-id'],
       events: ['peer', 'after'], deliveries: ['peer'], requests: ['peer'],
       respond: ['peer', 'request', 'decision', 'response-file'],
+      fork: ['peer', 'parent', 'model', 'binary'],
       interrupt: ['peer', 'turn'], close: ['peer']
     };
     if (!Object.hasOwn(allowed, command)) throw new CliError('BAD_ARGS', `Unknown native command: ${command}`);
     validateOpts(`native ${command}`, opts, allowed[command]);
-    if (['start', 'send', 'events', 'interrupt', 'close', 'requests', 'respond'].includes(command) && !opts.peer) throw new CliError('BAD_ARGS', 'Missing --peer');
+    if (['start', 'fork', 'send', 'events', 'interrupt', 'close', 'requests', 'respond'].includes(command) && !opts.peer) throw new CliError('BAD_ARGS', 'Missing --peer');
     if (command === 'start' && !opts.provider) throw new CliError('BAD_ARGS', 'Missing --provider');
     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 === 'start' && opts.sandbox !== undefined &&
+        (opts.provider !== 'codex' || !['read-only', 'workspace-write'].includes(opts.sandbox))) {
+      throw new CliError('BAD_ARGS', '--sandbox accepts read-only or workspace-write for Codex only');
+    }
     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,14 +73,28 @@ export function createNativeCommands(deps) {
       process.once('SIGINT', shutdown);
       return;
     } else if (command === 'start') {
-      await up(ctx);
+      const runtime = await ensureNativeRuntime(ctx);
+      if (opts.provider === 'codex') requireSandboxRuntime(runtime);
       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 });
+        cwd: opts.cwd ? path.resolve(ctx.cwd, opts.cwd) : ctx.root, model: opts.model, binary: opts.binary, resume: opts.resume,
+        ...(opts.sandbox !== undefined ? { sandbox: opts.sandbox } : {}) },
+        opts.provider === 'codex' ? { expectedGeneration: runtime.generation } : undefined);
+    } else if (command === 'fork') {
+      if (!opts.parent) throw new CliError('BAD_ARGS', 'Missing --parent');
+      const runtime = await nativeRequest(ctx, 'GET', '/status');
+      requireSandboxRuntime(runtime);
+      result = await nativeRequest(ctx, 'POST', '/fork', { parent: opts.parent, peer: opts.peer, model: opts.model, binary: opts.binary },
+        { expectedGeneration: runtime.generation });
     } else if (command === 'send') {
       const taskId = intOpt(opts, 'task', null);
       if (taskId !== null && taskId < 1) throw new CliError('BAD_ARGS', 'Task ID must be positive');
+      const submissionId = opts['submission-id'];
+      if (submissionId !== undefined && !/^[A-Za-z0-9_-]{8,100}$/.test(submissionId)) {
+        throw new CliError('BAD_ARGS', 'Submission ID must contain 8 to 100 letters, digits, underscores, or hyphens');
+      }
       const sender = deps.resolveCurrentPeer(ctx, opts, 'from', 'shell').id;
-      result = await nativeRequest(ctx, 'POST', '/send', { peer: opts.peer, from: sender, body: opts.body, taskId });
+      result = await nativeRequest(ctx, 'POST', '/send', { peer: opts.peer, from: sender, body: opts.body, taskId,
+        ...(submissionId ? { submissionId } : {}) });
     } else if (command === 'events') {
       const after = intOpt(opts, 'after', 0);
       if (after < 0) throw new CliError('BAD_ARGS', 'Event cursor must be nonnegative');

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

package/lib/core/sessions/hook-root-identity.mjs

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import {
+  assertSelectedCwdSnapshot,
+  captureSelectedCwdSnapshot,
+  sameSelectedCwdIdentity
+} from '../../process/selected-cwd-identity.mjs';
+import { CliError } from '../../shared/errors.mjs';
+
+export const HOOK_ROOT_IDENTITY_ENV = 'HCC_HOOK_ROOT_IDENTITY';
+
+function mismatch() {
+  return new CliError('HOOK_ROOT_IDENTITY_MISMATCH',
+    'Hook project root no longer matches the provider launch identity');
+}
+
+// Carry the launch-time directory identity into short-lived hook children.
+// A pathname alone cannot distinguish a moved project from another directory
+// subsequently installed at the same pathname.
+export function hookRootIdentityValue(root, original = null) {
+  const selected = captureSelectedCwdSnapshot(root);
+  if (original) {
+    if (typeof original.assertUnchanged === 'function') original.assertUnchanged();
+    else assertSelectedCwdSnapshot(original);
+    if (!sameSelectedCwdIdentity(selected, original)) throw mismatch();
+  }
+  return JSON.stringify({ version: 1, ...selected });
+}
+
+export function assertHookRootIdentity(root, value) {
+  if (value === undefined) return false; // Unmanaged and pre-upgrade hooks have no launch marker.
+  try {
+    if (typeof value !== 'string' || value.length > 4096) throw mismatch();
+    const snapshot = JSON.parse(value);
+    if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot) ||
+        snapshot.version !== 1 || snapshot.requested !== path.resolve(root) ||
+        typeof snapshot.canonical !== 'string' || !path.isAbsolute(snapshot.canonical) ||
+        !snapshot.identity || typeof snapshot.identity !== 'object' ||
+        !/^\d+$/.test(snapshot.identity.dev) || !/^\d+$/.test(snapshot.identity.ino) ||
+        (snapshot.identity.birthtimeNs !== null && !/^\d+$/.test(snapshot.identity.birthtimeNs))) {
+      throw mismatch();
+    }
+    assertSelectedCwdSnapshot(snapshot);
+    return snapshot;
+  } catch {
+    throw mismatch();
+  }
+}

package/lib/core/sessions/launch.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 import { shortHash } from '../peers/format.mjs';
+import { HOOK_ROOT_IDENTITY_ENV, hookRootIdentityValue } from './hook-root-identity.mjs';
 
 export const WEB_CHILD_ENV = 'HCC_WEB_CHILD';
 export const LAUNCH_FINGERPRINT_ENV = 'HCC_LAUNCH_FINGERPRINT';
@@ -11,6 +12,7 @@ const LAUNCH_ENV_IGNORED_KEYS = new Set([
   '_',
   'COLUMNS',
   'HCC_DB',
+  HOOK_ROOT_IDENTITY_ENV,
   'HCC_NO_AUTO_INSTALL_TMUX',
   'HCC_PEER',
   'HCC_ROOT',
@@ -41,8 +43,12 @@ const LAUNCH_ENV_IGNORED_KEYS = new Set([
   'SSH_AUTH_SOCK'
 ]);
 
-export function childSessionEnv(extra = {}, baseEnv = process.env) {
+export function childSessionEnv(extra = {}, baseEnv = process.env, { rootIdentity = null } = {}) {
   const env = { ...(baseEnv || {}), ...extra };
+  if (Object.hasOwn(extra, 'HCC_ROOT')) {
+    if (extra.HCC_ROOT) env[HOOK_ROOT_IDENTITY_ENV] = hookRootIdentityValue(extra.HCC_ROOT, rootIdentity);
+    else delete env[HOOK_ROOT_IDENTITY_ENV];
+  }
   delete env[WEB_CHILD_ENV];
   delete env.HCC_RUNTIME_LOCAL_ONLY;
   return env;

package/lib/db/connection.mjs

@@ -10,7 +10,8 @@ import { DatabaseSync } from 'node:sqlite';
 import { CliError } from '../shared/errors.mjs';
 import {
   DB_SCHEMA_VERSION,
-  execWithBusyRetry
+  execWithBusyRetry,
+  readSchemaVersion
 } from './schema.mjs';
 import { initSchemaWithBackup } from './migration-backup.mjs';
 import { readProjectRegistry } from '../runtime/projects.mjs';
@@ -18,6 +19,7 @@ import { resolveProjectDatabase, secureExistingProjectStateDirectory } from '../
 import { projectStateDir, legacyProjectStateDir } from '../runtime/paths.mjs';
 import { privateProjectStateDir, ensurePrivateProjectStateDir } from '../runtime/private-state.mjs';
 import { unsafeDirectoryAcl } from '../runtime/project-trust.mjs';
+import { assertSelectedCwdSnapshot } from '../process/selected-cwd-identity.mjs';
 
 const MIGRATION_FAILURE_COOLDOWN_MS = 5 * 60 * 1000;
 
@@ -28,16 +30,40 @@ function managedDatabase(ctx) {
   try { canonicalRoot = fs.realpathSync.native(requestedRoot); } catch {}
   const requestedDb = path.resolve(ctx.dbPath);
   let canonicalCandidate = requestedDb;
-  try {
-    canonicalCandidate = path.join(fs.realpathSync.native(path.dirname(requestedDb)), path.basename(requestedDb));
-  } catch {}
-  return [requestedRoot, canonicalRoot].some(root =>
+  let parent = path.dirname(requestedDb);
+  const missingParents = [];
+  for (;;) {
+    try {
+      canonicalCandidate = path.join(fs.realpathSync.native(parent),
+        ...missingParents, path.basename(requestedDb));
+      break;
+    } catch (error) {
+      if (error?.code !== 'ENOENT' || path.dirname(parent) === parent) break;
+      missingParents.unshift(path.basename(parent));
+      parent = path.dirname(parent);
+    }
+  }
+  const candidates = new Set([requestedDb, canonicalCandidate]);
+  try { candidates.add(fs.realpathSync.native(requestedDb)); } catch {}
+  const within = (parent, candidate) => {
+    const relative = path.relative(parent, candidate);
+    return relative !== '' && relative !== '..' &&
+      !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+  };
+  const managed = [requestedRoot, canonicalRoot].some(root =>
     [legacyProjectStateDir(root), privateProjectStateDir(root)].some(stateDir =>
-      [requestedDb, canonicalCandidate].some(db => {
-        const relative = path.relative(stateDir, db);
-        return relative !== '' && relative !== '..' &&
-          !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
-      })));
+      [...candidates].some(db => within(stateDir, db))));
+  if (managed) return true;
+  // A context may have captured A's local or private .hello-cc DB before its
+  // root alias was repointed to B. A reserved state path is never an explicit
+  // external DB just because it no longer belongs to the current root.
+  const reservedStatePath = db => path.dirname(db).split(path.sep).some(segment =>
+    segment.toLowerCase() === '.hello-cc');
+  if ([...candidates].some(reservedStatePath)) {
+    throw new CliError('PROJECT_PATH_FORBIDDEN',
+      `Private database path is not bound to the current project root: ${requestedDb}`);
+  }
+  return false;
 }
 
 function secureOwnedSqliteFile(file, { create = false, readOnly = false, optional = false } = {}) {
@@ -115,6 +141,11 @@ export function createConnectionHelpers({ now, dedupePeerBindings, redactedLogTe
   const migratedRegisteredProjectDbs = new Set();
 
   function connect(ctx, options = {}) {
+    const existingSchema = options.existingSchema === true;
+    if (existingSchema && options.create !== false) {
+      throw new TypeError('existingSchema requires create: false');
+    }
+    if (ctx.initialRootIdentity) assertSelectedCwdSnapshot(ctx.initialRootIdentity);
     let dbPath = ctx.dbPath;
     if (managedDatabase(ctx)) {
       const rootWasMissing = options.create !== false && !fs.existsSync(ctx.root);
@@ -144,20 +175,35 @@ export function createConnectionHelpers({ now, dedupePeerBindings, redactedLogTe
       }
       if (options.create !== false) fs.mkdirSync(path.dirname(dbPath), { recursive: true });
     }
-    const db = new DatabaseSync(dbPath, { timeout: 5000 });
-    db.exec('PRAGMA busy_timeout = 5000;');
-    execWithBusyRetry(db, 'PRAGMA journal_mode = WAL;', { ignoreBusy: true });
-    db.exec('PRAGMA synchronous = NORMAL;');
-    db.exec('PRAGMA wal_autocheckpoint = 1000;');
-    db.exec('PRAGMA foreign_keys = ON;');
-    initSchemaWithBackup(db, dbPath, {
-      beforePostMigrationIndexes: dedupePeerBindings
-    });
-    if (options.migrateRegistered !== false) migrateRegisteredProjectDbs(ctx);
-    return db;
+    const db = new DatabaseSync(dbPath, { timeout: existingSchema ? 0 : 5000 });
+    try {
+      if (existingSchema) {
+        // Shutdown may abandon advisory detachment when another writer owns
+        // the DB. Never migrate, change journal mode, or retry while exiting.
+        db.exec('PRAGMA busy_timeout = 0; PRAGMA foreign_keys = ON;');
+        if (readSchemaVersion(db) !== DB_SCHEMA_VERSION) {
+          throw new CliError('DB_SCHEMA_NOT_CURRENT', 'Shutdown requires an existing current database schema');
+        }
+        return db;
+      }
+      db.exec('PRAGMA busy_timeout = 5000;');
+      execWithBusyRetry(db, 'PRAGMA journal_mode = WAL;', { ignoreBusy: true });
+      db.exec('PRAGMA synchronous = NORMAL;');
+      db.exec('PRAGMA wal_autocheckpoint = 1000;');
+      db.exec('PRAGMA foreign_keys = ON;');
+      initSchemaWithBackup(db, dbPath, {
+        beforePostMigrationIndexes: dedupePeerBindings
+      });
+      if (options.migrateRegistered !== false) migrateRegisteredProjectDbs(ctx);
+      return db;
+    } catch (error) {
+      try { db.close(); } catch {}
+      throw error;
+    }
   }
 
   function connectReadOnly(ctx) {
+    if (ctx.initialRootIdentity) assertSelectedCwdSnapshot(ctx.initialRootIdentity);
     const managed = managedDatabase(ctx);
     const dbPath = managed
       ? resolveProjectDatabase({ root: ctx.root, db: ctx.dbPath, createStateDir: false }).db