@logicseek/hello-cc 1.1.0-rc.8 → 1.1.0

package/lib/web/context-files.mjs

@@ -1,23 +1,86 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import process from 'node:process';
 import { CliError } from '../shared/errors.mjs';
+import { captureSelectedCwdIdentity } from '../process/selected-cwd-identity.mjs';
+import { privateComponent, PROJECT_PRIVATE_COMPONENT_WORKER_SOURCE,
+  runPinnedDirectoryWorker } from './project-files.mjs';
 
-const ignored = new Set(['.git', 'node_modules', '.hcc', '.hello-cc', '.codex', '.claude', '.dsh', '.ssh', '.aws', 'dist', 'build', 'coverage', '.next']);
-const ignoredName = name => ignored.has(name) || name === '.env' || name.startsWith('.env.');
+const contextIgnored = new Set(['.git', 'node_modules', '.hcc', '.hello-cc', '.codex', '.claude', '.dsh', '.ssh', '.aws', 'dist', 'build', 'coverage', '.next']);
 
-function assertBoundRoot(rootIdentity, stat = null) {
+function changed() {
+  return new CliError('PROJECT_PATH_CHANGED', 'Selected project directory changed while listing files');
+}
+
+function assertBoundRoot(rootIdentity) {
   if (!rootIdentity) return;
   rootIdentity.assertUnchanged();
-  if (stat && (rootIdentity.identity.dev !== stat.dev.toString() ||
-      rootIdentity.identity.ino !== stat.ino.toString() ||
-      rootIdentity.identity.birthtimeNs !== (stat.birthtimeNs?.toString() || null))) {
-    throw new CliError('PROJECT_PATH_CHANGED', 'Selected project directory changed; select its current location again');
+}
+
+function sameDirectory(left, right) {
+  return left.isDirectory() && right.isDirectory() && left.dev === right.dev &&
+    left.ino === right.ino && left.mode === right.mode && left.size === right.size &&
+    left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+
+// Windows cannot use the POSIX pinned helper, so keep the existing read-only
+// traversal there. Its transient ancestor-replacement risk is not closed here.
+async function listContextFilesByPath(root, query, { limit, maxEntries, timeBudgetMs, now, rootIdentity }) {
+  assertBoundRoot(rootIdentity);
+  const base = await fs.realpath(root), pending = [''], paths = [], needle = query.toLocaleLowerCase();
+  const directorySnapshots = [];
+  if (rootIdentity) {
+    const parent = path.dirname(base);
+    directorySnapshots.push({ directory: parent, stat: await fs.lstat(parent, { bigint: true }) });
+    const initial = await fs.lstat(base, { bigint: true });
+    assertBoundRoot(rootIdentity);
+    if (rootIdentity.identity.dev !== initial.dev.toString() ||
+        rootIdentity.identity.ino !== initial.ino.toString() ||
+        rootIdentity.identity.birthtimeNs !== (initial.birthtimeNs?.toString() || null)) throw changed();
+    directorySnapshots.push({ directory: base, stat: initial });
   }
+  const exact = await exactContextFile(base, query, rootIdentity);
+  if (exact) paths.push(exact);
+  let seen = 0, truncated = false;
+  const deadline = now() + timeBudgetMs;
+  outer: while (pending.length) {
+    if (now() >= deadline || seen >= maxEntries || paths.length >= limit) { truncated = true; break; }
+    assertBoundRoot(rootIdentity);
+    const relative = pending.shift(), directory = path.join(base, relative);
+    try {
+      const before = await fs.lstat(directory, { bigint: true });
+      if (before.isSymbolicLink() || !before.isDirectory()) continue;
+      if (rootIdentity) directorySnapshots.push({ directory, stat: before });
+      const resolved = await fs.realpath(directory), fromRoot = path.relative(base, resolved);
+      if (fromRoot === '..' || fromRoot.startsWith('..' + path.sep) || path.isAbsolute(fromRoot)) continue;
+      const handle = await fs.opendir(directory);
+      for await (const item of handle) {
+        seen++;
+        if (seen > maxEntries || now() >= deadline) { truncated = true; break outer; }
+        if (item.isSymbolicLink() || contextIgnored.has(item.name) || privateComponent(item.name) ||
+            /[\\:\x00-\x1f\x7f]/.test(item.name)) continue;
+        const name = relative ? relative + '/' + item.name : item.name;
+        if (item.isDirectory()) pending.push(name);
+        else if (item.isFile() && name !== exact && name.toLocaleLowerCase().includes(needle)) {
+          paths.push(name);
+          if (paths.length >= limit) { truncated = true; break outer; }
+        }
+      }
+      if (rootIdentity && !sameDirectory(before, await fs.lstat(directory, { bigint: true }))) throw changed();
+    } catch (error) { if (!['ENOENT', 'ENOTDIR', 'EACCES', 'EPERM'].includes(error.code)) throw error; }
+  }
+  assertBoundRoot(rootIdentity);
+  if (rootIdentity) {
+    for (const { directory, stat } of directorySnapshots) {
+      if (!sameDirectory(stat, await fs.lstat(directory, { bigint: true }))) throw changed();
+    }
+  }
+  return { paths: paths.sort(), truncated };
 }
 
 async function exactContextFile(base, query, rootIdentity) {
   const parts = query.split('/');
-  if (!query || parts.some(part => !part || part === '.' || ignoredName(part))) return null;
+  if (!query || parts.some(part => !part || part === '.' || contextIgnored.has(part) || privateComponent(part))) return null;
   let directory = base;
   try {
     for (let index = 0; index < parts.length; index++) {
@@ -26,7 +89,7 @@ async function exactContextFile(base, query, rootIdentity) {
       if (stat.isSymbolicLink() || (index < parts.length - 1 ? !stat.isDirectory() : !stat.isFile())) return null;
       const resolved = await fs.realpath(target), relative = path.relative(base, resolved);
       if (relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative) ||
-          relative.split(path.sep).some(ignoredName)) return null;
+          relative.split(path.sep).some(part => contextIgnored.has(part) || privateComponent(part))) return null;
       // Recheck the named entry after resolving it and discard any observed
       // link or entry replacement before offering the filename.
       const confirmed = await fs.lstat(target);
@@ -38,6 +101,103 @@ async function exactContextFile(base, query, rootIdentity) {
   return null;
 }
 
+function contextListWorker() {
+  const fs = require('node:fs');
+  const { query, limit, maxEntries, timeBudgetMs } = JSON.parse(process.argv[1]);
+  const deadline = Date.now() + timeBudgetMs;
+  const root = fs.statSync('.', { bigint: true });
+  const same = (left, right) => left.isDirectory() && right.isDirectory() &&
+    left.dev === right.dev && left.ino === right.ino && left.birthtimeNs === right.birthtimeNs;
+  const skippable = new Set(['ENOENT', 'ENOTDIR', 'EACCES', 'EPERM', 'ELOOP']);
+  const changed = () => { const error = new Error('Directory identity changed'); error.code = 'PROJECT_PATH_CHANGED'; return error; };
+
+  function leave(held) {
+    for (let index = held.length - 1; index >= 0; index--) {
+      process.chdir('..');
+      const current = fs.statSync('.', { bigint: true });
+      const expected = index ? held[index - 1].stat : root;
+      fs.closeSync(held[index].fd);
+      if (!same(current, expected)) throw changed();
+    }
+  }
+
+  function enter(relative) {
+    const held = [];
+    for (const part of relative ? relative.split('/') : []) {
+      let fd;
+      try { fd = fs.openSync(part, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW); }
+      catch (error) {
+        leave(held);
+        if (skippable.has(error.code)) return null;
+        throw error;
+      }
+      let stat;
+      try { stat = fs.fstatSync(fd, { bigint: true }); }
+      catch (error) { fs.closeSync(fd); leave(held); throw error; }
+      if (!stat.isDirectory()) { fs.closeSync(fd); leave(held); return null; }
+      try { process.chdir(part); }
+      catch (error) {
+        fs.closeSync(fd); leave(held);
+        if (skippable.has(error.code)) return null;
+        throw error;
+      }
+      // A rename between no-follow open and chdir must not let us inspect B.
+      if (!same(stat, fs.statSync('.', { bigint: true }))) throw changed();
+      held.push({ fd, stat });
+    }
+    return held;
+  }
+
+  function exactPath() {
+    const parts = query.split('/');
+    if (!query || parts.some(part => !part || part === '.' || contextIgnored.has(part) || privateComponent(part))) return null;
+    const held = enter(parts.slice(0, -1).join('/'));
+    if (held === null) return null;
+    try {
+      const entry = fs.lstatSync(parts.at(-1));
+      return entry.isFile() && !entry.isSymbolicLink() ? query : null;
+    } catch (error) { if (skippable.has(error.code)) return null; throw error; }
+    finally { leave(held); }
+  }
+
+  const pending = [''], paths = [], needle = query.toLocaleLowerCase();
+  const exact = exactPath();
+  if (exact) paths.push(exact);
+  let seen = 0, truncated = false, stop = false;
+  try {
+    while (pending.length && !stop) {
+      if (Date.now() >= deadline || seen >= maxEntries || paths.length >= limit) { truncated = true; break; }
+      const relative = pending.shift(), held = enter(relative);
+      if (held === null) continue;
+      let directory;
+      try {
+        directory = fs.opendirSync('.');
+        for (let item; (item = directory.readSync()) !== null;) {
+          seen++;
+          if (seen > maxEntries || Date.now() >= deadline) { truncated = true; stop = true; break; }
+          if (item.isSymbolicLink() || contextIgnored.has(item.name) || privateComponent(item.name) ||
+              /[\\:\x00-\x1f\x7f]/.test(item.name)) continue;
+          const name = relative ? relative + '/' + item.name : item.name;
+          if (item.isDirectory()) pending.push(name);
+          else if (item.isFile() && name !== exact && name.toLocaleLowerCase().includes(needle)) {
+            paths.push(name);
+            if (paths.length >= limit) { truncated = true; stop = true; break; }
+          }
+        }
+      } catch (error) { if (!skippable.has(error.code)) throw error; }
+      finally { directory?.closeSync(); leave(held); }
+    }
+    process.stdout.write(JSON.stringify({ paths, truncated, exact }));
+  } catch (error) {
+    process.stderr.write('HCC_DIRECTORY_WORKER_FAILED:' + (error.code || 'PROJECT_PATH_CHANGED') + '\n');
+    process.exitCode = 1;
+  }
+}
+
+const CONTEXT_LIST_WORKER_SOURCE = PROJECT_PRIVATE_COMPONENT_WORKER_SOURCE +
+  `const contextIgnored = new Set(${JSON.stringify([...contextIgnored])});\n` +
+  `(${contextListWorker.toString()})()`;
+
 /** List bounded project-relative filenames only. Never open or upload their contents. */
 export async function listContextFiles(root, query = '', { limit = 80, maxEntries = 10000, timeBudgetMs = 150, now = Date.now, rootIdentity = null } = {}) {
   if (typeof query !== 'string' || query.length > 256 || /[\0\r\n]/.test(query) || path.isAbsolute(query) || query.includes('\\') || query.split('/').includes('..')) {
@@ -46,37 +206,30 @@ export async function listContextFiles(root, query = '', { limit = 80, maxEntrie
   if (!Number.isSafeInteger(limit) || limit < 1 || !Number.isSafeInteger(maxEntries) || maxEntries < 1 || !Number.isFinite(timeBudgetMs) || timeBudgetMs < 0 || typeof now !== 'function') {
     throw new TypeError('Invalid context file listing budget');
   }
-  assertBoundRoot(rootIdentity);
-  const base = await fs.realpath(root), pending = [''], paths = [], needle = query.toLocaleLowerCase();
-  if (rootIdentity) assertBoundRoot(rootIdentity, await fs.lstat(base, { bigint: true }));
-  // An explicit filename remains usable even if an unrelated directory read
-  // consumes the scan budget. Keep the bounded substring scan for other hits.
-  const exact = await exactContextFile(base, query, rootIdentity);
-  if (exact) paths.push(exact);
-  let seen = 0, truncated = false;
-  const deadline = now() + timeBudgetMs;
-  outer: while (pending.length) {
-    if (now() >= deadline || seen >= maxEntries || paths.length >= limit) { truncated = true; break; }
-    assertBoundRoot(rootIdentity);
-    const relative = pending.shift(), directory = path.join(base, relative);
+  if (process.platform === 'win32') return listContextFilesByPath(root, query,
+    { limit, maxEntries, timeBudgetMs, now, rootIdentity });
+  const ownedIdentity = rootIdentity ? null : captureSelectedCwdIdentity(root);
+  const identity = rootIdentity || ownedIdentity;
+  try {
+    assertBoundRoot(identity);
+    let result;
     try {
-      if ((await fs.lstat(directory)).isSymbolicLink()) continue;
-      const resolved = await fs.realpath(directory), fromRoot = path.relative(base, resolved);
-      if (fromRoot === '..' || fromRoot.startsWith('..' + path.sep) || path.isAbsolute(fromRoot)) continue;
-      const handle = await fs.opendir(directory);
-      for await (const item of handle) {
-        seen++;
-        if (seen > maxEntries || now() >= deadline) { truncated = true; break outer; }
-        if (item.isSymbolicLink() || ignoredName(item.name)) continue;
-        const name = relative ? relative + '/' + item.name : item.name;
-        if (item.isDirectory()) pending.push(name);
-        else if (item.isFile() && name.toLocaleLowerCase().includes(needle) && name !== exact) {
-          paths.push(name);
-          if (paths.length >= limit) { truncated = true; break outer; }
-        }
-      }
-    } catch (error) { if (!['ENOENT', 'ENOTDIR', 'EACCES', 'EPERM'].includes(error.code)) throw error; }
-  }
-  assertBoundRoot(rootIdentity);
-  return { paths: paths.sort(), truncated };
+      result = await runPinnedDirectoryWorker(identity.canonical, identity,
+        CONTEXT_LIST_WORKER_SOURCE, { query, limit, maxEntries, timeBudgetMs });
+    } catch (error) {
+      if (['PROJECT_FILE_CHANGED', 'PROJECT_PATH_CHANGED'].includes(error.code)) throw changed();
+      throw error;
+    }
+    assertBoundRoot(identity);
+    const paths = [];
+    // Apply the listing budget inside the pinned worker; bootstrap latency
+    // must not discard names that the bounded scan already found.
+    const deadline = now() + timeBudgetMs;
+    let truncated = result.truncated;
+    for (const file of result.paths) {
+      if (file !== result.exact && now() >= deadline) { truncated = true; break; }
+      paths.push(file);
+    }
+    return { paths: paths.sort(), truncated };
+  } finally { ownedIdentity?.release(); }
 }

package/lib/web/http-routes.mjs

@@ -13,8 +13,7 @@ import { createAgentDefaults } from './agent-defaults.mjs';
 import { listProjectFiles, previewProjectFile, inspectProjectFileStatus, projectFileErrorStatus } from './project-files.mjs';
 import { saveProjectFile, uploadProjectFile } from './project-file-write.mjs';
 import { projectRecord } from '../runtime/projects.mjs';
-import { projectDbPath } from '../runtime/paths.mjs';
-import { resolveProjectDatabase } from '../runtime/project-path.mjs';
+import { prevalidateProjectDatabaseLocation } from '../runtime/project-path.mjs';
 import { writeRuntime } from '../runtime/state.mjs';
 import { normalizeStateResources } from '../ui/state-render.mjs';
 import { requestUrl, runtimeBaseUrl } from '../web/runtime.mjs';
@@ -31,7 +30,7 @@ import { scheduleResponseShutdown } from './shutdown-response.mjs';
 // even when the dispatcher ultimately returns 404. Null means the matching
 // dispatcher branch handles its own method error.
 const projectApiPaths = new Map([
-  ['/api/agent-defaults', null],
+  ['/api/agent-defaults', ['GET', 'PUT']],
   ['/api/files/tree', ['GET']], ['/api/files/preview', ['GET']],
   ['/api/files/status', ['GET']], ['/api/files/content', ['PUT']], ['/api/files/upload', ['POST']],
   ['/api/context/files', ['GET']],
@@ -41,13 +40,18 @@ const projectApiPaths = new Map([
   ['/api/sessions', ['GET', 'POST']], ['/api/sessions/attach', ['POST']],
   ['/api/native/history', ['GET']], ['/api/codex/threads', ['GET']]
 ]);
+const peerReadActions = new Set(['status', 'state', 'inbox']);
+const peerWriteActions = new Set([
+  'task-next', 'task-takeover', 'lock-acquire', 'lock-release', 'heartbeat', 'register'
+]);
 const projectApiPatterns = [
-  [/^\/api\/peers\/[^/]+\/actions\/[^/]+$/, null],
-  [/^\/api\/native\/history\/[^/]+(?:\/resume)?$/, null],
+  [/^\/api\/native\/history\/[^/]+$/, ['GET']],
+  [/^\/api\/native\/history\/[^/]+\/resume$/, ['POST']],
   [/^\/api\/sessions\/[^/]+\/native\/([^/]+)$/, null, {
     GET: ['state', 'account'], POST: ['send', 'interrupt', 'close', 'respond']
   }],
-  [/^\/api\/codex\/threads\/[^/]+(?:\/fork)?$/, null],
+  [/^\/api\/codex\/threads\/[^/]+$/, ['GET']],
+  [/^\/api\/codex\/threads\/[^/]+\/fork$/, ['POST']],
   [/^\/api\/sessions\/[^/]+\/results$/, ['GET', 'POST']],
   [/^\/api\/sessions\/[^/]+\/codex\/([^/]+)$/, null, {
     GET: ['state', 'read', 'account'], POST: ['turn', 'steer', 'interrupt', 'approve']
@@ -56,11 +60,25 @@ const projectApiPatterns = [
   [/^\/api\/detected\/[^/]+\/(?:msg|stop|restart)$/, ['POST']]
 ];
 
+function peerApiActionKind(pathname) {
+  const match = pathname.match(/^\/api\/peers\/[^/]+\/actions\/([^/]+)$/);
+  if (!match) return null;
+  try {
+    const action = decodeURIComponent(match[1]).replace(/_/g, '-');
+    if (peerReadActions.has(action)) return 'read';
+    if (peerWriteActions.has(action)) return 'write';
+  } catch {}
+  return 'unknown';
+}
+
 function projectApiRouteExists(method, pathname) {
   if (projectApiPaths.has(pathname)) {
     const methods = projectApiPaths.get(pathname);
     return methods === null || methods.includes(method);
   }
+  const peerAction = peerApiActionKind(pathname);
+  if (peerAction !== null) return peerAction === 'read' ? method === 'GET' :
+    peerAction === 'write' && method === 'POST';
   return projectApiPatterns.some(([pattern, methods, actions]) => {
     const match = pathname.match(pattern);
     if (!match || methods !== null && !methods.includes(method)) return false;
@@ -240,10 +258,23 @@ export function createHttpRoutes(deps) {
         sendJson(res, 404, { ok: false, error: { code: 'NOT_FOUND', message: 'Route not found' } });
         return;
       }
-      if (!projectApiRouteExists(req.method, url.pathname)) {
+      // Dynamic IDs can be malformed even when the route shape and action
+      // match. Validate the whole pathname before resolving a project.
+      let pathEncodingValid = true;
+      try { decodeURIComponent(url.pathname); } catch { pathEncodingValid = false; }
+      if (!pathEncodingValid || !projectApiRouteExists(req.method, url.pathname)) {
+        const peerAction = pathEncodingValid ? peerApiActionKind(url.pathname) : null;
+        if (peerAction === 'read' || peerAction === 'write') {
+          sendJson(res, 405, { ok: false, error: { code: 'METHOD_NOT_ALLOWED',
+            message: peerAction === 'read' ? 'Use GET for read-only peer actions' : 'Use POST for mutating peer actions' } });
+          return;
+        }
+        if (url.pathname === '/api/agent-defaults') {
+          throw new CliError('BAD_REQUEST', 'Agent defaults support GET and PUT only');
+        }
         // The legacy Codex account-control POSTs have a stable BAD_REQUEST
         // contract. Reject them here without resolving an arbitrary project.
-        if (legacyForbiddenCodexAction(req.method, url.pathname)) {
+        if (pathEncodingValid && legacyForbiddenCodexAction(req.method, url.pathname)) {
           throw new CliError('BAD_REQUEST', 'Unsupported Codex action');
         }
         sendJson(res, 404, { ok: false, error: { code: 'NOT_FOUND', message: 'Route not found' } });
@@ -259,11 +290,10 @@ export function createHttpRoutes(deps) {
       // Reject an outside DB before resolving the body-selected root, which
       // can create its managed state directory and record registry activity.
       if (projectInput?.db) {
-        resolveProjectDatabase({
+        prevalidateProjectDatabaseLocation({
           root: projectInput.root || url.searchParams.get('root') ||
             url.searchParams.get('project') || req.headers['x-hcc-root'] || ctx.root,
-          db: projectInput.db,
-          createStateDir: false
+          db: projectInput.db
         });
       }
       const projectUrl = projectInput?.root && !url.searchParams.has('root') &&
@@ -325,7 +355,8 @@ export function createHttpRoutes(deps) {
         const requestedRoot = input.root || reqCtx.root;
         const selected = resolveWebProjectContext(
           requestedRoot,
-          input.db || projectDbPath(requestedRoot)
+          input.db || null,
+          { explicitSelection: true }
         );
         let projectCtx;
         try {

package/lib/web/native-sessions.mjs

@@ -11,6 +11,7 @@ import { ensureNativeRuntime } from '../runtime/native/launcher.mjs';
 import { readNativeHistory, readNativeWorkerHistory } from '../runtime/native/history.mjs';
 import { parseNativeCwdIdentity } from '../runtime/native/store.mjs';
 import { captureSelectedCwdSnapshot, sameSelectedCwdIdentity } from '../process/selected-cwd-identity.mjs';
+import { assertPinnedSessionLaunchAllowed } from '../process/pinned-cwd.mjs';
 import { createAgentDefaults } from './agent-defaults.mjs';
 
 const PROVIDERS = new Set(['codex', 'claude', 'dsh']);
@@ -148,6 +149,7 @@ export function createNativeSessions({ sessions, sessionKey, connectWebProject,
         typeof input.sessionId !== 'string' || !input.sessionId || input.sessionId.length > 512) {
       throw new CliError('BAD_REQUEST', 'Restore requires confirmed:true and the saved owner and sessionId');
     }
+    assertPinnedSessionLaunchAllowed();
     const key = sessionKey(ctx, peer);
     if (stopped) throw new CliError('NATIVE_WEB_DISCONNECTED', 'Web is stopping');
     if (creating.has(key)) throw new CliError('NATIVE_WORKER_EXISTS', 'This worker is already being opened', { peer });
@@ -206,6 +208,7 @@ export function createNativeSessions({ sessions, sessionKey, connectWebProject,
         input.transport !== 'native' || (input.kind !== undefined && !PROVIDERS.has(input.kind))) {
       throw new CliError('BAD_REQUEST', 'Native creation accepts only transport, kind, id, cwd and model; use provider codex, claude or dsh');
     }
+    assertPinnedSessionLaunchAllowed();
     const ctx = input.projectCtx;
     // Resolve before asynchronous daemon startup; explicit null clears a saved model.
     input = resolveNativeDefaults(ctx, input);

package/lib/web/project-contexts.mjs

@@ -8,7 +8,8 @@ import path from 'node:path';
 import WebSocket from 'ws';
 import { CliError } from '../shared/errors.mjs';
 import { contextForProject, projectDbPath } from '../runtime/paths.mjs';
-import { resolveProjectDatabase } from '../runtime/project-path.mjs';
+import { prevalidateProjectDatabaseLocation, resolveProjectDatabase } from '../runtime/project-path.mjs';
+import { provisionPrivateProjectGeneration } from '../runtime/private-state.mjs';
 import { assertSelectedCwdSnapshot, captureSelectedCwdIdentity, sameSelectedCwdIdentity } from '../process/selected-cwd-identity.mjs';
 import {
   projectRecord,
@@ -33,6 +34,7 @@ export function createProjectContexts(deps) {
   } = deps;
 
   const projectContexts = new Map();
+  const retiredProjectContexts = new Set();
   const MAX_IDLE_PROJECT_DESCRIPTORS = 32;
 
   function changedProject() {
@@ -79,6 +81,11 @@ export function createProjectContexts(deps) {
       retainedIdle += 1;
       if (retainedIdle > maxIdle) binding.dropDescriptor();
     }
+    for (const project of retiredProjectContexts) {
+      if (hasLiveManagedSession(project.rootIdentity)) continue;
+      project.rootIdentity?.release();
+      retiredProjectContexts.delete(project);
+    }
   }
 
   function retainProjectContextDescriptor(projectCtx) {
@@ -156,7 +163,10 @@ export function createProjectContexts(deps) {
         dropIdleProjectContextDescriptors(retained);
         return existing;
       }
-      if (previous && previous !== retained) previous.release();
+      if (previous && previous !== retained) {
+        if (hasLiveManagedSession(previous)) retiredProjectContexts.add(existing);
+        else previous.release();
+      }
       projectContexts.set(normalized.root, normalized);
       dropIdleProjectContextDescriptors(retained);
       return normalized;
@@ -185,7 +195,7 @@ export function createProjectContexts(deps) {
     return rows;
   }
 
-  function resolveWebProjectContext(root, db) {
+  function resolveWebProjectContext(root, db, { explicitSelection = false } = {}) {
     const selected = captureSelectedCwdIdentity(root);
     let binding = selected;
     try {
@@ -194,6 +204,16 @@ export function createProjectContexts(deps) {
       // pathname. The alias must still be unchanged throughout selection.
       if (selected.requested !== selected.canonical) binding = captureSelectedCwdIdentity(selected.canonical);
       selected.assertUnchanged();
+      if (db) {
+        prevalidateProjectDatabaseLocation({ root: selected.requested, db });
+        selected.assertUnchanged();
+        binding.assertUnchanged();
+      }
+      if (explicitSelection) {
+        provisionPrivateProjectGeneration(binding.canonical, { expectedIdentity: binding });
+        selected.assertUnchanged();
+        binding.assertUnchanged();
+      }
       // Preserve explicit legacy DB spellings under a selected alias while
       // resolving state against the captured canonical directory only.
       const selectedLegacy = path.join(selected.requested, '.hello-cc');
@@ -202,7 +222,7 @@ export function createProjectContexts(deps) {
         !relativeDb.startsWith(`..${path.sep}`) && !path.isAbsolute(relativeDb);
       const stableDb = underSelectedLegacy
         ? path.join(binding.canonical, '.hello-cc', relativeDb)
-        : db;
+        : db || projectDbPath(binding.canonical);
       const first = resolveProjectDatabase({ root: binding.canonical, db: stableDb, createStateDir: true });
       selected.assertUnchanged();
       binding.assertUnchanged();
@@ -281,7 +301,7 @@ export function createProjectContexts(deps) {
         }
         carried = captureSelectedCwdIdentity(requestedRoot, expected);
       }
-      resolved = resolveWebProjectContext(requestedRoot, requestedDb || projectDbPath(requestedRoot));
+      resolved = resolveWebProjectContext(requestedRoot, requestedDb, { explicitSelection });
       if (carried && !sameSelectedCwdIdentity(carried, resolved.rootIdentity)) throw changedProject();
       const remembered = rememberProject(resolved, { activity: true });
       resolved = null;
@@ -346,7 +366,9 @@ export function createProjectContexts(deps) {
 
   function releaseProjectContexts() {
     for (const project of projectContexts.values()) project.rootIdentity?.release();
+    for (const project of retiredProjectContexts) project.rootIdentity?.release();
     projectContexts.clear();
+    retiredProjectContexts.clear();
   }
 
   function knownPeerIds(projectCtx) {