chati-dev 4.5.27 → 4.5.29

package/src/terminal/verification-process-facts.js

@@ -0,0 +1,49 @@
+/** Typed process facts, not authentication. Only the private native transport
+ * may produce Darwin observations for the trusted canonical verifier. */
+import { createHash } from 'node:crypto';
+import { isAbsolute, resolve } from 'node:path';
+import { canonicalize, darwinSupervisorNonce, parseDarwinReadyMessage, parseDarwinCompletionMessage, sha256 } from '@chati/core';
+
+const keys = ['schema_version', 'invocation_context', 'helper_sha256', 'policy_digest', 'working_dir',
+  'arguments_digest', 'stdin_sha256', 'executable_binding_digest', 'ready', 'completion'];
+const digest = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const bytesHash = value => createHash('sha256').update(value).digest('hex');
+function invalid() { throw Object.assign(new Error('verification requires a complete native observation of the exact frozen check'), { code: 'VERIFICATION_COMPLETION_INVALID' }); }
+
+// Derive facts from the validated/pinned binding, without adding normalizer
+// defaults that were absent from the frozen command's hashed representation.
+export function projectVerificationExecutableBinding(validated, declared) {
+  return Object.freeze({ executable_path: validated.executable_path, executable_sha256: validated.executable_sha256,
+    ...(Object.hasOwn(declared, 'supporting_executables')
+      ? { supporting_executables: structuredClone(validated.supporting_executables) } : {}) });
+}
+
+export function createDarwinVerificationBinding({ context, helperSha256, policyDigest, ready, completion, workingDir, executableBinding, args, stdin }) {
+  return Object.freeze(canonicalize({ schema_version: 1, invocation_context: context,
+    helper_sha256: helperSha256, policy_digest: policyDigest, working_dir: workingDir,
+    executable_binding_digest: sha256(executableBinding), arguments_digest: sha256(args), stdin_sha256: bytesHash(stdin), ready, completion }));
+}
+
+export function verificationProcessCompleted(facts, expected) {
+  if (facts?.containment_kind !== 'darwin_scoped_process_group_v1') {
+    return facts?.containment_kind === 'bubblewrap_pid_namespace_v1' && facts.process_tree_stopped === true
+      && !Object.hasOwn(facts, 'darwin_verification_binding');
+  }
+  const binding = facts.darwin_verification_binding;
+  if (!binding || Array.isArray(binding) || Object.keys(binding).length !== keys.length || keys.some(key => !Object.hasOwn(binding, key))
+    || binding.schema_version !== 1 || facts.process_tree_stopped !== false || facts.process_group_stopped !== true
+    || !digest(binding.helper_sha256) || !digest(binding.policy_digest) || !digest(facts.containment_digest)
+    || !expected || !isAbsolute(expected.workingDir) || resolve(expected.workingDir) !== binding.working_dir
+    || binding.invocation_context?.authority_kind !== 'verification_check'
+    || binding.invocation_context.executable_binding_digest !== binding.executable_binding_digest
+    || binding.executable_binding_digest !== sha256(expected.executableBinding)
+    || sha256(facts.executable_binding) !== binding.executable_binding_digest
+    || binding.arguments_digest !== sha256(expected.args) || binding.stdin_sha256 !== bytesHash(expected.stdin)
+    || facts.stdin_sha256 !== binding.stdin_sha256) invalid();
+  try {
+    const ready = parseDarwinReadyMessage(`${JSON.stringify(binding.ready)}\n`, { ...binding.ready,
+      nonce: darwinSupervisorNonce(binding.invocation_context) });
+    parseDarwinCompletionMessage(`${JSON.stringify(binding.completion)}\n`, ready, facts.exit_code);
+  } catch { invalid(); }
+  return true;
+}

package/src/upgrade/entrypoints.js

