chati-dev 4.5.28 → 4.5.29

package/src/installer/core.js

@@ -5,14 +5,16 @@ import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
 import { IDE_CONFIGS, IDE_TO_PROVIDER } from '../config/ide-configs.js';
 import { mergeClaudeMCPConfig, upsertManagedMcpToml } from '../config/mcp-configs.js';
-import { generateSessionYaml, generateConfigYaml, generateProjectContext, generateClaudeMd, generateClaudeLocalMd, generateCodexSkill, generateGeminiRouter, generateGrokRouter, generateGrokGovernanceRules, generateGeminiSessionLock, generateAgentsOverrideMd, generateCodexConstitutionGuardRules, generateCodexReadProtectionRules } from './templates.js';
+import { generateSessionYaml, generateConfigYaml, generateProjectContext, generateClaudeMd, generateClaudeLocalMd, generateClaudeRouter, generateCodexSkill, generateGeminiRouter, generateGrokRouter, generateGrokGovernanceRules, generateGeminiSessionLock, generateAgentsOverrideMd, generateCodexConstitutionGuardRules, generateCodexReadProtectionRules } from './templates.js';
 import { generateContextFiles } from '../config/context-file-generator.js';
 import { adaptFrameworkFile, ADAPTABLE_FILES, stripLegacyBuildSurface } from '../config/framework-adapter.js';
 import { generateClaudeSettings } from '../config/claude-settings-generator.js';
 import { generateProviderOverlays } from './provider-overlay.js';
 import { applyInstalledPathReplacement } from './path-replacement.js';
 import { verifyFrameworkSource } from './manifest.js';
+import { PACKAGE_ARTIFACT_MANIFEST, PACKAGE_ARTIFACT_SIGNATURE } from './package-artifact.js';
 import { initializeSessionDocument } from '../orchestrator/session-manager.js';
+import { withUpgradeMaintenance } from '../upgrade/maintenance.js';
 import * as yaml from 'js-yaml';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -55,6 +57,14 @@ export async function installFramework(config) {
   );
   if (initialSession.error) throw new Error(initialSession.error);
 
+  // The first session creates .chati. Hold the lease from this point through
+  // all framework/configuration writes, including direct installer API use.
+  return withUpgradeMaintenance(targetDir, () => installPreparedFramework(config, enabledProviders, version));
+}
+
+async function installPreparedFramework(config, enabledProviders, version) {
+  const { targetDir, projectType, language, selectedIDEs, selectedMCPs } = config;
+
   // 2. Create .chati.dev/ framework directory (hidden — dot prefix)
   // The source is chati.dev/ in the monorepo; installed as .chati.dev/ in user projects.
   // Text replacement during copy handles all internal path references.
@@ -120,17 +130,61 @@ export async function installFramework(config) {
     createDir(join(memoriesBase, dir));
   }
 
+  copyInstalledRuntime({ frameworkDir, providers: enabledProviders, runtimeVersion: config.runtimeVersion, version });
+
+  // Write config.yaml
+  writeFileSync(
+    join(frameworkDir, 'config.yaml'),
+    generateConfigYaml({
+      version, projectType, language, selectedIDEs,
+      allProviders: enabledProviders,
+      runtimeVersion: config.runtimeVersion,
+      installationMode: config.installationMode,
+      clickupPreflight: config.clickupPreflight,
+    }),
+    'utf-8'
+  );
+
+  // 3. Configure every CLI against its own overlay. The CLI that opens a
+  // session becomes that session's orchestrator.
+  for (const ideKey of selectedIDEs) {
+    const ideProvider = IDE_TO_PROVIDER[ideKey];
+    const hasProviderOverlay = ideProvider && enabledProviders.includes(ideProvider);
+    const orchestratorPath = hasProviderOverlay
+      ? `.chati.dev/.adapted/${ideProvider}/orchestrator/chati.md`
+      : '.chati.dev/orchestrator/chati.md';
+    await configureIDE(targetDir, ideKey, selectedMCPs, {
+      orchestratorPath,
+      isSecondary: false,
+      providerName: ideProvider,
+      runtimeVersion: config.runtimeVersion,
+    });
+  }
+
+  await finishProjectInstallation(config);
+}
+
+/** Assemble only the managed runtime. Upgrade can reuse this in private staging
+ * without regenerating project context, session, bindings or CLAUDE.md. */
+export function copyInstalledRuntime({ frameworkDir, providers = [], runtimeVersion, version, strict = false }) {
+  const isRuntimeV2 = runtimeVersion === 2;
+  const packageRoot = join(__dirname, '..', '..');
+  const packageVersion = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).version;
+  if (strict && version !== packageVersion) {
+    throw Object.assign(new Error('Runtime version must match the package being copied'), { code: 'UPGRADE_PACKAGE_VERSION_MISMATCH' });
+  }
+  const options = { strict };
   // Copy the provider-neutral canonical framework. Every enabled CLI receives
   // an explicit native overlay below, but no provider owns the source core.
