chati-dev 4.3.1 → 4.4.1

package/src/orchestrator/pipeline-manager.js

@@ -9,6 +9,8 @@ import { initCollector, track as telemetryTrack, flush as telemetryFlush } from
 import { sendEvents } from '../telemetry/sender.js';
 import { getTelemetryConfig, isEnabled as isTelemetryEnabled } from '../telemetry/config.js';
 import { getCurrentVersion } from '../upgrade/checker.js';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
 
 /**
  * Pipeline phases in order.
@@ -107,6 +109,35 @@ const QA_THRESHOLDS = {
   'qa-visual': QA_VISUAL_THRESHOLD,
 };
 
+/**
+ * Resolve the gate thresholds from the canonical rubric file
+ * (chati.dev/data/qa-rubrics.yaml), falling back to the constants above when
+ * the file is unavailable (for example in a unit test with no project on disk).
+ * The constants stay as the documented fallback, not as a second source of
+ * truth: when the rubric file is present its values win. Cached per directory.
+ */
+const _qaThresholdCache = new Map();
+function loadQaThresholds(projectDir) {
+  const dir = projectDir || process.cwd();
+  if (_qaThresholdCache.has(dir)) return _qaThresholdCache.get(dir);
+  const candidates = ['.chati.dev', 'chati.dev'].map(
+    (d) => join(dir, d, 'data', 'qa-rubrics.yaml')
+  );
+  let raw = null;
+  for (const p of candidates) {
+    if (existsSync(p)) { try { raw = readFileSync(p, 'utf-8'); break; } catch { /* fall through */ } }
+  }
+  const out = { ...QA_THRESHOLDS };
+  if (raw) {
+    for (const key of Object.keys(QA_THRESHOLDS)) {
+      const m = raw.match(new RegExp(`^\\s*${key}:\\s*(\\d+)`, 'm'));
+      if (m) out[key] = parseInt(m[1], 10);
+    }
+  }
+  _qaThresholdCache.set(dir, out);
+  return out;
+}
+
 /**
  * Route a failing QA to the correct rework target via Fault Vector Protocol.
  *
@@ -180,16 +211,6 @@ function correctionKey(qaAgent, target) {
   return `${qaAgent}->${target}`;
 }
 
-/**
- * Check if a QA agent's score is below its threshold.
- */
-function qaScoreBelowThreshold(qaAgent, score) {
-  const threshold = QA_THRESHOLDS[qaAgent];
-  if (threshold === undefined) return false;
-  if (score === null || score === undefined) return true;
-  return score < threshold;
-}
-
 /**
  * Initialize a new pipeline for a project.
  *
@@ -690,6 +711,7 @@ function getFirstAgentInPhase(state, phase) {
  */
 export function checkPhaseTransition(pipelineState) {
   const { phase, agents } = pipelineState;
+  const T = loadQaThresholds(pipelineState.targetDir);
 
   // Check based on current phase
   if (phase === 'discover') {
@@ -731,15 +753,15 @@ export function checkPhaseTransition(pipelineState) {
       return {
         canAdvance: false,
         reason: 'QA-Planning not yet completed',
-        requiredScore: QA_PLANNING_THRESHOLD,
+        requiredScore: T['qa-planning'],
       };
     }
 
-    if (qaPlanning.score === null || qaPlanning.score < QA_PLANNING_THRESHOLD) {
+    if (qaPlanning.score === null || qaPlanning.score < T['qa-planning']) {
       return {
         canAdvance: false,
-        reason: `QA-Planning score ${qaPlanning.score || 0} below threshold ${QA_PLANNING_THRESHOLD}`,
-        requiredScore: QA_PLANNING_THRESHOLD,
+        reason: `QA-Planning score ${qaPlanning.score || 0} below threshold ${T['qa-planning']}`,
+        requiredScore: T['qa-planning'],
       };
     }
 
@@ -795,15 +817,15 @@ export function checkPhaseTransition(pipelineState) {
       return {
         canAdvance: false,
         reason: 'QA-Implementation not yet completed',
-        requiredScore: QA_IMPLEMENTATION_THRESHOLD,
+        requiredScore: T['qa-implementation'],
       };
     }
 
-    if (qaImpl.score === null || qaImpl.score < QA_IMPLEMENTATION_THRESHOLD) {
+    if (qaImpl.score === null || qaImpl.score < T['qa-implementation']) {
       return {
         canAdvance: false,
-        reason: `QA-Implementation score ${qaImpl.score || 0} below threshold ${QA_IMPLEMENTATION_THRESHOLD}`,
-        requiredScore: QA_IMPLEMENTATION_THRESHOLD,
+        reason: `QA-Implementation score ${qaImpl.score || 0} below threshold ${T['qa-implementation']}`,
+        requiredScore: T['qa-implementation'],
       };
     }
 
@@ -813,14 +835,14 @@ export function checkPhaseTransition(pipelineState) {
         return {
           canAdvance: false,
           reason: 'QA-Visual not yet completed',
-          requiredScore: 90,
+          requiredScore: T['qa-visual'],
         };
       }
-      if (qaVisual.score === null || qaVisual.score < 90) {
+      if (qaVisual.score === null || qaVisual.score < T['qa-visual']) {
         return {
           canAdvance: false,
-          reason: `QA-Visual score ${qaVisual.score || 0} below threshold 90`,
-          requiredScore: 90,
+          reason: `QA-Visual score ${qaVisual.score || 0} below threshold ${T['qa-visual']}`,
+          requiredScore: T['qa-visual'],
         };
       }
     }

package/src/orchestrator/session-manager.js

@@ -6,11 +6,24 @@
  */
 
 import yaml from 'js-yaml';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
 
 const SESSION_FILE = '.chati/session.yaml';
 
+/**
+ * Atomic write helper. Writes `content` to a sibling `.tmp` file and then
+ * renames it into place. If the process is killed mid-write the original
+ * remains intact. Same-FS rename on POSIX is atomic; on Windows it's
+ * best-effort. Mirrors the pattern used by `chati.dev/hooks/prism-engine.js`
+ * `writeBackSession` to keep both hook and CLI write paths consistent.
+ */
+function writeFileAtomic(path, content, encoding = 'utf-8') {
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, content, encoding);
+  renameSync(tmp, path);
+}
+
 /**
  * Default session template.
  */
@@ -26,6 +39,12 @@ const DEFAULT_SESSION = {
   started_at: null,
   current_agent: '',
   pipeline_position: 0,
+  // execution_mode is a string enum ('interactive' | 'autonomous') per
+  // session.schema.json. Article XVIII deprecation (2026-04-18) collapsed
+  // the old 4-value execution_profile enum into this binary form. Per-
+  // transition metadata (setAt, reason) lives in mode_transitions[] below,
+  // not on this field. mode-manager.js was historically reading it as an
+  // object — that path was normalized to read the string in 2026-05.
   execution_mode: 'interactive',
   user_level: 'auto',
   user_level_confidence: 0.0,
@@ -135,7 +154,7 @@ export function initSession(projectDir, options = {}) {
       noRefs: true,
     });
 
-    writeFileSync(sessionPath, yamlContent, 'utf-8');
+    writeFileAtomic(sessionPath, yamlContent);
 
     return {
       created: true,
@@ -216,6 +235,14 @@ export function migrateSession(session) {
     };
   }
 
+  // Defensive seed: ensure execution_mode is always present after migration.
+  // An unrecognized execution_profile (e.g. a hand-edited 'custom') or no
+  // profile at all used to leave the field absent, so validateSession could
+  // not catch it and every subsequent load re-migrated the same session. The
+  // profile mapping below can still promote this to 'autonomous'. Guarded so
+  // an existing 'autonomous' value is preserved.
+  if (!session.execution_mode) session.execution_mode = 'interactive';
+
   // Article XVIII deprecation (2026-04-18): collapse execution_profile into
   // execution_mode per the migration table. Runs LAST so it overrides any
   // default seeded above. See constitution Article XVIII for rationale.
@@ -232,6 +259,20 @@ export function migrateSession(session) {
     delete session.profile_transitions;
   }
 
+  // execution_mode normalization (2026-05): the schema declares this field
+  // as a string enum ('interactive' | 'autonomous'), and all CLI/dashboard/
+  // hook consumers treat it as a string. Earlier `setExecutionMode` writes
+  // accidentally produced an object shape `{ mode, setAt, reason }` that
+  // only `mode-manager.js#getCurrentMode` understood. Sessions that ran
+  // through that path stored the object form; flatten them back to a string
+  // here so subsequent reads from cli.js / dashboard / templates work.
+  // Per-transition metadata lives in mode_transitions[] (already present).
+  if (session.execution_mode && typeof session.execution_mode === 'object' && !Array.isArray(session.execution_mode)) {
+    const inner = session.execution_mode.mode;
+    const map = { 'human-in-the-loop': 'interactive', interactive: 'interactive', autonomous: 'autonomous' };
+    session.execution_mode = map[inner] || 'interactive';
+  }
+
   return { migrated: true, fromVersion, toVersion: CURRENT_SCHEMA_VERSION };
 }
 
@@ -260,9 +301,16 @@ export function loadSession(projectDir) {
     if (migration.migrated) {
       try {
         const yamlContent = yaml.dump(session, { lineWidth: -1, noRefs: true });
-        writeFileSync(sessionPath, yamlContent, 'utf-8');
-      } catch { /* expected: operation may fail gracefully */
-        // Migration write failed — continue with migrated in-memory session
+        writeFileAtomic(sessionPath, yamlContent);
+      } catch (writeErr) {
+        // Migration write-back failed (read-only filesystem, EACCES). The
+        // session continues with the migrated in-memory copy, but disk stays
+        // on the old schema and re-migrates on every load. Surface it so the
+        // user can fix the cause (make .chati/ writable) instead of it failing
+        // silently. The production path (writable FS) never reaches here.
+        process.stderr.write(
+          `[chati] warning: session migrated in memory but could not be written back to ${sessionPath} (${writeErr.code || writeErr.message}); it will re-migrate on every load until the directory is writable\n`
+        );
       }
     }
 
@@ -329,7 +377,7 @@ export function updateSession(projectDir, updates) {
       noRefs: true,
     });
 
-    writeFileSync(sessionPath, yamlContent, 'utf-8');
+    writeFileAtomic(sessionPath, yamlContent);
 
     return {
       saved: true,
@@ -392,7 +440,7 @@ function writeSessionToDisk(projectDir, session) {
   const sessionPath = join(projectDir, SESSION_FILE);
   try {
     const yamlContent = yaml.dump(session, { lineWidth: -1, noRefs: true });
-    writeFileSync(sessionPath, yamlContent, 'utf-8');
+    writeFileAtomic(sessionPath, yamlContent);
     return { saved: true, session };
   } catch (err) {
     return { saved: false, error: `Failed to write session: ${err.message}` };
@@ -875,7 +923,7 @@ export function validateSession(projectDir) {
   const session = loadResult.session;
 
   // Validate required fields
-  const requiredFields = ['schema_version', 'version', 'mode', 'language', 'project_type', 'agents'];
+  const requiredFields = ['schema_version', 'version', 'mode', 'execution_mode', 'language', 'project_type', 'agents'];
   for (const field of requiredFields) {
     if (!session[field]) {
       return {

package/src/telemetry/sender.js

@@ -5,30 +5,19 @@
  * Fire-and-forget: never blocks the user workflow, fails silently.
  */
 
-import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
-import { homedir } from 'os';
-
 // ---------------------------------------------------------------------------
 // Default Endpoint
 // ---------------------------------------------------------------------------
 
 export const DEFAULT_ENDPOINT = 'https://chati.dev/api/telemetry';
 
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function readGlobalLicenseKey() {
-  try {
-    const p = join(homedir(), '.chati-dev', 'license.yaml');
-    if (!existsSync(p)) return null;
-    const content = readFileSync(p, 'utf-8');
-    const match = content.match(/^key:\s*(.+)$/m);
-    const key = match?.[1]?.trim();
-    return key && key !== 'null' ? key : null;
-  } catch { return null; }
-}
+// Note: the prior implementation read the local license key from
+// `~/.chati-dev/license.yaml` and shipped it inside every telemetry POST as
+// `license_key`. That sent a paying user's credential to the analytics
+// endpoint on every install/pipeline event — outside the per-event PII
+// scrubber. Removed (2026-05). Server-side attribution should be derived
+// from the validated license session correlated to `anonymousId`, never from
+// the raw key over the wire.
 
 // ---------------------------------------------------------------------------
 // Sender
@@ -50,7 +39,6 @@ export async function sendEvents(events, config) {
 
   const payload = {
     anonymousId: config.anonymousId,
-    license_key: readGlobalLicenseKey(),
     project_name: config.projectName ?? null,
     chatiVersion: config.version || 'unknown',
     nodeVersion: process.version,

package/src/terminal/run-parallel.js

@@ -16,7 +16,7 @@
 
 import { fileURLToPath } from 'url';
 import { buildAgentPrompt } from './prompt-builder.js';
-import { spawnParallelGroup, spawnTerminal } from './spawner.js';
+import { spawnParallelGroup, spawnTerminal, killTerminal } from './spawner.js';
 import { TerminalMonitor } from './monitor.js';
 import { collectResults, mergeHandoffs, buildConsolidatedHandoff } from './collector.js';
 import { parseAgentOutput } from './handoff-parser.js';
@@ -254,13 +254,13 @@ async function main() {
  * @param {number} timeout - Per-agent timeout in ms
  * @returns {Promise<{ groupId: string, terminals: object[] }>}
  */
-async function sequentialFallback(configs, timeout) {
+async function sequentialFallback(configs, timeout, _spawnFn = spawnTerminal) {
   const groupId = `seq-fallback-${Date.now()}`;
   const terminals = [];
 
   for (let i = 0; i < configs.length; i++) {
     const cfg = configs[i];
-    const terminal = spawnTerminal({
+    const handle = _spawnFn({
       agent: cfg.agent,
       taskId: cfg.taskId,
       model: cfg.model,
@@ -270,26 +270,26 @@ async function sequentialFallback(configs, timeout) {
       timeout: cfg.timeout || timeout,
     });
 
-    // Wait for this terminal to finish before spawning the next
+    // Wait for the REAL process exit before spawning the next agent. The old
+    // implementation probed terminal.onExit?.(), a method TerminalHandle never
+    // had, so every agent "completed" instantly and the fallback ran the whole
+    // group in parallel - defeating its purpose (shedding rate-limit pressure).
     await new Promise((resolve) => {
-      const timer = setTimeout(() => {
-        terminal.kill?.();
+      if (!handle?.process || handle.status !== 'running') {
         resolve();
+        return;
+      }
+      const timer = setTimeout(() => {
+        killTerminal(handle).catch(() => {}).then(resolve, resolve);
       }, (cfg.timeout || timeout) + 5_000);
 
-      terminal.onExit?.(() => {
+      handle.process.once('exit', () => {
         clearTimeout(timer);
         resolve();
       });
-
-      // If terminal doesn't have onExit, resolve after a short poll
-      if (!terminal.onExit) {
-        clearTimeout(timer);
-        resolve();
-      }
     });
 
-    terminals.push(terminal);
+    terminals.push(handle);
 
     // Small delay between spawns to avoid rate limit pressure
     if (i < configs.length - 1) {

package/src/terminal/run-team.js

@@ -21,7 +21,7 @@ import { fileURLToPath } from 'url';
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { buildAgentPrompt } from './prompt-builder.js';
-import { spawnParallelGroup, spawnTerminal } from './spawner.js';
+import { spawnParallelGroup } from './spawner.js';
 import { TerminalMonitor } from './monitor.js';
 import { collectResults, mergeHandoffs, buildConsolidatedHandoff } from './collector.js';
 import { parseAgentOutput } from './handoff-parser.js';
@@ -107,7 +107,7 @@ async function main() {
   const taskListPath = join(teamDir, 'tasks.yaml');
 
   // Load session state (minimal parse)
-  let sessionState = {};
+  const sessionState = {};
   try {
     const sessionPath = join(projectDir, '.chati', 'session.yaml');
     if (existsSync(sessionPath)) {
@@ -166,7 +166,7 @@ async function main() {
 
   // Spawn team members
   let group;
-  let fallbackUsed = false;
+  const fallbackUsed = false;
   const echoEvents = [];
 
   try {

package/src/upgrade/backup.js

@@ -1,6 +1,24 @@
 import { existsSync, mkdirSync, cpSync, rmSync } from 'fs';
 import { join } from 'path';
 import { resolveFrameworkDir } from '../utils/framework-dir.js';
+import { FRAMEWORK_DIRS_TO_COPY } from '../installer/core.js';
+
+/**
+ * The backup must cover exactly what the upgrade overwrites, or a rollback
+ * leaves the install in a chimera state (some dirs at the new version, some
+ * restored). The upgrade replaces every dir in FRAMEWORK_DIRS_TO_COPY (via
+ * copyFrameworkFiles), so that same list is the backup/restore scope - one
+ * source of truth, no asymmetry. Previously the backup saved 12 dirs and the
+ * restore returned only 10 (intelligence and data were backed up but never
+ * restored; hooks, domains, tasks, scaffold and others were never backed up
+ * at all).
+ */
+const BACKUP_DIRS = FRAMEWORK_DIRS_TO_COPY;
+
+const BACKUP_FILES = [
+  'constitution.md',
+  'config.yaml',
+];
 
 /**
  * Create backup of chati.dev/ directory before upgrade
@@ -17,28 +35,7 @@ export function createBackup(targetDir, currentVersion) {
 
   mkdirSync(backupDir, { recursive: true });
 
-  // Backup framework files (NOT artifacts or intelligence)
-  const dirsToBackup = [
-    'orchestrator',
-    'agents',
-    'templates',
-    'workflows',
-    'quality-gates',
-    'schemas',
-    'frameworks',
-    'i18n',
-    'patterns',
-    'migrations',
-    'intelligence',
-    'data',
-  ];
-
-  const filesToBackup = [
-    'constitution.md',
-    'config.yaml',
-  ];
-
-  for (const dir of dirsToBackup) {
+  for (const dir of BACKUP_DIRS) {
     const src = join(frameworkDir, dir);
     const dest = join(backupDir, dir);
     if (existsSync(src)) {
@@ -46,7 +43,7 @@ export function createBackup(targetDir, currentVersion) {
     }
   }
 
-  for (const file of filesToBackup) {
+  for (const file of BACKUP_FILES) {
     const src = join(frameworkDir, file);
     const dest = join(backupDir, file);
     if (existsSync(src)) {
@@ -68,26 +65,7 @@ export function restoreFromBackup(targetDir, version) {
     throw new Error(`Backup not found: ${backupDir}`);
   }
 
-  // Restore backed-up directories
-  const dirsToRestore = [
-    'orchestrator',
-    'agents',
-    'templates',
-    'workflows',
-    'quality-gates',
-    'schemas',
-    'frameworks',
-    'i18n',
-    'patterns',
-    'migrations',
-  ];
-
-  const filesToRestore = [
-    'constitution.md',
-    'config.yaml',
-  ];
-
-  for (const dir of dirsToRestore) {
+  for (const dir of BACKUP_DIRS) {
     const src = join(backupDir, dir);
     const dest = join(frameworkDir, dir);
     if (existsSync(src)) {
@@ -98,7 +76,7 @@ export function restoreFromBackup(targetDir, version) {
     }
   }
 
-  for (const file of filesToRestore) {
+  for (const file of BACKUP_FILES) {
     const src = join(backupDir, file);
     const dest = join(frameworkDir, file);
     if (existsSync(src)) {

package/src/upgrade/migrator.js

@@ -42,13 +42,25 @@ export function findMigrations(targetDir, fromVersion, toVersion) {
   for (const file of files) {
     try {
       const content = yaml.load(readFileSync(join(migrationsDir, file), 'utf-8'));
-      const migration = content?.migration;
+      // Two header schemas exist: the nested `migration: { from, to }` form and
+      // the older flat `from_version`/`to_version` form (with `operations`
+      // instead of `steps`). The flat files were silently skipped here, which
+      // hid them from every upgrade.
+      const migration = content?.migration
+        ?? (content?.from_version && content?.to_version
+          ? { from: content.from_version, to: content.to_version, description: content.description, breaking: content.breaking }
+          : null);
 
       if (!migration?.from || !migration?.to) continue;
 
-      // Check if this migration is in the upgrade path
+      // A migration applies when its TARGET version lies inside the upgrade
+      // interval (fromVersion, toVersion]. The old condition compared the
+      // migration's `from` against the user's version with gte, which skipped
+      // every pending migration for users sitting ABOVE a migration's starting
+      // point (a 4.2.3 user never received v4.2-to-v4.3) and is wrong for
+      // users below it too (a 3.x user needs every step on the way up).
       if (
-        semver.gte(migration.from, fromVersion) &&
+        semver.gt(migration.to, fromVersion) &&
         semver.lte(migration.to, toVersion)
       ) {
         applicable.push({
@@ -57,7 +69,7 @@ export function findMigrations(targetDir, fromVersion, toVersion) {
           to: migration.to,
           description: migration.description || '',
           breaking: migration.breaking || false,
-          steps: content.steps || [],
+          steps: content.steps || content.operations || [],
           rollback: content.rollback || [],
         });
       }
@@ -73,14 +85,20 @@ export function findMigrations(targetDir, fromVersion, toVersion) {
 }
 
 /**
- * Execute a single migration step
+ * Execute a single migration step. Exported for testing.
  */
-async function executeMigrationStep(targetDir, step) {
+export async function executeMigrationStep(targetDir, step, sourceFile = '') {
   switch (step.type) {
     case 'create_directory': {
-      const dir = join(targetDir, step.path);
-      if (!existsSync(dir) || !step.idempotent) {
-        mkdirSync(dir, { recursive: true });
+      // Both shapes exist in the migration corpus: `path` (string) in the
+      // nested-schema files and `paths` (array) in the older flat-schema ones.
+      const dirs = Array.isArray(step.paths) ? step.paths : [step.path];
+      for (const rel of dirs) {
+        if (!rel) continue;
+        const dir = join(targetDir, rel);
+        if (!existsSync(dir) || !step.idempotent) {
+          mkdirSync(dir, { recursive: true });
+        }
       }
       break;
     }
@@ -100,7 +118,19 @@ async function executeMigrationStep(targetDir, step) {
 
       const content = yaml.load(readFileSync(filePath, 'utf-8')) || {};
 
-      if (step.operation === 'add_field') {
+      if (step.changes && typeof step.changes === 'object') {
+        // Older flat-schema shape: a `changes:` map of (possibly dotted)
+        // field -> value, applied as a plain set.
+        for (const [field, value] of Object.entries(step.changes)) {
+          const keys = field.split('.');
+          let obj = content;
+          for (let i = 0; i < keys.length - 1; i++) {
+            if (!obj[keys[i]]) obj[keys[i]] = {};
+            obj = obj[keys[i]];
+          }
+          obj[keys[keys.length - 1]] = value;
+        }
+      } else if (step.operation === 'add_field') {
         const keys = step.field.split('.');
         let obj = content;
         for (let i = 0; i < keys.length - 1; i++) {
@@ -176,7 +206,16 @@ async function executeMigrationStep(targetDir, step) {
     }
 
     default:
-      // Unknown step type - skip
+      // Copy-style steps (copy_file, copy_directory) from the older flat-schema
+      // migrations are subsumed by the upgrade's blanket copyFrameworkFiles, so
+      // skipping them is correct. Anything else unknown is surfaced instead of
+      // silently dropped, so an upgrader from a very old version knows what to
+      // review manually.
+      if (step.type !== 'copy_file' && step.type !== 'copy_directory') {
+        process.stderr.write(
+          `[chati] warning: migration step type "${step.type}"${sourceFile ? ` in ${sourceFile}` : ''} is not auto-executable; review the migration file manually\n`
+        );
+      }
       break;
   }
 }
@@ -196,7 +235,7 @@ export async function runMigrations(targetDir, fromVersion, toVersion) {
   for (const migration of migrations) {
     try {
       for (const step of migration.steps) {
-        await executeMigrationStep(targetDir, step);
+        await executeMigrationStep(targetDir, step, migration.file);
       }
       results.push({ file: migration.file, success: true });
     } catch (err) {

package/src/upgrade/tracked-files-detector.js

@@ -41,6 +41,11 @@ function isGitRepo(targetDir) {
  * Detect which framework-owned paths are currently tracked by git.
  * Does NOT modify git state — read-only operation.
  *
+ * Runs a single `git ls-files -z -- <pattern1> <pattern2> …` invocation and
+ * partitions the result locally. The prior implementation spawned one
+ * `git ls-files` per pattern (19 processes per call) which added several
+ * hundred ms of overhead on a slow disk during every upgrade check.
+ *
  * @param {string} targetDir - absolute path to the project root
  * @returns {string[]} array of tracked framework file paths (relative to targetDir)
  */
@@ -49,28 +54,41 @@ export function detectTrackedFrameworkFiles(targetDir) {
     return [];
   }
 
-  const tracked = [];
+  let stdout;
+  try {
+    // -z: NUL-separated output (safe for paths with spaces/newlines).
+    // Pass all patterns as positional args after `--` so they're treated as
+    // pathspecs, not options. Quoting is handled by execFile-style argv if
+    // available; we use execSync with a builtin pattern array escape.
+    const args = FRAMEWORK_PATTERNS.map(p => JSON.stringify(p)).join(' ');
+    stdout = execSync(`git ls-files -z -- ${args}`, {
+      cwd: targetDir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+    }).toString();
+  } catch {
+    // git ls-files failed entirely (not a repo, repo corrupt, etc.) → none tracked
+    return [];
+  }
 
-  for (const pattern of FRAMEWORK_PATTERNS) {
-    try {
-      const result = execSync(`git ls-files -- "${pattern}"`, {
-        cwd: targetDir,
-        stdio: ['ignore', 'pipe', 'ignore'],
-        timeout: 5000,
-      })
-        .toString()
-        .trim();
+  if (!stdout) return [];
 
-      if (result.length > 0) {
-        tracked.push(pattern);
+  // Split on NUL. For each tracked path returned by git, find which of our
+  // FRAMEWORK_PATTERNS it belongs under (directory prefixes use trailing
+  // slash; exact-file patterns match equality).
+  const trackedPaths = stdout.split('\0').filter(Boolean);
+  const tracked = new Set();
+  for (const path of trackedPaths) {
+    for (const pattern of FRAMEWORK_PATTERNS) {
+      if (pattern.endsWith('/')) {
+        if (path.startsWith(pattern)) { tracked.add(pattern); break; }
+      } else if (path === pattern) {
+        tracked.add(pattern); break;
       }
-    } catch {
-      // git ls-files failure means path is not tracked — skip
     }
   }
 
-  // Deduplicate in case patterns overlap
-  return [...new Set(tracked)];
+  return [...tracked];
 }
 
 /**