@@ -0,0 +1,68 @@
+import { createHash } from 'node:crypto';
+import { closeSync, constants, fstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { lstatAtSync, openAtSync } from '@chati/core';
+import { generateClaudeRouter, generateCodexSkill, generateGeminiRouter, generateGrokRouter, generateGrokGovernanceRules } from '../installer/templates.js';
+import { openUpgradeDirectory } from './paths.js';
+
+const definitions = Object.freeze([
+  ['claude', '.claude/commands/chati.md', generateClaudeRouter],
+  ['codex', '.agents/skills/chati/SKILL.md', generateCodexSkill],
+  ['grok', '.grok/commands/chati.md', generateGrokRouter],
+  ['grok', '.grok/rules/chati-governance.md', generateGrokGovernanceRules],
+  ['gemini', '.gemini/commands/chati.toml', generateGeminiRouter],
+]);
+export const MANAGED_ENTRYPOINT_PATHS = Object.freeze(definitions.map(([, path]) => path));
+
+// Exact outputs of production-verified candidate116, both neutral and adapted
+// paths. Signed inventory 65d4466261894dbe167773ee2d80d7be1af55339151864a7dfaace4460f19fd2;
+// templates e8741cbff4b58c391703c6acd83112328055682dbcdaef5cbed3a212abdf32db;
+// core ef9b65f6592f5de4d2367ff54d7a2267c3ad6c182bb70310581a6385016a5825.
+// Never derive legacy ownership from the mutable project's current manifest.
+const legacyHashes = Object.freeze({
+  '.claude/commands/chati.md': ['4fddf1519bad9cbd73d1abea2d4090e03faf1aac6330253b2dc0ea0c5c58fc8c', '5894f7307afbc1033fc74eda2ec22020d075db92f3050da126813316785d5d99'],
+  '.agents/skills/chati/SKILL.md': ['910c94e5ab8b08a8e357dcce81224a7cb8c898a098105bbcfd7883846a84c076', '43a975bd31e3be126a2ae563071efcb6463a4652ea3e0ab6591f49aab8ed59dd'],
+  '.grok/commands/chati.md': ['864ecd0964d28ea4b28a55e4250c3a23035ccee0f9641bc71afe7dadd459928d', '9d69a817220aaaa6f62ad2e33b0d184903dd9d0e83d0066017ebdebeb03be219'],
+  '.grok/rules/chati-governance.md': ['dde0f1787ba4ddebdd7471b4f9333435894e99275f7d47df710d1259ac7ee80e'],
+  '.gemini/commands/chati.toml': ['440e9625122c58710fc01effaf18e0dc6c32e522bd041b44f3057f71c1940d11', '164bd298566e92021152b9318efcc8ba90bd279f7b7234d675fa72ad791b3535'],
+});
+
+export function managedEntrypoints(providers) {
+  return definitions.filter(([provider]) => providers.includes(provider)).map(([provider, path, render]) => ({
+    path, content: render({ orchestratorPath: `.chati.dev/.adapted/${provider}/orchestrator/chati.md` }),
+    neutral: render(),
+  }));
+}
+
+function readEntrypoint(root, path) {
+  const parent = openUpgradeDirectory(root, dirname(path));
+  if (parent === undefined) return null;
+  let file;
+  try {
+    try { file = openAtSync(parent, basename(path), constants.O_RDONLY | constants.O_NONBLOCK); }
+    catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+    const stat = fstatSync(file);
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024) throw Object.assign(new Error(`Unsafe entrypoint: ${path}`), { code: 'UNSAFE_UPGRADE_PATH' });
+    const bytes = readFileSync(file);
+    const after = lstatAtSync(parent, basename(path));
+    if (after.dev !== stat.dev || after.ino !== stat.ino || bytes.length > 1024 * 1024) throw Object.assign(new Error(`Entrypoint changed: ${path}`), { code: 'UPGRADE_STORAGE_CHANGED' });
+    return bytes;
+  } finally { if (file !== undefined) closeSync(file); closeSync(parent); }
+}
+
+/** Recognition precedes all staging; user customizations are never merged. */
+export function stageManagedEntrypoints(projectDir, stagingDir, providers) {
+  const entries = managedEntrypoints(providers);
+  for (const entry of entries) {
+    const bytes = readEntrypoint(projectDir, entry.path);
+    if (bytes === null || bytes.equals(Buffer.from(entry.content)) || bytes.equals(Buffer.from(entry.neutral))) continue;
+    if (!legacyHashes[entry.path]?.includes(createHash('sha256').update(bytes).digest('hex'))) {
+      throw Object.assign(new Error(`Managed entrypoint was edited or is an unrecognized version: ${entry.path}. No active files were replaced. Preserve the customization and resolve this conflict before upgrading.`), { code: 'UPGRADE_ENTRYPOINT_CONFLICT' });
+    }
+  }
+  for (const { path, content } of entries) {
+    mkdirSync(dirname(join(stagingDir, path)), { recursive: true });
+    writeFileSync(join(stagingDir, path), content, { flag: 'wx' });
+  }
+  return entries.map(entry => entry.path);
+}