-  copyFrameworkFiles(frameworkDir, null);
+  copyFrameworkFiles(frameworkDir, null, options);
 
   // Generate symmetric provider overlays. No CLI is permanently primary.
-  if (enabledProviders.length > 0) {
-    generateProviderOverlays(targetDir, FRAMEWORK_SOURCE, enabledProviders);
+  if (providers.length > 0) {
+    generateProviderOverlays(dirname(frameworkDir), FRAMEWORK_SOURCE, providers, { frameworkDir });
   }
 
   if (isRuntimeV2) {
-    pruneLegacyExecutionSurface(frameworkDir, enabledProviders);
+    pruneLegacyExecutionSurface(frameworkDir, providers);
     pruneLegacyRegistryEntities(frameworkDir);
   }
 
@@ -140,7 +194,8 @@ export async function installFramework(config) {
   // Result: every install is self-contained; no network/cache dependency at runtime.
   copyCliSource(
     join(__dirname, '..'),                         // packages/chati-dev/src/
-    join(frameworkDir, '_cli')                     // .chati.dev/_cli/
+    join(frameworkDir, '_cli'),                    // .chati.dev/_cli/
+    options
   );
 
   // The bundled CLI imports ../../framework/hooks/model-governance.js relative
@@ -149,7 +204,7 @@ export async function installFramework(config) {
   // .chati.dev/framework/hooks/ to satisfy the import path.
   copyDirVerbatim(
     join(__dirname, '..', '..', 'framework', 'hooks'),
-    join(frameworkDir, 'framework', 'hooks')
+    join(frameworkDir, 'framework', 'hooks'), options
   );
   if (isRuntimeV2) {
     rmSync(join(frameworkDir, 'framework', 'hooks', 'post-dev.js'), { force: true });
@@ -159,47 +214,34 @@ export async function installFramework(config) {
   // without relying on a node_modules tree in the user's project.
   copyCliDependencies(
     join(__dirname, '..', '..'),                    // packages/chati-dev/
-    join(frameworkDir, '_cli', 'node_modules')      // .chati.dev/_cli/node_modules/
+    join(frameworkDir, '_cli', 'node_modules'),     // .chati.dev/_cli/node_modules/
+    options
   );
 
+  // Preserve the publisher's original attestation for native runtime helpers.
+  // Their installed bytes must be checked against this signature, never blessed
+  // by hashing the installed file itself. The runtime reader verifies it before
+  // preparing any executable snapshot. Missing metadata must not stamp success.
+  for (const name of [PACKAGE_ARTIFACT_MANIFEST, PACKAGE_ARTIFACT_SIGNATURE]) {
+    const source = join(packageRoot, name);
+    const stat = lstatSync(source);
+    if (!stat.isFile() || stat.nlink !== 1) unsafeManagedPath(source, 'package attestation must be a single-link regular file');
+    copySafeManagedFile(source, join(frameworkDir, '_cli', name));
+  }
+
   // v4.3.1+ — Write version stamp so chati-router.js can detect bundle/canonical
   // mismatch on subsequent invocations. Pre-v4.3.1 installs lack this file;
   // mismatch detection silent-skips when it's missing (graceful degradation).
   writeFileSync(
     join(frameworkDir, '_cli', 'version.json'),
-    JSON.stringify({ version, bundled_at: new Date().toISOString() }, null, 2),
+    JSON.stringify({ version, package_version: packageVersion, bundled_at: new Date().toISOString(), maintenance_protocol: 1 }, null, 2),
     'utf-8'
   );
 
-  // Write config.yaml
-  writeFileSync(
-    join(frameworkDir, 'config.yaml'),
-    generateConfigYaml({
-      version, projectType, language, selectedIDEs,
-      allProviders: enabledProviders,
-      runtimeVersion: config.runtimeVersion,
-      installationMode: config.installationMode,
-      clickupPreflight: config.clickupPreflight,
-    }),
-    'utf-8'
-  );
-
-  // 3. Configure every CLI against its own overlay. The CLI that opens a
-  // session becomes that session's orchestrator.
-  for (const ideKey of selectedIDEs) {
-    const ideProvider = IDE_TO_PROVIDER[ideKey];
-    const hasProviderOverlay = ideProvider && enabledProviders.includes(ideProvider);
-    const orchestratorPath = hasProviderOverlay
-      ? `.chati.dev/.adapted/${ideProvider}/orchestrator/chati.md`
-      : '.chati.dev/orchestrator/chati.md';
-    await configureIDE(targetDir, ideKey, selectedMCPs, {
-      orchestratorPath,
-      isSecondary: false,
-      providerName: ideProvider,
-      runtimeVersion: config.runtimeVersion,
-    });
-  }
+}
 
+async function finishProjectInstallation(config) {
+  const { targetDir, projectName, projectType, language, selectedIDEs } = config;
   const hasClaude = selectedIDEs.includes('claude-code');
   // 4. Generate the provider-neutral project context. Harness files consume
   // this artifact and never become the source for one another.
@@ -398,8 +440,8 @@ const TEXT_EXTENSIONS = new Set(['.md', '.js', '.yaml', '.yml', '.json', '.html'
  * 1. Path replacement (chati.dev/ → .chati.dev/, artifacts/ at root)
  * 2. Provider adaptation for non-Claude providers
  */
-function copyDirRecursive(srcDir, destDir, provider, relBase = '') {
-  if (!existsSync(srcDir)) return;
+function copyDirRecursive(srcDir, destDir, provider, relBase = '', options = {}) {
+  if (!existsSync(srcDir) && !options.strict) return;
   createSafeManagedDirectory(destDir);
 
   const entries = readdirSync(srcDir, { withFileTypes: true });
@@ -411,7 +453,7 @@ function copyDirRecursive(srcDir, destDir, provider, relBase = '') {
     if (entry.isDirectory()) {
       // Skip artifacts/ — those live at project root, not inside .chati.dev/
       if (entry.name === 'artifacts') continue;
-      copyDirRecursive(srcPath, destPath, provider, relPath);
+      copyDirRecursive(srcPath, destPath, provider, relPath, options);
     } else if (entry.isFile()) {
       const ext = entry.name.includes('.') ? '.' + entry.name.split('.').pop() : '';
       const isText = TEXT_EXTENSIONS.has(ext);
@@ -429,7 +471,7 @@ function copyDirRecursive(srcDir, destDir, provider, relBase = '') {
         // Binary file: direct copy
         copySafeManagedFile(srcPath, destPath);
       }
-    }
+    } else if (options.strict) unsafeManagedPath(srcPath, 'source must contain only regular files and directories');
   }
 }
 
@@ -442,13 +484,13 @@ function copyDirRecursive(srcDir, destDir, provider, relBase = '') {
  * @param {string} destDir - Target framework directory (e.g., {project}/chati.dev/)
  * @param {string} provider - Primary provider for text adaptation ('claude' | 'gemini' | 'codex')
  */
-export function copyFrameworkFiles(destDir, provider = null) {
-  if (!existsSync(FRAMEWORK_SOURCE)) return;
+export function copyFrameworkFiles(destDir, provider = null, options = {}) {
+  if (!existsSync(FRAMEWORK_SOURCE) && !options.strict) return;
 
   // Copy loose root files (with path replacement)
   for (const file of FRAMEWORK_ROOT_FILES) {
     const src = join(FRAMEWORK_SOURCE, file);
-    if (!existsSync(src)) continue;
+    if (!existsSync(src) && !options.strict) continue;
     const dest = join(destDir, file);
     createSafeManagedDirectory(dirname(dest));
     let content = readFileSync(src, 'utf-8');
@@ -463,7 +505,7 @@ export function copyFrameworkFiles(destDir, provider = null) {
   for (const dir of FRAMEWORK_DIRS_TO_COPY) {
     const srcDir = join(FRAMEWORK_SOURCE, dir);
     const destSubDir = join(destDir, dir);
-    copyDirRecursive(srcDir, destSubDir, provider, dir);
+    copyDirRecursive(srcDir, destSubDir, provider, dir, options);
   }
 }
 
@@ -480,47 +522,7 @@ async function configureIDE(targetDir, ideKey, selectedMCPs, options = {}) {
 
   if (ideKey === 'claude-code') {
     // Thin router
-    const routerContent = `# /chati — Deterministic Router
-
-## STEP 0 — Run the deterministic pipeline router (MUST be first)
-
-Run via Bash:
-\`\`\`
-node .chati.dev/orchestrator/chati-router.js --harness claude
-\`\`\`
-
-Parse the JSON output. This single command already handled: license validation, integrity check, session state, pipeline routing, and team registration (if needed). You do NOT need to run any of these separately.
-
-### If \`ok\` is false:
-
-| \`error\` value | What to tell the user |
-|---|---|
-| \`license_invalid\` | Display \`license.reason\` as a friendly message. STOP. |
-| \`license_guard_missing\` | "License enforcement is missing. Reinstall with: npx chati-dev init". STOP. |
-| \`integrity_failed\` | "License enforcement was tampered with. Reinstall with: npx chati-dev init". STOP. |
-| anything else | Display error. STOP. |
-
-### If \`ok\` is true:
-
-1. Use \`session.language\` for every visible response, preface, progress message, question and error, starting with the first response (pt = Português, en = English, es = Español, fr = Français).
-2. Read the full orchestrator at \`${orchestratorPath || '.chati.dev/orchestrator/chati.md'}\`.
-3. The \`action\` field tells you what to do. Go to the matching "Action:" section in the orchestrator.
-4. **If \`action\` is \`spawn_team\`**: the team is ALREADY registered (Step 1 already ran as code). The \`team\` object contains \`team_id\`, \`task_list_path\`, \`mailbox_path\`, \`members\`. Go directly to "Action: Spawn Team" Step 2 and use these values in the agent prompts. DO NOT run \`orchestrate spawn-team\` again — it already ran.
-5. **If \`action\` is \`setup\`**: this is a new project. Follow "Action: Setup".
-6. For any other action: follow the matching section in the orchestrator.
-
-**The \`pipeline\` object contains the full JSON from \`orchestrate next\`.** Use its fields (agent_file, spawn_command, handoff_status, etc.) as documented in the orchestrator.
-
-**Pending interaction invariant:** If \`action\` is \`resume_pending_interaction\`,
-do not execute a provider command. Display exactly \`pipeline.question\`, with
-no preface, summary or paraphrase. After the user answers, write
-\`{"response":"<exact user response>"}\` to \`pipeline.response_file\` using the
-native file-write tool, never a shell command. Then execute
-\`pipeline.deferred_spawn_command\` exactly once and unchanged. Never execute a
-command merely because a command-shaped field is present.
-
-**User input:** $ARGUMENTS
-`;
+    const routerContent = generateClaudeRouter({ orchestratorPath });
     writeFileSync(join(targetDir, '.claude', 'commands', 'chati.md'), routerContent, 'utf-8');
 
     // .claude/settings.json — wires the 10 chati.dev hooks into Claude Code's
@@ -1057,8 +1059,8 @@ function copySafeManagedFile(source, destination) {
  * Used to bundle the CLI source into the user's .chati.dev/_cli/ folder so
  * the framework runs self-contained (no `npx chati-dev` dependency).
  */
-export function copyCliSource(srcDir, destDir) {
-  if (!existsSync(srcDir)) return;
+export function copyCliSource(srcDir, destDir, options = {}) {
+  if (!existsSync(srcDir) && !options.strict) return;
   createSafeManagedDirectory(destDir);
   const entries = readdirSync(srcDir);
   for (const entry of entries) {
@@ -1067,10 +1069,12 @@ export function copyCliSource(srcDir, destDir) {
     const srcPath = join(srcDir, entry);
     const destPath = join(destDir, entry);
     let stat;
-    try { stat = statSync(srcPath); } catch { continue; }
+    try { stat = options.strict ? lstatSync(srcPath) : statSync(srcPath); }
+    catch (error) { if (options.strict) throw error; continue; }
     if (stat.isDirectory()) {
-      copyCliSource(srcPath, destPath);
+      copyCliSource(srcPath, destPath, options);
     } else {
+      if (options.strict && !stat.isFile()) unsafeManagedPath(srcPath, 'CLI source must be a regular file');
       copySafeManagedFile(srcPath, destPath);
     }
   }
@@ -1079,20 +1083,21 @@ export function copyCliSource(srcDir, destDir) {
 /**
  * Recursively copy a directory verbatim (used for bundling node_modules trees).
  */
-function copyDirVerbatim(srcDir, destDir) {
-  if (!existsSync(srcDir)) return;
+function copyDirVerbatim(srcDir, destDir, options = {}) {
+  if (!existsSync(srcDir) && !options.strict) return;
   createSafeManagedDirectory(destDir);
   for (const entry of readdirSync(srcDir)) {
     const srcPath = join(srcDir, entry);
     const destPath = join(destDir, entry);
     let stat;
-    try { stat = statSync(srcPath); } catch { continue; }
+    try { stat = statSync(srcPath); } catch (error) { if (options.strict) throw error; continue; }
     if (stat.isDirectory()) {
-      copyDirVerbatim(srcPath, destPath);
+      copyDirVerbatim(srcPath, destPath, options);
     } else {
+      if (options.strict && !stat.isFile()) unsafeManagedPath(srcPath, 'dependency source must be a regular file');
       try { copySafeManagedFile(srcPath, destPath); }
       catch (error) {
-        if (error?.code === 'UNSAFE_INSTALLATION_TARGET') throw error;
+        if (options.strict || error?.code === 'UNSAFE_INSTALLATION_TARGET') throw error;
         /* skip unreadable source material */
       }
     }
@@ -1108,11 +1113,11 @@ function copyDirVerbatim(srcDir, destDir) {
  * which works whether the package is hoisted or nested in the user's
  * node_modules (npx cache, npm install, etc.).
  */
-export function copyCliDependencies(pkgDir, destNodeModules) {
+export function copyCliDependencies(pkgDir, destNodeModules, options = {}) {
   let pkg;
   try {
     pkg = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf-8'));
-  } catch { return; }
+  } catch (error) { if (options.strict) throw error; return; }
   const deps = [
     ...Object.keys(pkg.dependencies || {}),
     ...Object.keys(pkg.optionalDependencies || {}),
@@ -1121,16 +1126,17 @@ export function copyCliDependencies(pkgDir, destNodeModules) {
 
   // Resolve each dep from the package.json location (works for hoisted + nested layouts).
    
-  const require = createRequire(join(pkgDir, 'package.json'));
   createSafeManagedDirectory(destNodeModules);
 
   const visited = new Set();
-  const queue = [...deps];
+  const resolvedPackages = new Map();
+  const copiedTargets = new Map();
+  const queue = deps.map(name => ({ name, from: pkgDir, destinationParent: dirname(destNodeModules), optional: Object.hasOwn(pkg.optionalDependencies || {}, name) }));
 
   while (queue.length > 0) {
-    const depName = queue.shift();
-    if (visited.has(depName)) continue;
-    visited.add(depName);
+    const { name: depName, optional, from, destinationParent } = queue.shift();
+    if (!options.strict && visited.has(depName)) continue;
+    const require = createRequire(join(options.strict ? from : pkgDir, 'package.json'));
 
     let depDir;
     try {
@@ -1153,19 +1159,53 @@ export function copyCliDependencies(pkgDir, destNodeModules) {
             } catch { /* keep walking */ }
           }
         }
-      } catch { continue; }
-      if (!depDir) continue;
+      } catch { /* required dependency failures are handled below */ }
+      if (!depDir) {
+        if (options.strict && !optional) {
+          throw Object.assign(new Error(`Required runtime dependency is unavailable: ${depName}`), { code: 'RUNTIME_DEPENDENCY_MISSING' });
+        }
+        // An optional miss must not hide a later required reference.
+        continue;
+      }
     }
+    let destination = join(destNodeModules, depName);
+    if (options.strict && resolvedPackages.has(depName) && resolvedPackages.get(depName) !== depDir) {
+      // Two consumers may require different installed versions of the same
+      // dependency. Preserve Node's nearest-ancestor resolution, never flatten
+      // the second version over the first or silently use the root version.
+      destination = join(destinationParent, 'node_modules', depName);
+      for (let parent = destinationParent; parent !== dirname(destNodeModules); parent = dirname(parent)) {
+        const ancestor = join(parent, 'node_modules', depName);
+        if (copiedTargets.has(ancestor)) {
+          if (copiedTargets.get(ancestor) === depDir) destination = ancestor;
+          break;
+        }
+        if (parent === dirname(parent)) break;
+      }
+    }
+    if (options.strict && copiedTargets.has(destination)) {
+      if (copiedTargets.get(destination) !== depDir) {
+        throw Object.assign(new Error(`Conflicting runtime dependency destination: ${depName}`), { code: 'RUNTIME_DEPENDENCY_LAYOUT_CONFLICT' });
+      }
+      continue;
+    }
+    if (!options.strict && visited.has(depName)) continue;
+    visited.add(depName);
+    if (!resolvedPackages.has(depName)) resolvedPackages.set(depName, depDir);
+    copiedTargets.set(destination, depDir);
     const depPkgJsonPath = join(depDir, 'package.json');
-    copyDirVerbatim(depDir, join(destNodeModules, depName));
+    copyDirVerbatim(depDir, destination, options);
 
     // Include transitive deps
     try {
       const depPkg = JSON.parse(readFileSync(depPkgJsonPath, 'utf-8'));
       for (const t of Object.keys(depPkg.dependencies || {})) {
-        if (!visited.has(t)) queue.push(t);
+        if (options.strict || !visited.has(t)) queue.push({ name: t, from: depDir, destinationParent: destination, optional: Object.hasOwn(depPkg.optionalDependencies || {}, t) });
+      }
+      for (const t of Object.keys(depPkg.optionalDependencies || {})) {
+        if ((options.strict || !visited.has(t)) && !Object.hasOwn(depPkg.dependencies || {}, t)) queue.push({ name: t, from: depDir, destinationParent: destination, optional: true });
       }
-    } catch { /* continue */ }
+    } catch (error) { if (options.strict) throw error; }
   }
 }
 

package/src/installer/package-artifact.js

@@ -165,6 +165,13 @@ export function buildPackageArtifactManifest(packageRoot, { createdAt = new Date
     if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1) {
       throw new Error(`publish artifact entry must be a single-link regular file: ${relativePath}`);
     }
+    // A valid signature over an unstable npm archive is not sufficient: npm
+    // renames .gitignore and adds read bits to owner-only files on install.
+    // Refuse such inputs at the producer. Never transform the signed identity
+    // in the installed reader or silently chmod the publisher's source tree.
+    if (relativePath.split('/').includes('.gitignore') || ![0o644, 0o755].includes(mode)) {
+      throw new Error(`publish artifact is not install-stable: ${relativePath}; prepare a private source copy with 0644/0755 modes and no bundled .gitignore`);
+    }
     files[relativePath] = Object.freeze({
       // npm normalizes file modes in the tarball. Signing the on-disk source
       // mode would reject a clean install when its umask differs, even though

package/src/installer/preflight.js

@@ -13,6 +13,15 @@
 
 import { execSync } from 'child_process';
 
+/** Platform eligibility only, not proof of execution containment or full E2E. */
+export function assertInstallerPlatformSupported() {
+  if (['linux', 'darwin'].includes(process.platform)) return;
+  const message = process.platform === 'win32'
+    ? 'Native Windows installation is not supported. WSL 2 is the proposed Linux execution route, but it has not been validated for this release. Setup stopped before license activation or dependency installation.'
+    : `Installation is not supported on ${process.platform}. Setup stopped before license activation or dependency installation.`;
+  throw Object.assign(new Error(message), { code: 'UNSUPPORTED_INSTALLATION_PLATFORM' });
+}
+
 /**
  * @typedef {{ name: string, status: 'pass'|'fail'|'warn', version?: string, message: string }} PreflightCheck
  * @typedef {{ passed: boolean, checks: PreflightCheck[] }} PreflightResult
@@ -25,6 +34,10 @@ import { execSync } from 'child_process';
  * @returns {Promise<PreflightResult>}
  */
 export async function runPreflightCheck(options = {}) {
+  try { assertInstallerPlatformSupported(); }
+  catch (error) {
+    return { passed: false, checks: [{ name: 'platform', status: 'fail', message: error.message }] };
+  }
   const checks = [];
   let mandatoryFailed = false;
 

package/src/installer/provider-overlay.js

@@ -29,9 +29,8 @@ import { applyInstalledPathReplacement } from './path-replacement.js';
  * @param {string[]} allProviders - All CLI provider names
  * @returns {{ generated: string[], skipped: string[] }}
  */
-export function generateProviderOverlays(targetDir, frameworkSource, allProviders) {
+export function generateProviderOverlays(targetDir, frameworkSource, allProviders, { frameworkDir = join(targetDir, '.chati.dev') } = {}) {
   const result = { generated: [], skipped: [] };
-  const frameworkDir = join(targetDir, '.chati.dev');
 
   for (const provider of allProviders) {
     const overlayDir = join(frameworkDir, '.adapted', provider);

package/src/installer/templates.js

@@ -1,4 +1,5 @@
 import * as yaml from 'js-yaml';
+import { DELEGATED_EXECUTION_BOUNDARY } from '../utils/execution-role.js';
 
 const IDE_PROVIDER_MAP = Object.freeze({
   'claude-code': 'claude',
@@ -221,12 +222,61 @@ Type \`/chati\` to start or resume Chati.dev.
  * The user invokes with $chati or Codex auto-detects based on description.
  * Also reads AGENTS.md for project context (auto-generated by context-file-generator).
  */
+/** Render only the managed Claude entry command; no project configuration writes. */
+export function generateClaudeRouter(options = {}) {
+  const { orchestratorPath } = options;
+  return `# /chati — Deterministic Router
+
+${DELEGATED_EXECUTION_BOUNDARY}
+
+## STEP 0 — Run the deterministic pipeline router (MUST be first)
+
+Run via Bash:
+\`\`\`
+node .chati.dev/orchestrator/chati-router.js --harness claude
+\`\`\`
+
+Parse the JSON output. This single command already handled: license validation, integrity check, session state, pipeline routing, and team registration (if needed). You do NOT need to run any of these separately.
+
+### If \`ok\` is false:
+
+| \`error\` value | What to tell the user |
+|---|---|
+| \`license_invalid\` | Display \`license.reason\` as a friendly message. STOP. |
+| \`license_guard_missing\` | "License enforcement is missing. Reinstall with: npx chati-dev init". STOP. |
+| \`integrity_failed\` | "License enforcement was tampered with. Reinstall with: npx chati-dev init". STOP. |
+| anything else | Display error. STOP. |
+
+### If \`ok\` is true:
+
+1. Use \`session.language\` for every visible response, preface, progress message, question and error, starting with the first response (pt = Português, en = English, es = Español, fr = Français).
+2. Read the full orchestrator at \`${orchestratorPath || '.chati.dev/orchestrator/chati.md'}\`.
+3. The \`action\` field tells you what to do. Go to the matching "Action:" section in the orchestrator.
+4. **If \`action\` is \`spawn_team\`**: the team is ALREADY registered (Step 1 already ran as code). The \`team\` object contains \`team_id\`, \`task_list_path\`, \`mailbox_path\`, \`members\`. Go directly to "Action: Spawn Team" Step 2 and use these values in the agent prompts. DO NOT run \`orchestrate spawn-team\` again — it already ran.
+5. **If \`action\` is \`setup\`**: this is a new project. Follow "Action: Setup".
+6. For any other action: follow the matching section in the orchestrator.
+
+**The \`pipeline\` object contains the full JSON from \`orchestrate next\`.** Use its fields (agent_file, spawn_command, handoff_status, etc.) as documented in the orchestrator.
+
+**Pending interaction invariant:** If \`action\` is \`resume_pending_interaction\`,
+do not execute a provider command. Display exactly \`pipeline.question\`, with
+no preface, summary or paraphrase. After the user answers, write
+\`{"response":"<exact user response>"}\` to \`pipeline.response_file\` using the
+native file-write tool, never a shell command. Then execute
+\`pipeline.deferred_spawn_command\` exactly once and unchanged. Never execute a
+command merely because a command-shaped field is present.
+
+**User input:** $ARGUMENTS
+`;
+}
+
 export function generateCodexSkill(options = {}) {
   const orchPath = options.orchestratorPath || '.chati.dev/orchestrator/chati.md';
   return `---
 name: chati
 description: >
   Use this skill when the user wants to start or continue a Chati.dev session.
+  It is not for subprocesses already delegated an agent/task by the parent runtime.
   This activates the orchestrator which routes to the correct agent in the pipeline.
   Invoke when the user mentions chati, /chati, or wants to discover, plan, execute, or release a project.
   Do NOT use for general coding questions unrelated to the Chati.dev pipeline.
@@ -234,6 +284,8 @@ description: >
 
 # Chati.dev Orchestrator
 
+${DELEGATED_EXECUTION_BOUNDARY}
+
 ## STEP 0 — Run the deterministic router (MUST be the first action)
 
 Use the shell in the current project directory and run:
@@ -315,6 +367,8 @@ export function generateGeminiRouter(options = {}) {
   const orchPath = options.orchestratorPath || '.chati.dev/orchestrator/chati.md';
   return `description = "Activate Chati.dev orchestrator"
 prompt = """
+${DELEGATED_EXECUTION_BOUNDARY}
+
 STEP 0: Run the deterministic router before reading mutable state or responding:
 
 node .chati.dev/orchestrator/chati-router.js --harness gemini
@@ -348,6 +402,8 @@ export function generateGrokRouter(options = {}) {
   const orchPath = options.orchestratorPath || '.chati.dev/orchestrator/chati.md';
   return `# Chati.dev Orchestrator
 
+${DELEGATED_EXECUTION_BOUNDARY}
+
 ## STEP 0: Run the deterministic router first
 
 Before reading mutable session files or responding, run:
@@ -397,6 +453,8 @@ User input: $ARGUMENTS
 export function generateGrokGovernanceRules() {
   return `# Chati.dev Grok Governance
 
+${DELEGATED_EXECUTION_BOUNDARY}
+
 For every CHATI.DEV entry or continuation, run this boundary before reading
 mutable CHATI state or taking an action:
 

package/src/installer-v2/catalog-client.js

@@ -1,7 +1,7 @@
 import { createPublicKey, randomUUID, verify as cryptoVerify } from 'node:crypto';
 import {
   closeSync, constants, fstatSync, fsyncSync, linkSync, lstatSync,
-  mkdirSync, openSync, readFileSync, readSync, realpathSync, renameSync, unlinkSync, writeSync,
+  mkdirSync, openSync, readFileSync, readdirSync, readSync, realpathSync, renameSync, unlinkSync, writeSync,
 } from 'node:fs';
 import { basename, dirname, join, parse, relative, resolve, sep } from 'node:path';
 import { isIP } from 'node:net';
@@ -343,6 +343,36 @@ export function replaceInstallationStorageFile(path, content, source) {
   return replaceInstallationArtifact(path, content, source);
 }
 
+/** Enumerate only the pinned directory; callers still authenticate each entry. */
+export function listSafeInstallationStorageFiles(path) {
+  let directory;
+  try { directory = openPinnedInstallationDirectory(path); }
+  catch (error) { if (error?.code === 'ENOENT') return []; throw error; }
+  try {
+    assertPinnedInstallationDirectory(directory);
+    const names = readdirSync(directory.reference);
+    if (names.length > 10000) throw catalogError('INSTALLATION_STORAGE_SIZE_LIMIT', 'managed storage exceeds its bounded entry budget');
+    return names.sort();
+  } finally { closeSync(directory.descriptor); }
+}
+
+/** Delete only the exact, already authenticated snapshot selected by the caller. */
+export function removeSafeInstallationStorageFile(path, source) {
+  const directory = openPinnedInstallationDirectory(dirname(path));
+  try {
+    runInstallationStorageSecurityTestHook('beforeRemovalCommit', { path, directory: directory.absolute });
+    assertPinnedInstallationDirectory(directory);
+    const current = readSafeInstallationEntry(directory, basename(path), { allowMissing: true });
+    if (current === null) return false;
+    if (!sameSnapshot(current.stat, source.stat) || current.content !== source.content) {
+      throw catalogError('INSTALLATION_STORAGE_CONFLICT', 'managed storage changed before removal');
+    }
+    unlinkSync(installationEntryPath(directory, basename(path)));
+    fsyncSync(directory.descriptor);
+    return true;
+  } finally { closeSync(directory.descriptor); }
+}
+
 export function readInstallationArtifactFile(projectDir, { allowMissing = true } = {}) {
   const directory = resolve(projectDir, '.chati/v2');
   return readSafeInstallationFile(join(directory, 'installation.json'), { allowMissing });