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

package/lib/process/pinned-cwd.mjs

@@ -0,0 +1,302 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { CliError } from '../shared/errors.mjs';
+import { ensurePrivateGlobalSubdirectory } from '../runtime/private-state.mjs';
+import { stableProjectStateRoot } from '../runtime/project-trust.mjs';
+
+// This function is serialized into node -e. Keep it self-contained: loading a
+// script from the selected project before checking its identity would recreate
+// the directory-rebind race that this bootstrap is intended to narrow.
+function pinnedBootstrap() {
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const config = JSON.parse(process.argv[1]);
+  const identity = config.identity;
+  const changed = (stage) => {
+    process.stderr.write('HCC_PINNED_CWD_CHANGED:' + stage + '\n');
+    process.exit(stage === 'entry' ? 41 : 42);
+  };
+  const matches = (stat) => stat.isDirectory() &&
+    stat.dev.toString() === identity.dev &&
+    stat.ino.toString() === identity.ino &&
+    (identity.birthtimeNs === null ||
+      stat.birthtimeNs?.toString() === identity.birthtimeNs);
+
+  let fd;
+  let opened;
+  try {
+    fd = fs.openSync(identity.cwd,
+      fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+    opened = fs.fstatSync(fd, { bigint: true });
+  } catch (error) {
+    if (fd !== undefined) fs.closeSync(fd);
+    if (identity.mode !== 'stat-only' || error?.code !== 'EACCES') changed('entry');
+    fd = undefined;
+    try { opened = fs.statSync(identity.cwd, { bigint: true }); }
+    catch { changed('entry'); }
+  }
+  if (!matches(opened)) changed('entry');
+  /* PINNED_TEST_AFTER_OPEN */
+  try { process.chdir(identity.cwd); }
+  catch { changed('chdir'); }
+  let current;
+  try { current = fs.statSync('.', { bigint: true }); }
+  catch { changed('chdir'); }
+  if (!matches(current) ||
+      (fd !== undefined &&
+        (current.dev !== opened.dev || current.ino !== opened.ino))) changed('chdir');
+  if (fd !== undefined) fs.closeSync(fd);
+  if (config.ack) {
+    let ackFd;
+    try {
+      ackFd = fs.openSync(config.ack.path,
+        fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | fs.constants.O_NOFOLLOW,
+        0o600);
+      const bytes = Buffer.from(config.ack.nonce);
+      let offset = 0;
+      while (offset < bytes.length) offset += fs.writeSync(ackFd, bytes, offset, bytes.length - offset);
+      fs.closeSync(ackFd);
+      ackFd = undefined;
+    } catch (error) {
+      if (ackFd !== undefined) fs.closeSync(ackFd);
+      process.stderr.write('HCC_PINNED_ACK_FAILED:' + (error?.code || 'unknown') + '\n');
+      process.exit(43);
+    }
+  }
+  /* PINNED_TEST_BEFORE_EXEC */
+
+  const env = { ...process.env };
+  if (config.nodeOptions !== null) env.NODE_OPTIONS = config.nodeOptions;
+  try { env.PWD = process.cwd(); } catch { changed('chdir'); }
+  const command = config.command;
+  const fromPinnedCwd = (candidate) => {
+    if (!path.isAbsolute(candidate)) return candidate;
+    for (const root of [identity.cwd, identity.requestedCwd]) {
+      const relative = path.relative(root, candidate);
+      if (relative === '') return '.';
+      if (relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative)) {
+        return '.' + path.sep + relative;
+      }
+    }
+    return candidate;
+  };
+  let executable;
+  if (command.includes('/')) {
+    executable = fromPinnedCwd(command);
+  } else {
+    const search = env.PATH === undefined ? '/usr/bin:/bin' : env.PATH;
+    for (const entry of search.split(path.delimiter)) {
+      const candidate = fromPinnedCwd(path.join(entry || '.', command));
+      try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        if (fs.statSync(candidate).isFile()) { executable = candidate; break; }
+      } catch {}
+    }
+  }
+  if (!executable || typeof process.execve !== 'function') {
+    process.stderr.write('HCC_PINNED_EXEC_FAILED:unavailable\n');
+    process.exit(127);
+  }
+  let execArgs = [command, ...config.args];
+  // Node 24's experimental execve aborts the process (rather than throwing)
+  // for ENOEXEC. Handle plain executable text without a shebang before execve:
+  // Linux ordinary spawn runs it via /bin/sh, whereas macOS rejects it.
+  try {
+    const probeFd = fs.openSync(executable, fs.constants.O_RDONLY);
+    try {
+      const prefix = Buffer.alloc(128);
+      const length = fs.readSync(probeFd, prefix, 0, prefix.length, 0);
+      const plainText = length > 0 && prefix.subarray(0, length).every(
+        byte => (byte >= 0x20 && byte <= 0x7e) || byte === 0x09 || byte === 0x0a || byte === 0x0d);
+      if (plainText && !(prefix[0] === 0x23 && prefix[1] === 0x21)) {
+        if (process.platform === 'linux') {
+          // Linux's ordinary Node spawn uses the POSIX shell fallback for an
+          // executable text file without a shebang. Preserve that behavior
+          // without asking Node's aborting execve to handle ENOEXEC.
+          try { fs.accessSync(executable, fs.constants.X_OK); }
+          catch {
+            process.stderr.write('HCC_PINNED_EXEC_FAILED:EACCES\n');
+            process.exit(127);
+          }
+          execArgs = ['sh', executable, ...config.args];
+          executable = '/bin/sh';
+        } else {
+          process.stderr.write('HCC_PINNED_EXEC_FAILED:ENOEXEC\n');
+          process.exit(127);
+        }
+      }
+    } finally { fs.closeSync(probeFd); }
+  } catch (error) {
+    if (error?.code !== 'EACCES') {
+      process.stderr.write('HCC_PINNED_EXEC_FAILED:' + (error?.code || 'unknown') + '\n');
+      process.exit(127);
+    }
+  }
+  try { process.execve(executable, execArgs, env); }
+  catch (error) {
+    process.stderr.write('HCC_PINNED_EXEC_FAILED:' + (error?.code || 'unknown') + '\n');
+    process.exit(127);
+  }
+}
+
+export const PINNED_CWD_BOOTSTRAP_SOURCE = '(' + pinnedBootstrap.toString() + ')()';
+
+function sameIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino &&
+    left.birthtimeNs === right.birthtimeNs;
+}
+
+function directoryIdentity(stat, cwd, requestedCwd, mode) {
+  return {
+    cwd,
+    requestedCwd,
+    dev: stat.dev.toString(),
+    ino: stat.ino.toString(),
+    birthtimeNs: stat.birthtimeNs?.toString() || null,
+    mode
+  };
+}
+
+function bootstrapDirectory(override) {
+  if (override !== undefined) {
+    const trusted = stableProjectStateRoot(override);
+    if (!trusted) throw new CliError('PROJECT_PATH_FORBIDDEN', 'Bootstrap cwd must have stable trusted ancestry');
+    return trusted;
+  }
+  return ensurePrivateGlobalSubdirectory('launches');
+}
+
+function acknowledgementState(ack) {
+  if (!ack) return null;
+  let fd;
+  try {
+    fd = fs.openSync(ack.path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || (stat.mode & 0o077) !== 0 || stat.size !== ack.nonce.length) return null;
+    if (fs.readFileSync(fd, 'utf8') !== ack.nonce) return null;
+    return { dev: stat.dev, ino: stat.ino };
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+function removeOwnedAcknowledgement(ack) {
+  const owned = acknowledgementState(ack);
+  if (!owned) return;
+  try {
+    const current = fs.lstatSync(ack.path);
+    if (current.dev === owned.dev && current.ino === owned.ino) fs.unlinkSync(ack.path);
+  } catch {}
+}
+
+// The returned binding deliberately retains its directory FD. Call release()
+// only when the child has established its cwd or exited; retaining it while a
+// child starts prevents inode reuse from satisfying a stale dev/ino snapshot.
+export function preparePinnedCwdLaunch(cwd, command, args = [], options = {}) {
+  if (process.platform === 'win32') {
+    throw new CliError('PINNED_CWD_UNAVAILABLE', 'Pinned cwd launch requires POSIX directory identity');
+  }
+  if (typeof command !== 'string' || !command || !Array.isArray(args) ||
+      args.some(arg => typeof arg !== 'string')) {
+    throw new CliError('BAD_ARGS', 'Pinned launch requires a command and string arguments');
+  }
+  const requested = path.resolve(cwd);
+  let canonical;
+  try { canonical = fs.realpathSync.native(requested); }
+  catch { throw new CliError('PROJECT_PATH_FORBIDDEN', 'Selected working directory is unavailable'); }
+
+  let fd;
+  let stat;
+  let mode = 'descriptor';
+  try {
+    fd = fs.openSync(canonical,
+      fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+    stat = fs.fstatSync(fd, { bigint: true });
+  } catch (error) {
+    if (fd !== undefined) fs.closeSync(fd);
+    fd = undefined;
+    if (error?.code !== 'EACCES') {
+      throw new CliError('PROJECT_PATH_FORBIDDEN', 'Selected working directory cannot be pinned');
+    }
+    mode = 'stat-only';
+    try { stat = fs.statSync(canonical, { bigint: true }); }
+    catch { throw new CliError('PROJECT_PATH_FORBIDDEN', 'Selected working directory is unavailable'); }
+  }
+  try {
+    const current = fs.statSync(requested, { bigint: true });
+    if (!stat.isDirectory() || !sameIdentity(stat, current)) {
+      throw new CliError('PROJECT_PATH_FORBIDDEN', 'Selected working directory changed during capture');
+    }
+    const env = { ...(options.env || process.env) };
+    const nodeOptions = Object.hasOwn(env, 'NODE_OPTIONS') ? String(env.NODE_OPTIONS) : null;
+    delete env.NODE_OPTIONS;
+    const identity = directoryIdentity(stat, canonical, requested, mode);
+    if (options.expectedIdentity &&
+        (identity.cwd !== options.expectedIdentity.canonical ||
+          identity.dev !== options.expectedIdentity.identity?.dev ||
+          identity.ino !== options.expectedIdentity.identity?.ino ||
+          identity.birthtimeNs !== options.expectedIdentity.identity?.birthtimeNs)) {
+      throw new CliError('PROJECT_PATH_CHANGED', 'Selected working directory changed before launch');
+    }
+    const trustedCwd = bootstrapDirectory(options.bootstrapCwd);
+    const ack = options.acknowledge === true ? {
+      path: path.join(trustedCwd, 'ack-' + randomBytes(16).toString('hex')),
+      nonce: randomBytes(32).toString('hex')
+    } : null;
+    const config = { identity, command, args, nodeOptions, ack };
+    return {
+      command: process.execPath,
+      args: ['-e', PINNED_CWD_BOOTSTRAP_SOURCE, JSON.stringify(config)],
+      cwd: trustedCwd,
+      env,
+      identity,
+      ackPath: ack?.path || null,
+      acknowledged() { return acknowledgementState(ack) !== null; },
+      release() {
+        if (fd !== undefined) { fs.closeSync(fd); fd = undefined; }
+        removeOwnedAcknowledgement(ack);
+      }
+    };
+  } catch (error) {
+    if (fd !== undefined) fs.closeSync(fd);
+    throw error;
+  }
+}
+
+export function spawnPinnedCwdProcess(command, args, options = {}, spawnProcess = spawn) {
+  const binding = preparePinnedCwdLaunch(options.cwd, command, args,
+    { env: options.env, expectedIdentity: options.expectedIdentity });
+  const { cwd, env, expectedIdentity, ...rest } = options;
+  try {
+    const child = spawnProcess(binding.command, binding.args, {
+      ...rest, cwd: binding.cwd, env: binding.env
+    });
+    child.once('exit', binding.release);
+    child.once('error', binding.release);
+    return child;
+  } catch (error) {
+    binding.release();
+    throw error;
+  }
+}
+
+export function spawnPinnedCwdPty(pty, command, args, options = {}) {
+  const binding = preparePinnedCwdLaunch(options.cwd, command, args,
+    { env: options.env, expectedIdentity: options.expectedIdentity });
+  const { cwd, env, expectedIdentity, ...rest } = options;
+  try {
+    const child = pty.spawn(binding.command, binding.args, {
+      ...rest, cwd: binding.cwd, env: binding.env
+    });
+    child.onExit(() => binding.release());
+    return child;
+  } catch (error) {
+    binding.release();
+    throw error;
+  }
+}

package/lib/process/pinned-guidance.mjs

@@ -0,0 +1,138 @@
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+import { CliError } from '../shared/errors.mjs';
+import { preparePinnedCwdLaunch } from './pinned-cwd.mjs';
+import { assertSelectedCwdSnapshot } from './selected-cwd-identity.mjs';
+
+// This worker only uses relative names after the bootstrap has entered the
+// selected directory inode. It cannot follow a rebound absolute project path.
+function guidanceWorker() {
+  const fs = require('node:fs');
+  const files = ['CLAUDE.md', 'AGENTS.md'];
+  const mode = process.argv[1];
+  const content = process.argv[2] || '';
+  const clause = '\n<!-- hello-cc:start -->\n\n' + content + '\n<!-- hello-cc:end -->\n';
+  const changed = [];
+  const opened = [];
+
+  function readTarget(name) {
+    let fd;
+    try { fd = fs.openSync(name, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW); }
+    catch (error) {
+      if (error?.code === 'ENOENT') return { name, fd: null, text: null };
+      throw error;
+    }
+    try {
+      const stat = fs.fstatSync(fd);
+      if (!stat.isFile() || stat.nlink !== 1) throw new Error('GUIDANCE_FILE_UNSAFE');
+      const text = fs.readFileSync(fd, 'utf8');
+      return { name, fd, text, dev: stat.dev, ino: stat.ino };
+    } catch (error) {
+      fs.closeSync(fd);
+      throw error;
+    }
+  }
+
+  function writeTarget(target, text) {
+    let fd = null;
+    try {
+      if (target.fd === null) {
+        fd = fs.openSync(target.name,
+          fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL |
+            fs.constants.O_NOFOLLOW, 0o644);
+      } else {
+        fd = fs.openSync(target.name, fs.constants.O_RDWR | fs.constants.O_NOFOLLOW);
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile() || stat.nlink !== 1 || stat.dev !== target.dev || stat.ino !== target.ino) {
+          throw new Error('GUIDANCE_FILE_CHANGED');
+        }
+      }
+      const bytes = Buffer.from(text);
+      let offset = 0;
+      while (offset < bytes.length) {
+        offset += fs.writeSync(fd, bytes, offset, bytes.length - offset, offset);
+      }
+      fs.ftruncateSync(fd, bytes.length);
+      fs.fsyncSync(fd);
+    } finally {
+      if (fd !== null) fs.closeSync(fd);
+    }
+  }
+
+  try {
+    // Inspect both targets before the first write, so a pre-existing symlink
+    // or hardlink cannot lead to a partial ordinary guidance installation.
+    for (const name of files) opened.push(readTarget(name));
+    for (const target of opened) {
+      if (mode === 'write') {
+        const updated = target.text === null ? clause.trimStart() :
+          target.text.includes('<!-- hello-cc:start -->')
+            ? target.text.replace(/<!-- hello-cc:start -->[\s\S]*?<!-- hello-cc:end -->/, clause.trim())
+            : target.text.trimEnd() + '\n' + clause;
+        if (updated !== target.text) { writeTarget(target, updated); changed.push(target.name); }
+      } else if (mode === 'remove') {
+        if (target.text === null) continue;
+        const updated = target.text
+          .replace(/\n?<!-- hello-cc:start -->[\s\S]*?<!-- hello-cc:end -->\n?/g, '\n')
+          .replace(/\n{3,}/g, '\n\n').trimEnd();
+        const result = updated ? updated + '\n' : '';
+        if (result !== target.text) { writeTarget(target, result); changed.push(target.name); }
+      } else throw new Error('GUIDANCE_MODE_INVALID');
+    }
+    process.stdout.write(JSON.stringify(changed));
+  } catch (error) {
+    process.stderr.write('HCC_GUIDANCE_FAILED:' + (error?.code || error?.message || 'unknown') + '\n');
+    process.exitCode = 1;
+  } finally {
+    for (const target of opened) if (target.fd !== null) fs.closeSync(target.fd);
+  }
+}
+
+const GUIDANCE_WORKER_SOURCE = '(' + guidanceWorker.toString() + ')()';
+
+function runPinnedGuidance(root, mode, content = '', {
+  spawnProcess = spawnSync, expectedBinding = null, expectedSnapshot = null
+} = {}) {
+  expectedBinding?.assertUnchanged();
+  if (expectedSnapshot) assertSelectedCwdSnapshot(expectedSnapshot);
+  const binding = preparePinnedCwdLaunch(root, process.execPath,
+    ['-e', GUIDANCE_WORKER_SOURCE, mode, content], {
+      // The worker needs only built-ins. Do not permit inherited Node preload
+      // hooks to run before it can operate on relative names.
+      env: { PATH: '/usr/bin:/bin', NODE_OPTIONS: '', NODE_NO_WARNINGS: '1' }
+    });
+  try {
+    const expected = expectedBinding || expectedSnapshot;
+    if (expected && (binding.identity.cwd !== expected.canonical ||
+        binding.identity.dev !== expected.identity.dev ||
+        binding.identity.ino !== expected.identity.ino ||
+        binding.identity.birthtimeNs !== expected.identity.birthtimeNs)) {
+      throw new CliError('PROJECT_PATH_CHANGED', 'Selected working directory changed before guidance update');
+    }
+    const result = spawnProcess(binding.command, binding.args, {
+      cwd: binding.cwd, env: binding.env, encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'], timeout: 10000, maxBuffer: 64 * 1024
+    });
+    if (result.error || result.status !== 0) {
+      const marker = String(result.stderr || '');
+      if (/HCC_PINNED_CWD_CHANGED:/.test(marker)) {
+        throw new CliError('PROJECT_PATH_CHANGED', 'Selected working directory changed before guidance update');
+      }
+      throw new CliError('GUIDANCE_WRITE_FAILED',
+        `Cannot ${mode} project guidance: ${result.error?.code || marker.trim() || `exit ${result.status}`}`);
+    }
+    const changed = JSON.parse(result.stdout || '[]');
+    if (!Array.isArray(changed) || changed.some(name => !['CLAUDE.md', 'AGENTS.md'].includes(name))) {
+      throw new CliError('GUIDANCE_WRITE_FAILED', 'Guidance worker returned an invalid receipt');
+    }
+    return changed.map(name => `${binding.identity.cwd}/${name}`);
+  } finally { binding.release(); }
+}
+
+export function writeProjectGuidanceFiles(root, content, options = {}) {
+  return runPinnedGuidance(root, 'write', content, options);
+}
+
+export function removeProjectGuidanceFiles(root, options = {}) {
+  return runPinnedGuidance(root, 'remove', '', options);
+}

package/lib/process/pinned-project-state.mjs

@@ -0,0 +1,105 @@
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+import { CliError } from '../shared/errors.mjs';
+import { preparePinnedCwdLaunch } from './pinned-cwd.mjs';
+
+// The bootstrap enters the checked directory inode before this worker runs.
+// All destructive names below are relative to that cwd, never to a project
+// pathname that could have been rebound after validation.
+function projectStateWorker() {
+  const fs = require('node:fs');
+  const mode = process.argv[1];
+  const expected = JSON.parse(process.argv[2]);
+  const content = process.argv[3] || '';
+  const sameDirectory = (stat) => stat.isDirectory() &&
+    stat.dev.toString() === expected.dev && stat.ino.toString() === expected.ino &&
+    (expected.birthtimeNs === null ||
+      stat.birthtimeNs?.toString() === expected.birthtimeNs);
+  let fd;
+  let temporary;
+  try {
+    if (mode === 'write-guidance') {
+      if (!sameDirectory(fs.statSync('.', { bigint: true }))) {
+        throw new Error('STATE_DIRECTORY_CHANGED');
+      }
+      temporary = `HCC.md.tmp.${process.pid}.${require('node:crypto').randomBytes(16).toString('hex')}`;
+      fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT |
+        fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+      fs.writeFileSync(fd, content);
+      fs.fsyncSync(fd);
+      fs.closeSync(fd);
+      fd = undefined;
+      /* PINNED_STATE_TEST_BEFORE_RENAME */
+      fs.renameSync(temporary, 'HCC.md');
+    } else if (mode === 'purge-legacy') {
+      const state = fs.lstatSync('.hello-cc', { bigint: true });
+      if (!sameDirectory(state)) throw new Error('STATE_DIRECTORY_CHANGED');
+      /* PINNED_STATE_TEST_BEFORE_PURGE */
+      fs.rmSync('.hello-cc', { recursive: true, force: true });
+    } else throw new Error('STATE_OPERATION_INVALID');
+    process.stdout.write('ok');
+  } catch (error) {
+    process.stderr.write('HCC_PINNED_STATE_FAILED:' + (error?.code || error?.message || 'unknown') + '\n');
+    process.exitCode = 1;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    if (temporary) {
+      try { fs.unlinkSync(temporary); } catch {}
+    }
+  }
+}
+
+const PROJECT_STATE_WORKER_SOURCE = '(' + projectStateWorker.toString() + ')()';
+
+function sameBinding(actual, expected) {
+  return actual.identity.cwd === expected.canonical &&
+    actual.identity.dev === expected.identity.dev &&
+    actual.identity.ino === expected.identity.ino &&
+    actual.identity.birthtimeNs === expected.identity.birthtimeNs;
+}
+
+function runPinnedStateWorker(cwd, mode, expectedCwd, targetIdentity, content, spawnProcess) {
+  expectedCwd.assertUnchanged();
+  const binding = preparePinnedCwdLaunch(cwd, process.execPath,
+    ['-e', PROJECT_STATE_WORKER_SOURCE, mode, JSON.stringify(targetIdentity), content], {
+      env: { PATH: '/usr/bin:/bin', NODE_OPTIONS: '', NODE_NO_WARNINGS: '1' }
+    });
+  try {
+    if (!sameBinding(binding, expectedCwd)) {
+      throw new CliError('PROJECT_PATH_CHANGED', 'Project state directory changed before pinned operation');
+    }
+    const result = spawnProcess(binding.command, binding.args, {
+      cwd: binding.cwd, env: binding.env, encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'], timeout: 300000, maxBuffer: 64 * 1024
+    });
+    if (result.error || result.status !== 0 || result.stdout !== 'ok') {
+      const marker = String(result.stderr || '');
+      if (/HCC_PINNED_CWD_CHANGED:|HCC_PINNED_STATE_FAILED:STATE_DIRECTORY_CHANGED/.test(marker)) {
+        throw new CliError('PROJECT_PATH_CHANGED', 'Project state directory changed during pinned operation');
+      }
+      throw new CliError('PROJECT_STATE_OPERATION_FAILED',
+        `Pinned project state operation failed: ${result.error?.code || marker.trim() || `exit ${result.status}`}`);
+    }
+  } finally { binding.release(); }
+}
+
+export function writePinnedProjectGuidance(stateDir, content, expectedState, {
+  spawnProcess = spawnSync
+} = {}) {
+  runPinnedStateWorker(stateDir, 'write-guidance', expectedState, expectedState.identity,
+    content, spawnProcess);
+  return path.join(stateDir, 'HCC.md');
+}
+
+export function purgePinnedLegacyProjectState(root, stateDir, expectedRoot, expectedState, {
+  spawnProcess = spawnSync
+} = {}) {
+  if (path.resolve(stateDir) !== path.join(expectedRoot.canonical, '.hello-cc')) {
+    throw new CliError('PROJECT_PATH_FORBIDDEN', 'Legacy state is not under the selected project root');
+  }
+  expectedState.assertUnchanged();
+  runPinnedStateWorker(root, 'purge-legacy', expectedRoot, expectedState.identity,
+    '', spawnProcess);
+  return stateDir;
+}

package/lib/process/selected-cwd-identity.mjs

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CliError } from '../shared/errors.mjs';
+
+function changed() {
+  return new CliError('PROJECT_PATH_CHANGED', 'Selected working directory changed; create a new session from its current location');
+}
+
+function sameDirectory(left, right) {
+  return left.isDirectory() && right.isDirectory() && left.dev === right.dev &&
+    left.ino === right.ino && left.birthtimeNs === right.birthtimeNs;
+}
+
+export function sameSelectedCwdIdentity(left, right) {
+  return Boolean(left && right && left.canonical === right.canonical &&
+    left.identity?.dev === right.identity?.dev && left.identity?.ino === right.identity?.ino &&
+    left.identity?.birthtimeNs === right.identity?.birthtimeNs);
+}
+
+export function captureSelectedCwdSnapshot(cwd) {
+  const binding = captureSelectedCwdIdentity(cwd);
+  try {
+    return Object.freeze({ requested: binding.requested, canonical: binding.canonical,
+      identity: binding.identity });
+  } finally { binding.release(); }
+}
+
+export function assertSelectedCwdSnapshot(snapshot) {
+  const current = captureSelectedCwdIdentity(snapshot.requested);
+  try {
+    if (!sameSelectedCwdIdentity(snapshot, current)) throw changed();
+  } finally { current.release(); }
+}
+
+// A provider protocol may require an absolute path even after its process was
+// started in a pinned cwd. Keep the originally selected directory identifiable
+// until the adapter closes, and recheck immediately before each path handoff.
+// This does not make the subsequent provider-internal path lookup atomic.
+export function captureSelectedCwdIdentity(cwd, expectedIdentity = null) {
+  if (typeof cwd !== 'string' || !cwd) throw new CliError('BAD_ARGS', 'Selected working directory is required');
+  const requested = path.resolve(cwd);
+  let canonical;
+  try { canonical = fs.realpathSync.native(requested); }
+  catch { throw changed(); }
+
+  let fd;
+  let initial;
+  let mode = 'descriptor';
+  try {
+    fd = fs.openSync(canonical, fs.constants.O_RDONLY |
+      (fs.constants.O_DIRECTORY || 0) | (fs.constants.O_NOFOLLOW || 0));
+    initial = fs.fstatSync(fd, { bigint: true });
+  } catch (error) {
+    if (fd !== undefined) fs.closeSync(fd);
+    fd = undefined;
+    // Execute-only directories can still be valid provider workspaces. The
+    // weaker stat-only mode preserves that contract without hiding the mode.
+    if (error?.code !== 'EACCES') throw changed();
+    mode = 'stat-only';
+    try { initial = fs.statSync(canonical, { bigint: true }); }
+    catch { throw changed(); }
+  }
+  let released = false;
+  const identity = Object.freeze({ dev: initial.dev.toString(), ino: initial.ino.toString(),
+    birthtimeNs: initial.birthtimeNs?.toString() || null });
+  const binding = {
+    requested, canonical, mode, identity,
+    assertUnchanged() {
+      if (released) throw changed();
+      try {
+        const selected = fs.statSync(requested, { bigint: true });
+        const target = fs.statSync(canonical, { bigint: true });
+        const original = fd === undefined ? initial : fs.fstatSync(fd, { bigint: true });
+        if (!sameDirectory(initial, original) || !sameDirectory(initial, selected) ||
+            !sameDirectory(initial, target)) throw changed();
+      } catch { throw changed(); }
+    },
+    dropDescriptor() {
+      if (released) return;
+      if (fd !== undefined) { fs.closeSync(fd); fd = undefined; }
+      binding.mode = 'stat-only';
+    },
+    release() {
+      if (released) return;
+      released = true;
+      if (fd !== undefined) { fs.closeSync(fd); fd = undefined; }
+    }
+  };
+  try {
+    binding.assertUnchanged();
+    if (expectedIdentity && !sameSelectedCwdIdentity(expectedIdentity, binding)) throw changed();
+  }
+  catch (error) { binding.release(); throw error; }
+  return binding;
+}

package/lib/runtime/buffer-evidence.mjs

@@ -4,6 +4,7 @@ import { performance } from 'node:perf_hooks';
 
 import { isPeerEvidenceCompatibilityProtected, resolvePeerEvidence } from '../core/peers/evidence.mjs';
 import { inspectProcessIdentity } from '../process/identity.mjs';
+import { resolveProjectDatabase } from './project-path.mjs';
 
 function canonicalDirectories(values) {
   const directories = [];
@@ -139,7 +140,7 @@ function safeTmuxPath(directory, row, runtimeId) {
 }
 
 function contextBufferDirectory(ctx) {
-  return path.resolve(ctx.root, '.hello-cc', 'bufs');
+  return path.join(resolveProjectDatabase({ root: ctx.root, createStateDir: false }).stateDir, 'bufs');
 }
 
 function boundedUnknown(referenceFile, {

package/lib/runtime/client.mjs

@@ -2,6 +2,7 @@ import { CliError } from '../shared/errors.mjs';
 import { readRuntime } from './state.mjs';
 import { runtimeApiUrl, runtimeHttpRequest } from '../web/runtime.mjs';
 import { withRuntimeApiVersionHeader } from '../web/api-version.mjs';
+import { assertSelectedCwdSnapshot } from '../process/selected-cwd-identity.mjs';
 import { performance } from 'node:perf_hooks';
 
 const DEFAULT_CLI_NAME = 'hcc';
@@ -47,12 +48,20 @@ function waitForAbort(promise, signal) {
 }
 
 export async function runtimeRequest(ctx, method, route, body = null, runtime = null, opts = {}) {
+  const expectedRootIdentity = ctx.initialRootIdentity || ctx.rootIdentity;
+  if (expectedRootIdentity) assertSelectedCwdSnapshot(expectedRootIdentity);
   const cliName = opts.cliName || DEFAULT_CLI_NAME;
   const rt = runtime || readRuntime(ctx, { cliName, localOnly: Boolean(opts.localOnly) });
   const url = runtimeApiUrl(rt, route);
   const headers = withRuntimeApiVersionHeader({ 'Content-Type': 'application/json' });
   headers['X-HCC-Root'] = ctx.root;
   headers['X-HCC-DB'] = ctx.dbPath;
+  if (expectedRootIdentity) {
+    headers['X-HCC-Root-Identity'] = Buffer.from(JSON.stringify({
+      canonical: expectedRootIdentity.canonical,
+      identity: expectedRootIdentity.identity
+    })).toString('base64url');
+  }
   if (rt.token) headers.Authorization = `Bearer ${rt.token}`;
   let res;
   let text;