package/src/upgrade/generation.js

@@ -0,0 +1,194 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { closeSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import * as yaml from 'js-yaml';
+import semver from 'semver';
+import { copyInstalledRuntime, writeClaudeSettingsWithMerge } from '../installer/core.js';
+import { generateManifest, saveManifest, verifyFrameworkSource } from '../installer/manifest.js';
+import { verifyCurrentPackageArtifact } from '../installer/package-artifact.js';
+import { validateInstallation } from '../installer/validator.js';
+import { loadRuntimeInstallationV2 } from '../orchestrator/runtime-installation-v2.js';
+import { openPinnedProviderExecutable, openPinnedProviderSupportingExecutables } from '../installer-v2/provider-executable.js';
+import { findMigrations } from './migrator.js';
+import { requireLicenseEntitlement } from '../license/client.js';
+import { MANAGED_ENTRYPOINT_PATHS, stageManagedEntrypoints } from './entrypoints.js';
+
+export const UPGRADE_PACKAGE_ROOT = fileURLToPath(new URL('../../', import.meta.url));
+export const UPGRADE_TARGETS = Object.freeze(['.chati.dev', '.claude/settings.json', ...MANAGED_ENTRYPOINT_PATHS, '.chati/manifest.json']);
+export const upgradeFailure = (code, message) => { throw Object.assign(new Error(message), { code }); };
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+export function upgradeTestHook(phase, detail = {}) {
+  globalThis[Symbol.for('chati.upgrade.test-hooks')]?.onPhase?.(phase, detail);
+}
+
+/** Bounded to an explicitly selected installation subtree, not the project.
+ * Links/special files are refused before staging or promotion can follow them. */
+export function upgradeSnapshot(path) {
+  let stat;
+  try { stat = lstatSync(path); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  const entries = [];
+  const walk = (current, relative = '') => {
+    const item = lstatSync(current);
+    if (item.isDirectory()) {
+      entries.push([relative, 'directory', item.mode & 0o777]);
+      for (const name of readdirSync(current).sort()) walk(join(current, name), relative ? `${relative}/${name}` : name);
+    } else if (item.isFile() && item.nlink === 1) {
+      entries.push([relative, 'file', item.mode & 0o777, digest(readFileSync(current))]);
+    } else upgradeFailure('UNSAFE_UPGRADE_PATH', `Upgrade target contains a link or special file: ${current}`);
+  };
+  walk(path);
+  return { identity: `${stat.dev}:${stat.ino}`, digest: digest(JSON.stringify(entries)), type: stat.isDirectory() ? 'directory' : 'file' };
+}
+
+export function copyUpgradeTree(source, destination, { exclude = [] } = {}) {
+  const stat = lstatSync(source);
+  if (stat.isDirectory()) {
+    mkdirSync(destination, { recursive: true, mode: stat.mode & 0o777 });
+    for (const name of readdirSync(source)) {
+      // Prior managed backups stay in the retired generation, never recursively
+      // duplicate every historical generation into the new runtime.
+      if (/^\.backup-v/.test(name) || exclude.includes(name)) continue;
+      copyUpgradeTree(join(source, name), join(destination, name));
+    }
+  } else if (stat.isFile() && stat.nlink === 1) {
+    mkdirSync(dirname(destination), { recursive: true });
+    copyFileSync(source, destination);
+  } else upgradeFailure('UNSAFE_UPGRADE_PATH', `Cannot stage linked or special source: ${source}`);
+}
+
+export function verifyUpgradePackage(targetVersion) {
+  const version = JSON.parse(readFileSync(join(UPGRADE_PACKAGE_ROOT, 'package.json'), 'utf8')).version;
+  if (targetVersion !== undefined && targetVersion !== version) upgradeFailure('UPGRADE_PACKAGE_VERSION_MISMATCH', `This command contains v${version}, not ${targetVersion}`);
+  const integrity = verifyCurrentPackageArtifact(UPGRADE_PACKAGE_ROOT);
+  if (!integrity.valid) upgradeFailure('UPGRADE_PACKAGE_UNTRUSTED', `Package verification failed: ${integrity.reason}`);
+  const framework = verifyFrameworkSource(join(UPGRADE_PACKAGE_ROOT, 'framework'), { expectedVersion: version });
+  if (!framework.valid) upgradeFailure('UPGRADE_PACKAGE_UNTRUSTED', `Framework verification failed: ${framework.reason}`);
+  return { version, package_sha256: digest(readFileSync(join(UPGRADE_PACKAGE_ROOT, 'package-artifact-manifest.json'))) };
+}
+
+export function assertUpgradeBindings(projectDir) {
+  const artifact = loadRuntimeInstallationV2(projectDir);
+  if (!artifact) return null;
+  try {
+    for (const binding of artifact.installation.enabled_providers) {
+      const descriptors = [];
+      try {
+        descriptors.push(openPinnedProviderExecutable(binding, { harnessId: binding.harness_id, projectDir }).descriptor);
+        for (const pinned of openPinnedProviderSupportingExecutables(binding, { harnessId: binding.harness_id, projectDir })) descriptors.push(pinned.descriptor);
+      } finally { for (const fd of descriptors) closeSync(fd); }
+    }
+  } catch (error) {
+    upgradeFailure('UPGRADE_BINDING_RECONFIGURATION_REQUIRED', `Existing executable binding is no longer valid (${error.code}). Explicitly reconfigure the installation before upgrading; no binding was changed.`);
+  }
+  return artifact;
+}
+
+export async function authorizeUpgradeProfile(artifact) {
+  if (artifact?.installation?.profile === 'authorized-internal') await requireLicenseEntitlement('internal');
+}
+
+export async function readUpgradeInstallation(projectDir, { version, offline = false }) {
+  const framework = join(projectDir, '.chati.dev');
+  if (!existsSync(framework) || existsSync(join(projectDir, 'chati.dev'))) {
+    upgradeFailure('UPGRADE_LAYOUT_REQUIRES_MIGRATION', 'Upgrade requires one canonical .chati.dev installation. Legacy or ambiguous layouts need explicit migration.');
+  }
+  const config = yaml.load(readFileSync(join(framework, 'config.yaml'), 'utf8'));
+  if (!semver.valid(config?.version) || semver.lt(config.version, '4.3.0') || semver.gt(config.version, version)) {
+    upgradeFailure('UPGRADE_VERSION_REQUIRES_MIGRATION', 'Automatic upgrade supports versions from 4.3.0 through the current package; older layouts or downgrades require an explicit migration.');
+  }
+  if (findMigrations(projectDir, config.version, version).length) upgradeFailure('UPGRADE_MIGRATION_REQUIRES_REVIEW', 'This upgrade requires a migration outside the runtime-only write set. No project files were changed.');
+  const cli = join(framework, '_cli');
+  if (existsSync(cli) && !lstatSync(cli).isDirectory()) upgradeFailure('UNSAFE_UPGRADE_PATH', 'Existing _cli must be a real directory');
+  const session = yaml.load(readFileSync(join(projectDir, '.chati/session.yaml'), 'utf8'));
+  if (!session || typeof session !== 'object' || Array.isArray(session)) upgradeFailure('UPGRADE_SESSION_INVALID', 'A valid session is required before upgrade');
+  if ((session.current_agent && session.session_status !== 'paused')
+    || Object.values(session.agents || {}).some(agent => ['running', 'reserved'].includes(agent.execution_claim_state))) {
+    upgradeFailure('UPGRADE_RUNTIME_ACTIVE', 'Pause/exit active sessions and resolve execution claims before upgrading. Session state was preserved.');
+  }
+  let protocol;
+  try { protocol = JSON.parse(readFileSync(join(cli, 'version.json'), 'utf8')).maintenance_protocol; }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (protocol !== 1 && !offline) upgradeFailure('UPGRADE_OFFLINE_CONFIRMATION_REQUIRED', 'This installed version cannot exclude legacy runtime processes. Close all Chati sessions, then repeat upgrade --offline. Online upgrade is not supported for this version.');
+  const artifact = assertUpgradeBindings(projectDir);
+  await authorizeUpgradeProfile(artifact);
+  const providers = artifact ? artifact.installation.enabled_providers.map(binding => binding.harness_id)
+    : Object.entries(config.providers || {}).filter(([, value]) => value?.enabled === true).map(([name]) => name);
+  if (providers.some(name => !['claude', 'codex', 'grok', 'gemini'].includes(name))) upgradeFailure('UPGRADE_PROVIDER_UNSUPPORTED', 'Installed provider configuration requires explicit reconfiguration');
+  const protectedPaths = ['.chati/session.yaml', '.chati/v2/installation.json', 'CLAUDE.md'];
+  const protectedState = Object.fromEntries(protectedPaths.map(path => [path, upgradeSnapshot(join(projectDir, path))]));
+  return { config, artifact, providers: [...new Set(providers)], protectedState };
+}
+
+export function assertUpgradeStatePreserved(projectDir, protectedState) {
+  for (const [path, before] of Object.entries(protectedState)) {
+    if (JSON.stringify(upgradeSnapshot(join(projectDir, path))) !== JSON.stringify(before)) upgradeFailure('UPGRADE_STATE_CHANGED', `Protected project state changed: ${path}`);
+  }
+}
+
+export async function prepareUpgradeGeneration(projectDir, stagingDir, installation, packageIdentity) {
+  const { config, artifact, providers } = installation;
+  const entrypointTargets = stageManagedEntrypoints(projectDir, stagingDir, providers);
+  const frameworkDir = join(stagingDir, '.chati.dev');
+  // These are fully managed namespaces. Overlaying the old CLI could retain
+  // removed code or nested dependencies that shadow the new package's graph.
+  // The original tree remains untouched and is retired intact at promotion.
+  copyUpgradeTree(join(projectDir, '.chati.dev'), frameworkDir, { exclude: ['_cli', 'framework', '.adapted'] });
+  upgradeTestHook('before-runtime-copy', { stagingDir });
+  copyInstalledRuntime({ frameworkDir, providers, runtimeVersion: artifact ? 2 : undefined, version: packageIdentity.version, strict: true });
+  // The router compares installer_version with the bundled CLI stamp: an
+  // upgraded generation must advance both, or every later run warns that
+  // an upgrade is still required.
+  writeFileSync(join(frameworkDir, 'config.yaml'), yaml.dump({ ...config, version: packageIdentity.version, installer_version: packageIdentity.version }, { lineWidth: -1 }));
+  copyUpgradeTree(join(projectDir, '.chati/session.yaml'), join(stagingDir, '.chati/session.yaml'));
+  if (artifact) copyUpgradeTree(join(projectDir, '.chati/v2/installation.json'), join(stagingDir, '.chati/v2/installation.json'));
+  const memories = join(projectDir, '.chati/memories/shared/durable');
+  if (existsSync(memories) && lstatSync(memories).isDirectory()) mkdirSync(join(stagingDir, '.chati/memories/shared/durable'), { recursive: true });
+  const targets = ['.chati.dev'];
+  const claude = join(projectDir, '.claude');
+  if (existsSync(claude)) {
+    if (!lstatSync(claude).isDirectory() || lstatSync(claude).isSymbolicLink()) upgradeFailure('UNSAFE_UPGRADE_PATH', '.claude must be a real directory');
+    const settings = join(claude, 'settings.json');
+    if (existsSync(settings)) {
+      const parsed = JSON.parse(readFileSync(settings, 'utf8'));
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) upgradeFailure('UPGRADE_SETTINGS_INVALID', 'Claude settings must be a JSON object');
+      copyUpgradeTree(settings, join(stagingDir, '.claude/settings.json'));
+    }
+    writeClaudeSettingsWithMerge(join(stagingDir, '.claude/settings.json'), { runtimeVersion: artifact ? 2 : undefined });
+    targets.push('.claude/settings.json');
+  }
+  targets.push(...entrypointTargets);
+  // A former manifest covering user instructions or other state cannot be
+  // silently narrowed to the runtime write set by this transaction.
+  const formerManifest = join(projectDir, '.chati/manifest.json');
+  if (existsSync(formerManifest)) {
+    const manifest = JSON.parse(readFileSync(formerManifest, 'utf8'));
+    if (!manifest.files || Object.keys(manifest.files).some(path => !path.startsWith('.chati.dev/') && path !== '.claude/settings.json' && !MANAGED_ENTRYPOINT_PATHS.includes(path))) {
+      upgradeFailure('UPGRADE_MANIFEST_REQUIRES_MIGRATION', 'Existing manifest covers paths outside this upgrade write set');
+    }
+  }
+  const paths = [];
+  const collect = (path, relative) => {
+    const stat = lstatSync(path);
+    if (stat.isDirectory()) for (const name of readdirSync(path)) collect(join(path, name), `${relative}/${name}`);
+    else if (stat.isFile() && stat.nlink === 1) paths.push(relative);
+    else upgradeFailure('UNSAFE_UPGRADE_PATH', `Invalid staged path: ${relative}`);
+  };
+  for (const path of targets) collect(join(stagingDir, path), path);
+  saveManifest(stagingDir, generateManifest(stagingDir, paths.sort(), packageIdentity.version));
+  targets.push('.chati/manifest.json');
+  const expected = Object.fromEntries(targets.map(path => [path, upgradeSnapshot(join(stagingDir, path))]));
+  upgradeTestHook('before-validation', { stagingDir });
+  const validation = await validateInstallation(stagingDir);
+  if (validation.passed !== validation.total) upgradeFailure('UPGRADE_VALIDATION_FAILED', `Staged installation passed ${validation.passed}/${validation.total} checks`);
+  const modules = ['orchestrator/cli.js', 'terminal/run-agent.js', 'terminal/run-rail-task.js', 'terminal/run-rail-recovery.js'];
+  const urls = modules.map(path => pathToFileURL(join(frameworkDir, '_cli', path)).href);
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !['NODE_OPTIONS', 'NODE_PATH'].includes(key)));
+  execFileSync(process.execPath, ['--input-type=module', '-e', `for (const url of ${JSON.stringify(urls)}) await import(url);`], { cwd: stagingDir, env, stdio: 'pipe', timeout: 20000 });
+  for (const path of targets) {
+    if (JSON.stringify(upgradeSnapshot(join(stagingDir, path))) !== JSON.stringify(expected[path])) upgradeFailure('UPGRADE_STAGING_CHANGED', `Staged inventory changed during validation: ${path}`);
+  }
+  assertUpgradeStatePreserved(projectDir, installation.protectedState);
+  return { targets, validation: { passed: validation.passed, total: validation.total } };
+}

