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

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,11 +10,16 @@ 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';
 import { resolveProjectDatabase, secureExistingProjectStateDirectory } from '../runtime/project-path.mjs';
+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;
 
@@ -25,48 +30,110 @@ 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 =>
-    [requestedDb, canonicalCandidate].some(db => {
-      const relative = path.relative(path.join(root, '.hello-cc'), db);
-      return relative !== '' && relative !== '..' &&
-        !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
-    }));
+  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 =>
+      [...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 secureManagedDatabaseFile(dbPath, create) {
+function secureOwnedSqliteFile(file, { create = false, readOnly = false, optional = false } = {}) {
+  const changed = () => new CliError('PROJECT_PATH_FORBIDDEN', `SQLite file changed during validation: ${file}`);
+  const safeStat = stat => stat && !stat.isSymbolicLink() && stat.isFile() && stat.nlink === 1 &&
+    (typeof process.getuid !== 'function' || stat.uid === process.getuid()) &&
+    (process.platform === 'win32' || (stat.mode & 0o022) === 0) &&
+    !unsafeDirectoryAcl(file, stat);
+  const stillSame = (current, original) => safeStat(current) &&
+    current.dev === original.dev && current.ino === original.ino;
+  const recheck = () => {
+    try { return fs.lstatSync(file); }
+    catch (error) {
+      if (!optional || error?.code !== 'ENOENT') throw error;
+      // An optional WAL/SHM/journal may disappear as SQLite closes its last
+      // connection. Do not accept a different file rebuilt at the same path.
+      try { fs.lstatSync(file); }
+      catch (again) {
+        if (again?.code === 'ENOENT') return null;
+        throw again;
+      }
+      throw changed();
+    }
+  };
   let stat;
-  try { stat = fs.lstatSync(dbPath); }
+  try { stat = fs.lstatSync(file); }
   catch (error) {
     if (error?.code !== 'ENOENT') throw error;
-    if (!create) throw new CliError('NOT_FOUND', `Project database does not exist: ${dbPath}`);
+    if (!create) return false;
     try {
-      const fd = fs.openSync(dbPath, fs.constants.O_RDWR | fs.constants.O_CREAT |
+      const fd = fs.openSync(file, fs.constants.O_RDWR | fs.constants.O_CREAT |
         fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW || 0), 0o600);
       fs.closeSync(fd);
     } catch (creationError) {
       if (creationError?.code !== 'EEXIST') throw creationError;
     }
-    stat = fs.lstatSync(dbPath);
+    stat = fs.lstatSync(file);
   }
-  if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1 ||
-      (typeof process.getuid === 'function' && stat.uid !== process.getuid())) {
-    throw new CliError('PROJECT_PATH_FORBIDDEN', `Project database must be an owned regular file: ${dbPath}`);
+  if (!safeStat(stat)) {
+    // ACL inspection invokes ls and may outlive a retiring optional sidecar.
+    // Missing is safe to skip; a rebuilt or otherwise unsafe file is not.
+    if (optional && !recheck()) return false;
+    throw new CliError('PROJECT_PATH_FORBIDDEN', `SQLite file must be an owned non-writable regular file: ${file}`);
   }
-  const fd = fs.openSync(dbPath, fs.constants.O_RDWR | (fs.constants.O_NOFOLLOW || 0));
-  try {
-    const opened = fs.fstatSync(fd);
-    if (!opened.isFile() || opened.dev !== stat.dev || opened.ino !== stat.ino) {
-      throw new CliError('PROJECT_PATH_FORBIDDEN', `Project database changed during validation: ${dbPath}`);
-    }
-    if (process.platform !== 'win32' && (opened.mode & 0o777) !== 0o600) fs.fchmodSync(fd, 0o600);
-    const current = fs.lstatSync(dbPath);
-    if (current.isSymbolicLink() || current.dev !== stat.dev || current.ino !== stat.ino) {
-      throw new CliError('PROJECT_PATH_FORBIDDEN', `Project database changed during validation: ${dbPath}`);
+  // Never open/close an existing SQLite file outside SQLite: on POSIX, close()
+  // can release locks held by another SQLite connection in this process.
+  const current = recheck();
+  if (!current) return false;
+  if (!stillSame(current, stat)) throw changed();
+  if (!readOnly && process.platform !== 'win32' && (current.mode & 0o777) !== 0o600) {
+    try { fs.chmodSync(file, 0o600); }
+    catch (error) {
+      if (!optional || error?.code !== 'ENOENT') throw error;
+      if (!recheck()) return false;
+      throw changed();
     }
-  } finally { fs.closeSync(fd); }
+    const tightened = recheck();
+    if (!tightened) return false;
+    if (!stillSame(tightened, stat) || (tightened.mode & 0o777) !== 0o600) throw changed();
+  }
+  return true;
+}
+
+function secureManagedDatabaseFile(dbPath, create, readOnly = false) {
+  if (!secureOwnedSqliteFile(dbPath, { create, readOnly })) {
+    throw new CliError('NOT_FOUND', `Project database does not exist: ${dbPath}`);
+  }
+  for (const suffix of ['-wal', '-shm', '-journal']) {
+    secureOwnedSqliteFile(`${dbPath}${suffix}`, { readOnly, optional: true });
+  }
 }
 
 export function createConnectionHelpers({ now, dedupePeerBindings, redactedLogText }) {
@@ -74,11 +141,25 @@ 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);
+      const pendingDefault = rootWasMissing ? path.join(privateProjectStateDir(ctx.root), 'mesh.db') : null;
       if (options.create !== false && !fs.existsSync(ctx.root)) {
         fs.mkdirSync(ctx.root, { recursive: true });
       }
+      if (rootWasMissing && path.resolve(dbPath) === pendingDefault) {
+        dbPath = path.join(projectStateDir(ctx.root), 'mesh.db');
+      }
+      if (rootWasMissing && path.resolve(ctx.dbPath) === pendingDefault &&
+          projectStateDir(ctx.root) === privateProjectStateDir(ctx.root)) {
+        ensurePrivateProjectStateDir(ctx.root, { create: true });
+      }
       const resolved = resolveProjectDatabase({
         root: ctx.root,
         db: dbPath,
@@ -94,26 +175,43 @@ 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) {
-    const dbPath = managedDatabase(ctx)
+    if (ctx.initialRootIdentity) assertSelectedCwdSnapshot(ctx.initialRootIdentity);
+    const managed = managedDatabase(ctx);
+    const dbPath = managed
       ? resolveProjectDatabase({ root: ctx.root, db: ctx.dbPath, createStateDir: false }).db
       : ctx.dbPath;
     if (!fs.existsSync(dbPath) || !fs.statSync(dbPath).isFile()) {
       throw new CliError('NOT_FOUND', `Project database does not exist: ${dbPath}`);
     }
+    if (managed) secureManagedDatabaseFile(dbPath, false, true);
     return new DatabaseSync(dbPath, { timeout: 5000, readOnly: true });
   }
 
@@ -128,7 +226,7 @@ export function createConnectionHelpers({ now, dedupePeerBindings, redactedLogTe
         try {
           resolved = resolveProjectDatabase({
             root: project.root,
-            db: project.db || path.join(project.root, '.hello-cc', 'mesh.db'),
+            db: project.db || path.join(projectStateDir(project.root), 'mesh.db'),
             createStateDir: false
           });
         } catch (err) {

package/lib/db/schema.mjs

@@ -1,7 +1,9 @@
 import { aggregateCleanupFailure } from '../shared/cleanup-error.mjs';
+import { automaticResultKey } from '../shared/automatic-result-key.mjs';
 import { CliError } from '../shared/errors.mjs';
 
 export const DB_SCHEMA_VERSION = 7;
+const AUTOMATIC_RESULT_SCRUB_KEY = 'automatic_result_content_scrub_v1';
 
 const sleepBuffer = new SharedArrayBuffer(4);
 const sleepView = new Int32Array(sleepBuffer);
@@ -125,6 +127,63 @@ export function initSchema(db, {
   runSchemaMigrations(db);
   if (typeof beforePostMigrationIndexes === 'function') beforePostMigrationIndexes(db);
   createPostMigrationIndexes(db);
+  scrubAutomaticTaskResults(db);
+}
+
+function scrubAutomaticTaskResults(db) {
+  const marker = db.prepare('SELECT 1 FROM meta WHERE key = ?');
+  if (marker.get(AUTOMATIC_RESULT_SCRUB_KEY)) return;
+  tx(db, () => {
+    if (marker.get(AUTOMATIC_RESULT_SCRUB_KEY)) return;
+    const read = db.prepare("SELECT id,payload,created_at FROM events WHERE type = 'task.result.recorded' AND id > ? ORDER BY id LIMIT 100");
+    const update = db.prepare('UPDATE events SET payload = ? WHERE id = ?');
+    let lastId = 0;
+    while (true) {
+      const rows = read.all(lastId);
+      if (!rows.length) break;
+      for (const row of rows) {
+        let record;
+        try { record = JSON.parse(row.payload); } catch { continue; }
+        if (record?.source !== 'executor' || record.stage !== 'local' ||
+            !['command', 'diff'].includes(record.kind) ||
+            typeof record.executor_id !== 'string' || !record.executor_id ||
+            typeof record.thread_id !== 'string' || !record.thread_id ||
+            typeof record.turn_id !== 'string' || !record.turn_id ||
+            typeof record.result_key !== 'string') continue;
+        // Legacy Web observer keys identify these records more precisely than
+        // source/kind/turn metadata, which an explicit result may also carry.
+        const commandKey = `${record.executor_id}:${record.turn_id}:${record.item_id}:command`;
+        const diffPrefix = `${record.executor_id}:${record.turn_id}:diff:`;
+        const legacyCommand = record.kind === 'command' && typeof record.item_id === 'string' &&
+          record.item_id && record.result_key === commandKey;
+        const legacyDiff = record.kind === 'diff' && record.title === 'Turn changes awaiting review' &&
+          record.result_key.startsWith(diffPrefix) &&
+          /^[a-f0-9]{64}$/.test(record.result_key.slice(diffPrefix.length));
+        if (!legacyCommand && !legacyDiff) continue;
+        const executorId = typeof record.executor_id === 'string' ? record.executor_id : null;
+        const turnId = typeof record.turn_id === 'string' ? record.turn_id : null;
+        const itemId = typeof record.item_id === 'string' ? record.item_id : null;
+        // Distinct old diff hashes may become the same structural key. Keep the
+        // historical rows; result-key lookup already chooses the latest ID.
+        const resultKey = automaticResultKey({ executorId,
+          threadId: typeof record.thread_id === 'string' ? record.thread_id : null,
+          turnId, kind: record.kind, itemId: record.kind === 'command' ? itemId : null });
+        update.run(JSON.stringify({
+          result_id: record.result_id, result_key: resultKey,
+          peer: record.peer, task_id: record.task_id, stage: 'local', status: record.status,
+          kind: record.kind, source: 'executor',
+          title: record.kind === 'command' ? 'Command execution' : 'Turn changes awaiting review',
+          details: '', evidence: [], command: '', diff: '',
+          executor_id: executorId, thread_id: record.thread_id, turn_id: turnId,
+          item_id: record.kind === 'command' ? itemId : null,
+          exit_code: Number.isSafeInteger(record.exit_code) ? record.exit_code : null,
+          created_at: row.created_at
+        }), row.id);
+      }
+      lastId = rows.at(-1).id;
+    }
+    db.prepare('INSERT INTO meta(key,value) VALUES (?,?)').run(AUTOMATIC_RESULT_SCRUB_KEY, '1');
+  });
 }
 
 function createBaseSchema(db) {

package/lib/diagnostics/codex-protocol.mjs

@@ -0,0 +1,105 @@
+import { CODEX_INTERACTION_METHODS } from '../integrations/codex-interactions.mjs';
+
+// A bounded upgrade gate, not a JSON Schema validator or a runtime permission
+// check. Generated types remain the authoritative version-specific artifacts.
+export const CODEX_CLIENT_METHODS = Object.freeze([
+  'initialize', 'thread/start', 'thread/resume', 'thread/read', 'thread/list',
+  'thread/fork', 'turn/start', 'turn/steer', 'turn/interrupt',
+  'mcpServerStatus/list', 'mcpServer/tool/call', 'account/read', 'account/rateLimits/read'
+]);
+export const CODEX_NOTIFICATION_METHODS = Object.freeze([
+  'thread/started', 'thread/status/changed', 'turn/started', 'turn/completed',
+  'turn/plan/updated', 'turn/diff/updated', 'item/started', 'item/completed',
+  'item/agentMessage/delta', 'serverRequest/resolved', 'error',
+  'account/updated', 'account/login/completed', 'account/rateLimits/updated'
+]);
+const ACCOUNT_SCHEMA_FILES = ['GetAccountParams', 'GetAccountResponse', 'GetAccountRateLimitsResponse',
+  'AccountUpdatedNotification', 'AccountLoginCompletedNotification', 'AccountRateLimitsUpdatedNotification'];
+export const CODEX_PROTOCOL_SCHEMA_FILES = Object.freeze([
+  'ClientRequest', 'ClientNotification', 'ServerRequest', 'ServerNotification',
+  'CommandExecutionRequestApprovalResponse', 'FileChangeRequestApprovalResponse',
+  'PermissionsRequestApprovalResponse', 'ToolRequestUserInputResponse',
+  'McpServerElicitationRequestParams', 'McpServerElicitationRequestResponse',
+  ...ACCOUNT_SCHEMA_FILES
+]);
+// Official account schemas are generated only in the versioned v2 directory.
+export const CODEX_PROTOCOL_SCHEMA_PATHS = Object.freeze(Object.fromEntries(CODEX_PROTOCOL_SCHEMA_FILES
+  .map(name => [name, (ACCOUNT_SCHEMA_FILES.includes(name) ? 'v2/' : '') + name + '.json'])));
+
+function methods(schema) {
+  return (schema?.oneOf || []).flatMap(row => row.properties?.method?.enum || []);
+}
+function enumValues(schema, document, seen = new Set()) {
+  if (!schema || typeof schema !== 'object') return [];
+  if (schema.$ref) {
+    const ref = schema.$ref;
+    if (seen.has(ref) || !ref.startsWith('#/definitions/')) return [];
+    const next = new Set(seen); next.add(ref);
+    return enumValues(document.definitions?.[ref.slice('#/definitions/'.length)], document, next);
+  }
+  return [...(schema.enum || []), ...(Object.hasOwn(schema, 'const') ? [schema.const] : []),
+    ...['oneOf', 'anyOf', 'allOf'].flatMap(key => (schema[key] || []).flatMap(row => enumValues(row, document, seen)))];
+}
+
+export function inspectCodexProtocol(schemas) {
+  const checks = [];
+  const check = (contract, ok) => checks.push({ contract, status: ok ? 'pass' : 'fail' });
+  for (const [file, expected] of [
+    ['ClientRequest', CODEX_CLIENT_METHODS], ['ClientNotification', ['initialized']],
+    ['ServerRequest', [...CODEX_INTERACTION_METHODS]], ['ServerNotification', CODEX_NOTIFICATION_METHODS]
+  ]) {
+    const available = methods(schemas[file]);
+    for (const method of expected) check(`${file}: ${method}`, available.includes(method));
+  }
+  for (const [file, fields] of [
+    ['CommandExecutionRequestApprovalResponse', ['decision']],
+    ['FileChangeRequestApprovalResponse', ['decision']],
+    ['PermissionsRequestApprovalResponse', ['permissions', 'scope']],
+    ['ToolRequestUserInputResponse', ['answers']],
+    ['McpServerElicitationRequestResponse', ['action', 'content']]
+  ]) {
+    const schema = schemas[file];
+    check(`${file}: response fields`, fields.every(field => Object.hasOwn(schema?.properties || {}, field)));
+    // HCC never supplies unknown required response fields. Optional extensions
+    // are compatible with this gate; new required fields demand adapter review.
+    check(`${file}: no new required response fields`, Boolean(schema) && (schema.required || []).every(field => fields.includes(field)));
+  }
+  for (const [file, field, expected] of [
+    ['CommandExecutionRequestApprovalResponse', 'decision', ['accept', 'decline', 'cancel']],
+    ['FileChangeRequestApprovalResponse', 'decision', ['accept', 'decline', 'cancel']],
+    ['PermissionsRequestApprovalResponse', 'scope', ['turn', 'session']],
+    ['McpServerElicitationRequestResponse', 'action', ['accept', 'decline', 'cancel']]
+  ]) {
+    const values = enumValues(schemas[file]?.properties?.[field], schemas[file] || {});
+    check(`${file}: ${field} choices`, expected.every(value => values.includes(value)));
+  }
+  const elicitation = schemas.McpServerElicitationRequestParams;
+  check('MCP elicitation: thread and server identity',
+    ['threadId', 'serverName'].every(field => elicitation?.required?.includes(field)) &&
+    Object.hasOwn(elicitation?.properties || {}, 'turnId'));
+  for (const [mode, fields] of [['form', ['message', 'mode', 'requestedSchema']], ['url', ['message', 'mode', 'elicitationId', 'url']]]) {
+    check(`MCP elicitation: ${mode} identity and payload`, Boolean(elicitation?.oneOf?.some(row =>
+      row.properties?.mode?.enum?.includes(mode) && fields.every(field => row.required?.includes(field) && Object.hasOwn(row.properties || {}, field)))));
+  }
+  check('Account read: explicit nonrefreshing option', schemas.GetAccountParams?.properties?.refreshToken?.type === 'boolean' &&
+    (schemas.GetAccountParams?.required || []).every(field => field === 'refreshToken'));
+  check('Account read: auth requirement is explicit', schemas.GetAccountResponse?.required?.includes('requiresOpenaiAuth') &&
+    schemas.GetAccountResponse?.properties?.requiresOpenaiAuth?.type === 'boolean');
+  check('Account read: recognized account types', ['apiKey', 'chatgpt', 'amazonBedrock'].every(type =>
+    schemas.GetAccountResponse?.definitions?.Account?.oneOf?.some(row => row.properties?.type?.enum?.includes(type))));
+  check('Account limits: historical and multi-bucket fields', ['rateLimits', 'rateLimitsByLimitId'].every(field =>
+    Object.hasOwn(schemas.GetAccountRateLimitsResponse?.properties || {}, field)));
+  check('Account limits: window percentage', schemas.GetAccountRateLimitsResponse?.definitions?.RateLimitWindow?.required?.includes('usedPercent') &&
+    ['integer', 'number'].includes(schemas.GetAccountRateLimitsResponse?.definitions?.RateLimitWindow?.properties?.usedPercent?.type));
+  check('Account notifications: status and quota fields', Object.hasOwn(schemas.AccountUpdatedNotification?.properties || {}, 'authMode') &&
+    Object.hasOwn(schemas.AccountUpdatedNotification?.properties || {}, 'planType') && schemas.AccountRateLimitsUpdatedNotification?.required?.includes('rateLimits'));
+  check('Account notification: correlated login completion', schemas.AccountLoginCompletedNotification?.required?.includes('success') &&
+    Object.hasOwn(schemas.AccountLoginCompletedNotification?.properties || {}, 'loginId'));
+  const unsupportedServerRequests = methods(schemas.ServerRequest).filter(method => !CODEX_INTERACTION_METHODS.has(method)).sort();
+  return {
+    status: checks.every(entry => entry.status === 'pass') ? 'compatible' : 'incompatible',
+    checks, unsupportedServerRequests,
+    scope: 'Method presence, response fields and choices, MCP form/URL identity, and read-only account/quota fields; not full schema or runtime validation.',
+    inferenceCalled: false, accountAccessed: false
+  };
+}

package/lib/guidance.mjs

@@ -1,5 +1,7 @@
-import fs from 'node:fs';
-import path from 'node:path';
+import { resolveProjectDatabase } from './runtime/project-path.mjs';
+import { writeProjectGuidanceFiles, removeProjectGuidanceFiles } from './process/pinned-guidance.mjs';
+import { writePinnedProjectGuidance } from './process/pinned-project-state.mjs';
+import { captureSelectedCwdIdentity } from './process/selected-cwd-identity.mjs';
 
 export function guidanceMarkdown() {
   return `# hello-cc Coordination Rules
@@ -83,41 +85,24 @@ Before stopping:
 `;
 }
 
-export function writeGuidance(root) {
-  const guidePath = path.join(root, '.hello-cc', 'HCC.md');
-  fs.mkdirSync(path.dirname(guidePath), { recursive: true });
-  const content = guidanceMarkdown();
-  fs.writeFileSync(guidePath, content);
-  const clause = `\n<!-- hello-cc:start -->\n\n${content}\n<!-- hello-cc:end -->\n`;
-  for (const file of ['CLAUDE.md', 'AGENTS.md']) {
-    const target = path.join(root, file);
-    if (!fs.existsSync(target)) {
-      fs.writeFileSync(target, clause.trimStart());
-      continue;
-    }
-    const existing = fs.readFileSync(target, 'utf8');
-    const updated = existing.includes('<!-- hello-cc:start -->')
-      ? existing.replace(/<!-- hello-cc:start -->[\s\S]*?<!-- hello-cc:end -->/, clause.trim())
-      : `${existing.trimEnd()}\n${clause}`;
-    fs.writeFileSync(target, updated);
+export function writeGuidance(root, options = {}) {
+  const selectedRoot = captureSelectedCwdIdentity(root, options.expectedSnapshot);
+  let selectedState;
+  try {
+    const stateDir = resolveProjectDatabase({ root, createStateDir: true }).stateDir;
+    selectedState = captureSelectedCwdIdentity(stateDir);
+    selectedRoot.assertUnchanged();
+    const content = guidanceMarkdown();
+    writeProjectGuidanceFiles(root, content, { ...options, expectedBinding: selectedRoot });
+    selectedRoot.assertUnchanged();
+    return writePinnedProjectGuidance(stateDir, content, selectedState,
+      { spawnProcess: options.stateSpawnProcess });
+  } finally {
+    selectedState?.release();
+    selectedRoot.release();
   }
-  return guidePath;
 }
 
-export function removeGuidanceBlocks(root) {
-  const changed = [];
-  for (const file of ['CLAUDE.md', 'AGENTS.md']) {
-    const target = path.join(root, file);
-    if (!fs.existsSync(target)) continue;
-    const existing = fs.readFileSync(target, 'utf8');
-    const updated = existing
-      .replace(/\n?<!-- hello-cc:start -->[\s\S]*?<!-- hello-cc:end -->\n?/g, '\n')
-      .replace(/\n{3,}/g, '\n\n')
-      .trimEnd();
-    if (updated !== existing) {
-      fs.writeFileSync(target, updated ? `${updated}\n` : '');
-      changed.push(target);
-    }
-  }
-  return changed;
+export function removeGuidanceBlocks(root, options = {}) {
+  return removeProjectGuidanceFiles(root, options);
 }