package/src/upgrade/maintenance.js

@@ -0,0 +1,79 @@
+import { closeSync, constants, fstatSync, fsyncSync, lstatSync, openSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { lstatAtSync, mkdirAtSync, openAtSync, tryExclusiveFileLockSync, trySharedFileLockSync } from '@chati/core';
+
+export const UPGRADE_PENDING_FILE = 'pending.json';
+const LOCK_FILE = 'maintenance.lock';
+const identity = (stat) => `${stat.dev}:${stat.ino}`;
+const fail = (code, message) => { throw Object.assign(new Error(message), { code }); };
+
+/** Persistent descriptor lock, never unlinked or stolen by age. Readers may
+ * coexist; the upgrade owns an exclusive descriptor until its promise settles. */
+export async function withUpgradeMaintenance(projectDir, action, { exclusive = false, createState = false } = {}) {
+  const unsafeCode = exclusive ? 'UNSAFE_UPGRADE_PATH' : 'UNSAFE_RUNTIME_PATH';
+  const changedCode = exclusive ? 'UPGRADE_STORAGE_CHANGED' : 'UNSAFE_RUNTIME_PATH';
+  if (!projectDir && !exclusive) return action();
+  const root = realpathSync(projectDir);
+  const statePath = join(root, '.chati');
+  let stateStat;
+  try { stateStat = lstatSync(statePath); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    if (!createState) { if (!exclusive) return action(); throw error; }
+    // Only an already authorized installer may bootstrap the shared lock.
+    const rootFd = openSync(root, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    try {
+      try { mkdirAtSync(rootFd, '.chati'); fsyncSync(rootFd); }
+      catch (mkdirError) { if (mkdirError.code !== 'EEXIST') throw mkdirError; }
+    } finally { closeSync(rootFd); }
+    stateStat = lstatSync(statePath);
+  }
+  if (!stateStat.isDirectory() || stateStat.isSymbolicLink()) fail(unsafeCode, '.chati must be a real directory');
+  const rootStat = lstatSync(root);
+  let stateFd; let lockFd;
+  const directories = [];
+  try {
+    stateFd = openSync(statePath, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    directories.push({ fd: stateFd, path: statePath, identity: identity(stateStat) });
+    if (identity(fstatSync(stateFd)) !== identity(stateStat)) fail(unsafeCode, '.chati changed while acquiring maintenance');
+    let storageDir = statePath;
+    for (const name of ['runtime', 'upgrade']) {
+      try { mkdirAtSync(stateFd, name); fsyncSync(stateFd); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+      const stat = lstatAtSync(stateFd, name);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) fail(unsafeCode, 'upgrade storage must contain only real directories');
+      stateFd = openAtSync(stateFd, name, constants.O_RDONLY | constants.O_DIRECTORY);
+      storageDir = join(storageDir, name);
+      directories.push({ fd: stateFd, path: storageDir, identity: identity(stat) });
+      if (identity(fstatSync(stateFd)) !== identity(stat)) fail(unsafeCode, 'upgrade storage changed while opening');
+    }
+    lockFd = openAtSync(stateFd, LOCK_FILE, constants.O_RDWR | constants.O_CREAT | constants.O_NONBLOCK, 0o600);
+    const lockStat = fstatSync(lockFd);
+    if (!lockStat.isFile() || lockStat.nlink !== 1) fail(unsafeCode, 'maintenance lock must be a single-link regular file');
+    const assertCurrent = () => {
+      if (identity(lstatSync(root)) !== identity(rootStat)
+        || directories.some(directory => identity(lstatSync(directory.path)) !== directory.identity)
+        || identity(lstatAtSync(stateFd, LOCK_FILE)) !== identity(lockStat)) {
+        fail(changedCode, 'maintenance storage identity changed');
+      }
+    };
+    assertCurrent();
+    const acquired = exclusive ? tryExclusiveFileLockSync(lockFd) : trySharedFileLockSync(lockFd);
+    if (!acquired) fail('UPGRADE_IN_PROGRESS', exclusive
+      ? 'A Chati runtime or another upgrade is active. Close active sessions before upgrading.'
+      : 'An upgrade is in progress. Resume this command after the upgrade finishes.');
+    assertCurrent();
+    if (!exclusive) {
+      try {
+        lstatAtSync(stateFd, UPGRADE_PENDING_FILE);
+        fail('UPGRADE_RECOVERY_REQUIRED', 'An interrupted upgrade must be recovered with chati-dev upgrade before starting runtime commands.');
+      } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+    globalThis[Symbol.for('chati.upgrade.test-hooks')]?.onMaintenance?.({ exclusive, root });
+    const result = await action({ root, stateFd, storageDir, assertCurrent });
+    assertCurrent();
+    return result;
+  } finally {
+    if (lockFd !== undefined) closeSync(lockFd);
+    for (const directory of directories.reverse()) closeSync(directory.fd);
+  }
+}

package/src/upgrade/paths.js

@@ -0,0 +1,81 @@
+import { closeSync, constants, fstatSync, fsyncSync, openSync } from 'node:fs';
+import { dirname, isAbsolute, sep } from 'node:path';
+import { lstatAtSync, mkdirAtSync, openAtSync } from '@chati/core';
+
+const identity = stat => `${stat.dev}:${stat.ino}`;
+const fail = (code, message) => { throw Object.assign(new Error(message), { code }); };
+
+/** Walk from a pinned root, never following even an intermediate symlink. */
+export function openUpgradeDirectory(root, relativeDirectory, { create = false, expected } = {}) {
+  const parts = relativeDirectory === '.' || relativeDirectory === '' ? [] : relativeDirectory.split(sep);
+  if (isAbsolute(relativeDirectory) || parts.some(part => !part || part === '.' || part === '..')) {
+    fail('UNSAFE_UPGRADE_PATH', 'Upgrade directory must be project-relative');
+  }
+  let fd = openSync(root, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+  const check = (path, stat) => {
+    if (!stat.isDirectory()) fail('UNSAFE_UPGRADE_PATH', 'Upgrade ancestor must be a real directory');
+    if (expected && Object.hasOwn(expected, path) && expected[path] !== identity(stat)) {
+      fail('UPGRADE_STORAGE_CHANGED', `Upgrade parent changed: ${path || '.'}`);
+    }
+  };
+  try {
+    check('', fstatSync(fd));
+    let relative = '';
+    for (const part of parts) {
+      relative = relative ? `${relative}${sep}${part}` : part;
+      let stat;
+      try { stat = lstatAtSync(fd, part); }
+      catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+        if (expected?.[relative]) fail('UPGRADE_STORAGE_CHANGED', `Upgrade parent disappeared: ${relative}`);
+        if (!create) { closeSync(fd); return undefined; }
+        mkdirAtSync(fd, part, 0o700); fsyncSync(fd);
+        stat = lstatAtSync(fd, part);
+        if (expected) expected[relative] = identity(stat);
+      }
+      if (!stat.isDirectory() || stat.isSymbolicLink()) fail('UNSAFE_UPGRADE_PATH', `Upgrade ancestor is linked or not a directory: ${relative}`);
+      check(relative, stat);
+      const next = openAtSync(fd, part, constants.O_RDONLY | constants.O_DIRECTORY);
+      if (identity(fstatSync(next)) !== identity(stat)) {
+        closeSync(next); fail('UPGRADE_STORAGE_CHANGED', `Upgrade parent changed while opening: ${relative}`);
+      }
+      closeSync(fd); fd = next;
+    }
+    return fd;
+  } catch (error) { closeSync(fd); throw error; }
+}
+
+export function snapshotUpgradeParents(root, targets) {
+  const paths = new Set(['']);
+  for (const target of targets) {
+    let path = dirname(target);
+    while (path !== '.') { paths.add(path); path = dirname(path); }
+  }
+  return Object.fromEntries([...paths].sort().map(path => {
+    const fd = openUpgradeDirectory(root, path);
+    if (fd === undefined) return [path, null];
+    try { return [path, identity(fstatSync(fd))]; } finally { closeSync(fd); }
+  }));
+}
+
+export function assertUpgradeParentsUnchanged(root, expected) {
+  for (const [path, before] of Object.entries(expected)) {
+    const fd = openUpgradeDirectory(root, path, { expected });
+    try {
+      if ((fd === undefined ? null : identity(fstatSync(fd))) !== before) {
+        fail('UPGRADE_STORAGE_CHANGED', `Upgrade parent changed: ${path || '.'}`);
+      }
+    } finally { if (fd !== undefined) closeSync(fd); }
+  }
+}
+
+export function createUpgradeParents(root, targets, expected) {
+  assertUpgradeParentsUnchanged(root, expected);
+  const current = { ...expected };
+  for (const target of targets) {
+    const fd = openUpgradeDirectory(root, dirname(target), { create: true, expected: current });
+    closeSync(fd);
+  }
+  assertUpgradeParentsUnchanged(root, current);
+  return current;
+}