agentic-qe 3.14.4 → 3.14.6

package/dist/cli/index.js

@@ -10,47 +10,19 @@
  * See: cli/commands/ for additional command modules
  */
 import { toErrorMessage } from '../shared/error-utils.js';
+import { initFeatureFlagsFromEnv } from '../integrations/ruvector/feature-flags.js';
 import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { ALL_DOMAINS } from '../shared/types/index.js';
 // ============================================================================
-// Redirect internal domain logs to stderr so stdout stays clean for CI/JSON
+// Route internal diagnostics to stderr, filtered by AQE_LOG_LEVEL / LOG_LEVEL /
+// AQE_VERBOSE (default: warn), so stdout stays clean for CI/JSON.
 // ============================================================================
-const INTERNAL_LOG_PREFIXES = [
-    '[UnifiedMemory]', '[HybridBackend]', '[UnifiedPersistence]',
-    '[PersistentSONAEngine]', '[QueenGovernance]', '[QueenCoordinator]',
-    '[Queen]', '[QUEEN]', '[DomainBreakerRegistry]',
-    '[RealEmbeddings]', '[HNSWIndex]', '[PatternStore]',
-    '[TestGenerationCoordinator]', '[CodeIntelligence]', '[ProductFactorsBridge]',
-    '[LearningOptimizationCoordinator]', '[DreamEngine]', '[DreamScheduler]',
-    '[SecurityCompliance]', '[Providers]', '[GNN]',
-    '[test-generation]', '[test-execution]', '[coverage-analysis]',
-    '[quality-assessment]', '[defect-intelligence]', '[requirements-validation]',
-    '[code-intelligence]', '[security-compliance]', '[contract-testing]',
-    '[visual-accessibility]', '[chaos-resilience]', '[learning-optimization]',
-    '[enterprise-integration]', '[coordination]', '[PatternLearnerService]',
-    '[RequirementsValidation]', '[ParserRegistry]', '[AdversarialDefense]',
-    '[ContinueGateIntegration]', '[ContinueGate]', '[SQLitePatternStore]',
-    '[TokenTracking]', '[InfraHealing]', '[ExperienceCapture]',
-];
-/** Timestamped log pattern: [HH:MM:SS.sss] [LEVEL] */
-const TIMESTAMPED_LOG_RE = /^\[\d{2}:\d{2}:\d{2}\.\d{3}\]\s+\[/;
-const originalConsoleLog = console.log.bind(console);
-console.log = (...args) => {
-    const first = typeof args[0] === 'string' ? args[0] : '';
-    const trimmed = first.trimStart();
-    if (INTERNAL_LOG_PREFIXES.some(prefix => trimmed.startsWith(prefix)) ||
-        TIMESTAMPED_LOG_RE.test(trimmed)) {
-        process.stderr.write(args.map(String).join(' ') + '\n');
-        return;
-    }
-    originalConsoleLog(...args);
-};
-// Also redirect timestamped INFO/WARN/ERROR log lines (e.g. "[07:12:24.372] [INFO ]")
-console.info = (...args) => {
-    process.stderr.write(args.map(String).join(' ') + '\n');
-};
+import { applyCommandVerbosity, installCliLogGate, isCliLogLevelEnabled } from './log-gate.js';
+import { LogLevel } from '../logging/index.js';
+import { formatErrorForLog } from '../logging/redaction.js';
+installCliLogGate();
 // ============================================================================
 // CLI State
 // ============================================================================
@@ -144,10 +116,12 @@ async function ensureInitializedStrict() {
     // For diagnostic commands: check if project was explicitly initialized
     const fs = await import('fs');
     const path = await import('path');
-    const configDir = path.resolve('.agentic-qe');
+    const { findProjectRoot } = await import('../kernel/project-root.js');
+    const configDir = path.join(findProjectRoot(), '.agentic-qe');
     if (!fs.existsSync(configDir)) {
         console.error(chalk.red('\nError: AQE system not initialized in this directory.'));
         console.log(chalk.yellow('Run `aqe init` first to set up this project.\n'));
+        process.exitCode = 1;
         return false;
     }
     return ensureInitialized();
@@ -156,14 +130,19 @@ async function ensureInitialized() {
     if (context.initialized && context.kernel && context.queen) {
         return true;
     }
-    process.stderr.write(chalk.gray('Auto-initializing v3 system...') + '\n');
+    const showProgress = isCliLogLevelEnabled(LogLevel.INFO);
+    if (showProgress) {
+        process.stderr.write(chalk.gray('Auto-initializing v3 system...') + '\n');
+    }
     const timeout = 30000;
     const timeoutPromise = new Promise((_, reject) => {
         setTimeout(() => reject(new Error('Initialization timeout after 30 seconds')), timeout);
     });
     try {
         await Promise.race([autoInitialize(), timeoutPromise]);
-        process.stderr.write(chalk.green('System ready') + '\n\n');
+        if (showProgress) {
+            process.stderr.write(chalk.green('System ready') + '\n\n');
+        }
         return true;
     }
     catch (err) {
@@ -176,6 +155,8 @@ async function ensureInitialized() {
             console.error(chalk.red('Failed to auto-initialize:'), err);
             console.log(chalk.yellow('Try running `aqe init` manually.'));
         }
+        // Callers `return` on false; main() then exits with this code (#758).
+        process.exitCode = 1;
         return false;
     }
 }
@@ -216,7 +197,18 @@ const VERSION = typeof __CLI_VERSION__ !== 'undefined' ? __CLI_VERSION__ : packa
 program
     .name('aqe')
     .description('Agentic QE - Domain-Driven Quality Engineering')
-    .version(VERSION);
+    .version(VERSION)
+    .addHelpText('after', `
+Environment:
+  AQE_LOG_LEVEL   Internal log level: debug | info | warn | error | silent (default: warn)
+  LOG_LEVEL       Same as AQE_LOG_LEVEL; AQE_LOG_LEVEL takes precedence
+  AQE_VERBOSE=1   Shorthand for info-level logging (full system-init output)
+Diagnostics are written to stderr; stdout carries command output only.`);
+// A command's own --verbose flag (aqe sync|status|workflow|eval ... --verbose)
+// raises the log gate to INFO for that run; AQE_LOG_LEVEL / LOG_LEVEL win.
+program.hook('preAction', (_thisCommand, actionCommand) => {
+    applyCommandVerbosity(actionCommand.opts());
+});
 // ============================================================================
 // Register Handlers (lazy — each handler loads only when its command runs)
 // ============================================================================
@@ -338,7 +330,11 @@ registerLazyCommand(program, {
 registerLazyCommand(program, {
     name: 'memory',
     description: 'Memory store, retrieve, search, and delete operations',
-    factory: () => import('./commands/memory.js').then(m => m.createMemoryCommand(context, cleanupAndExit, ensureInitialized)),
+    // Memory subcommands open only the memory store, not the full v3 system.
+    factory: () => Promise.all([
+        import('./commands/memory.js'),
+        import('./helpers/standalone-memory.js'),
+    ]).then(([m, h]) => m.createMemoryCommand(context, cleanupAndExit, h.createEnsureMemoryBackend(context))),
 });
 registerLazyCommand(program, {
     name: 'mcp',
@@ -402,6 +398,7 @@ async function main() {
         console.log(VERSION);
         process.exit(0);
     }
+    initFeatureFlagsFromEnv();
     // File recovery must validate its input before anything opens, migrates, or
     // auto-restores the project's database. Commander accepts `--` separators.
     const commandArgs = process.argv.slice(2).filter(arg => arg !== '--');
@@ -421,10 +418,10 @@ async function main() {
         return;
     // If the command didn't explicitly exit, clean up and exit now.
     // This prevents process hangs from active handles (domain init, embeddings, etc.)
-    await cleanupAndExit(0);
+    await cleanupAndExit(process.exitCode ?? 0);
 }
 main().catch(async (error) => {
-    console.error(chalk.red('Fatal error:'), error);
+    console.error(chalk.red('Fatal error:'), formatErrorForLog(error));
     await cleanupAndExit(1);
 });
 //# sourceMappingURL=index.js.map

package/dist/cli/log-gate.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Agentic QE v3 - CLI Log Gate
+ *
+ * Single place that decides how much internal diagnostic output a CLI
+ * invocation prints. Two kinds of diagnostics exist in the codebase:
+ *
+ *   1. Structured logger output (LoggerFactory / ConsoleLogger), formatted as
+ *      "[HH:MM:SS.mmm] [INFO ] [domain] message".
+ *   2. Ad-hoc console calls with a bracketed tag, e.g.
+ *      console.log('[UnifiedMemory] Initialized: ...').
+ *
+ * Both are routed to stderr (stdout stays clean for JSON/CI consumers) and
+ * filtered against one threshold resolved from the environment:
+ *
+ *   AQE_LOG_LEVEL  debug | info | warn | error | silent   (highest precedence)
+ *   LOG_LEVEL      same values
+ *   AQE_VERBOSE    1 | true | yes | on  -> info
+ *   (default)      warn
+ *
+ * Regular command output (anything without a bracketed tag) is never touched.
+ */
+import { LogLevel } from '../logging/index.js';
+type ConsoleMethod = 'log' | 'info' | 'debug' | 'warn' | 'error';
+type ConsoleLike = Pick<Console, ConsoleMethod>;
+/** Default threshold for CLI commands when nothing is configured. */
+export declare const DEFAULT_CLI_LOG_LEVEL = LogLevel.WARN;
+/**
+ * Resolve the effective CLI log level from the environment.
+ * Unrecognised values are ignored rather than silently mapped to INFO.
+ */
+export declare function resolveCliLogLevel(env?: NodeJS.ProcessEnv, defaultLevel?: LogLevel): LogLevel;
+/**
+ * Classify a console call. Returns the diagnostic level of the line, or null
+ * when the line is regular command output that must pass through untouched.
+ */
+export declare function classifyConsoleLine(method: ConsoleMethod, firstArg: unknown): LogLevel | null;
+/** True when AQE_LOG_LEVEL or LOG_LEVEL holds a recognised level. */
+export declare function hasExplicitCliLogLevel(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Honour a command's own `--verbose` flag (e.g. `aqe sync --verbose`): raise
+ * the threshold to INFO so the diagnostics the user explicitly asked for are
+ * printed (on stderr). An explicit AQE_LOG_LEVEL / LOG_LEVEL still wins.
+ * Returns true when the level was raised.
+ */
+export declare function applyCommandVerbosity(options: Record<string, unknown>, env?: NodeJS.ProcessEnv): boolean;
+/** Current CLI log threshold. */
+export declare function getCliLogLevel(): LogLevel;
+/** True when diagnostics at `level` should be printed. */
+export declare function isCliLogLevelEnabled(level: LogLevel): boolean;
+/**
+ * Change the threshold at runtime. Also reconfigures LoggerFactory so loggers
+ * created afterwards filter at the source instead of relying on the gate.
+ */
+export declare function setCliLogLevel(level: LogLevel): void;
+export interface InstallCliLogGateOptions {
+    level?: LogLevel;
+    target?: ConsoleLike;
+    writeStderr?: (text: string) => void;
+}
+/**
+ * Patch the console so internal diagnostics are routed to stderr and filtered
+ * by the CLI log level. Returns a function that restores the original methods.
+ */
+export declare function installCliLogGate(options?: InstallCliLogGateOptions): () => void;
+export {};
+//# sourceMappingURL=log-gate.d.ts.map

package/dist/cli/log-gate.js

@@ -0,0 +1,170 @@
+/**
+ * Agentic QE v3 - CLI Log Gate
+ *
+ * Single place that decides how much internal diagnostic output a CLI
+ * invocation prints. Two kinds of diagnostics exist in the codebase:
+ *
+ *   1. Structured logger output (LoggerFactory / ConsoleLogger), formatted as
+ *      "[HH:MM:SS.mmm] [INFO ] [domain] message".
+ *   2. Ad-hoc console calls with a bracketed tag, e.g.
+ *      console.log('[UnifiedMemory] Initialized: ...').
+ *
+ * Both are routed to stderr (stdout stays clean for JSON/CI consumers) and
+ * filtered against one threshold resolved from the environment:
+ *
+ *   AQE_LOG_LEVEL  debug | info | warn | error | silent   (highest precedence)
+ *   LOG_LEVEL      same values
+ *   AQE_VERBOSE    1 | true | yes | on  -> info
+ *   (default)      warn
+ *
+ * Regular command output (anything without a bracketed tag) is never touched.
+ */
+import { format } from 'node:util';
+import { LogLevel, LoggerFactory } from '../logging/index.js';
+/** Default threshold for CLI commands when nothing is configured. */
+export const DEFAULT_CLI_LOG_LEVEL = LogLevel.WARN;
+const LEVEL_NAMES = {
+    debug: LogLevel.DEBUG,
+    info: LogLevel.INFO,
+    warn: LogLevel.WARN,
+    warning: LogLevel.WARN,
+    error: LogLevel.ERROR,
+    silent: LogLevel.SILENT,
+    none: LogLevel.SILENT,
+    off: LogLevel.SILENT,
+};
+const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+// eslint-disable-next-line no-control-regex
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+/** "[10:01:10.407] [INFO ] ..." or "[2026-09-28T10:01:10.407Z] [WARN ] ..." */
+const STRUCTURED_RE = /^\[(?:\d{2}:\d{2}:\d{2}\.\d{3}|\d{4}-\d{2}-\d{2}T[^\]]+)\]\s+\[(DEBUG|INFO|WARN|ERROR)\s*\]/;
+/**
+ * "[UnifiedMemory] ...", "[sona-three-loop] ...", "[quality-assessment/rl] ...".
+ * Requires a letter first and whitespace after the closing bracket so JSON
+ * arrays such as '["a"]' or '[true]' are never mistaken for diagnostics.
+ *
+ * Only a tag at column 0 counts. Indented bracketed text is command output:
+ * severity markers ("    [critical] Code Injection ..." from `aqe security`,
+ * "  [high] ..." from `aqe status` / `aqe coverage`) and user data such as a
+ * stored memory value "[TODO] fix auth" printed by `aqe memory get`.
+ */
+const TAGGED_RE = /^\[[A-Za-z][\w./:-]*\]\s/;
+const TAG_METHOD_LEVEL = {
+    debug: LogLevel.DEBUG,
+    log: LogLevel.INFO,
+    info: LogLevel.INFO,
+    warn: LogLevel.WARN,
+    error: LogLevel.ERROR,
+};
+let currentLevel = DEFAULT_CLI_LOG_LEVEL;
+function parseLevel(value) {
+    if (!value)
+        return undefined;
+    return LEVEL_NAMES[value.trim().toLowerCase()];
+}
+/**
+ * Resolve the effective CLI log level from the environment.
+ * Unrecognised values are ignored rather than silently mapped to INFO.
+ */
+export function resolveCliLogLevel(env = process.env, defaultLevel = DEFAULT_CLI_LOG_LEVEL) {
+    const explicit = parseLevel(env.AQE_LOG_LEVEL) ?? parseLevel(env.LOG_LEVEL);
+    if (explicit !== undefined)
+        return explicit;
+    if (env.AQE_VERBOSE && TRUTHY.has(env.AQE_VERBOSE.trim().toLowerCase())) {
+        return LogLevel.INFO;
+    }
+    return defaultLevel;
+}
+/**
+ * Classify a console call. Returns the diagnostic level of the line, or null
+ * when the line is regular command output that must pass through untouched.
+ */
+export function classifyConsoleLine(method, firstArg) {
+    if (typeof firstArg !== 'string')
+        return null;
+    const text = firstArg.replace(ANSI_RE, '');
+    const structured = STRUCTURED_RE.exec(text.trimStart());
+    if (structured) {
+        return LEVEL_NAMES[structured[1].toLowerCase()];
+    }
+    if (TAGGED_RE.test(text)) {
+        return TAG_METHOD_LEVEL[method];
+    }
+    return null;
+}
+/** True when AQE_LOG_LEVEL or LOG_LEVEL holds a recognised level. */
+export function hasExplicitCliLogLevel(env = process.env) {
+    return parseLevel(env.AQE_LOG_LEVEL) !== undefined || parseLevel(env.LOG_LEVEL) !== undefined;
+}
+/**
+ * Honour a command's own `--verbose` flag (e.g. `aqe sync --verbose`): raise
+ * the threshold to INFO so the diagnostics the user explicitly asked for are
+ * printed (on stderr). An explicit AQE_LOG_LEVEL / LOG_LEVEL still wins.
+ * Returns true when the level was raised.
+ */
+export function applyCommandVerbosity(options, env = process.env) {
+    if (options.verbose !== true || hasExplicitCliLogLevel(env))
+        return false;
+    if (isCliLogLevelEnabled(LogLevel.INFO))
+        return false;
+    setCliLogLevel(LogLevel.INFO);
+    return true;
+}
+/** Current CLI log threshold. */
+export function getCliLogLevel() {
+    return currentLevel;
+}
+/** True when diagnostics at `level` should be printed. */
+export function isCliLogLevelEnabled(level) {
+    return level >= currentLevel && currentLevel !== LogLevel.SILENT;
+}
+/**
+ * Change the threshold at runtime. Also reconfigures LoggerFactory so loggers
+ * created afterwards filter at the source instead of relying on the gate.
+ */
+export function setCliLogLevel(level) {
+    currentLevel = level;
+    LoggerFactory.setLevel(level);
+}
+/**
+ * Patch the console so internal diagnostics are routed to stderr and filtered
+ * by the CLI log level. Returns a function that restores the original methods.
+ */
+export function installCliLogGate(options = {}) {
+    const target = options.target ?? console;
+    const writeStderr = options.writeStderr ?? ((text) => { process.stderr.write(text); });
+    setCliLogLevel(options.level ?? resolveCliLogLevel());
+    const original = {
+        log: target.log.bind(target),
+        info: target.info.bind(target),
+        debug: target.debug.bind(target),
+        warn: target.warn.bind(target),
+        error: target.error.bind(target),
+    };
+    const toStderr = (args) => writeStderr(format(...args) + '\n');
+    const gate = (method, passthrough, emit) => (...args) => {
+        const level = classifyConsoleLine(method, args[0]);
+        if (level === null) {
+            passthrough(args);
+        }
+        else if (isCliLogLevelEnabled(level)) {
+            emit(args);
+        }
+    };
+    // log/debug output normally goes to stdout; diagnostics are moved to stderr.
+    target.log = gate('log', args => original.log(...args), toStderr);
+    target.debug = gate('debug', args => original.debug(...args), toStderr);
+    // console.info has always been redirected to stderr by the CLI.
+    target.info = gate('info', toStderr, toStderr);
+    // warn/error already target stderr; keep their native formatting.
+    target.warn = gate('warn', args => original.warn(...args), args => original.warn(...args));
+    target.error = gate('error', args => original.error(...args), args => original.error(...args));
+    return () => {
+        target.log = original.log;
+        target.info = original.info;
+        target.debug = original.debug;
+        target.warn = original.warn;
+        target.error = original.error;
+    };
+}
+//# sourceMappingURL=log-gate.js.map

package/dist/init/agents-installer.d.ts

@@ -74,6 +74,10 @@ export declare class AgentsInstaller {
      * Install a single agent
      */
     private installAgent;
+    /**
+     * Describe an agent from its installed file (type, description, domain).
+     */
+    private describeAgent;
     /**
      * Get the type of an agent based on its name
      */

package/dist/init/agents-installer.js

@@ -11,6 +11,7 @@ import { toErrorMessage } from '../shared/error-utils.js';
 import { loadOverlays, applyOverlayToContent } from '../agents/overlay-loader.js';
 import { validateFleetMcpDeps } from '../validation/steps/agent-mcp-validator.js';
 import { findPackageRoot } from './find-package-root.js';
+import { GENERATED_ON_LINE, writeTextIfChangedIgnoring } from './idempotent-write.js';
 // ============================================================================
 // Helpers
 // ============================================================================
@@ -240,15 +241,21 @@ export class AgentsInstaller {
         result.totalCount = availableAgents.length;
         // Filter agents based on options
         const agentsToInstall = this.filterAgents(availableAgents);
+        // Every selected agent present on disk after this run — newly installed or
+        // already there — so the index describes the install, not just this run's
+        // delta (a repeat init used to rewrite it as "Total Agents: 0", #778).
+        const presentAgents = [];
         // Install each agent
         for (const agentName of agentsToInstall) {
             try {
                 const agentInfo = await this.installAgent(agentName, targetAgentsDir, targetSubagentsDir);
                 if (agentInfo) {
                     result.installed.push(agentInfo);
+                    presentAgents.push(agentInfo);
                 }
                 else {
                     result.skipped.push(agentName);
+                    presentAgents.push(this.describeAgent(agentName, targetAgentsDir, targetSubagentsDir));
                 }
             }
             catch (error) {
@@ -313,7 +320,7 @@ export class AgentsInstaller {
             }
         }
         // Create agents index file
-        await this.createAgentsIndex(targetAgentsDir, result.installed);
+        await this.createAgentsIndex(targetAgentsDir, presentAgents);
         return result;
     }
     /**
@@ -405,17 +412,22 @@ export class AgentsInstaller {
         else {
             throw new Error(`Source file not found: ${sourceFile}`);
         }
-        // Determine agent type
-        const agentType = this.getAgentType(agentName, isSubagent);
-        // Get description from agent file
-        const description = this.getAgentDescription(targetFile);
-        // Get domain from agent name
-        const domain = this.getAgentDomain(agentName);
+        return this.describeAgent(agentPath, targetDir, targetSubagentsDir);
+    }
+    /**
+     * Describe an agent from its installed file (type, description, domain).
+     */
+    describeAgent(agentPath, targetDir, targetSubagentsDir) {
+        const isSubagent = agentPath.startsWith('subagents/');
+        const agentName = isSubagent ? agentPath.split('/')[1] : agentPath;
+        const targetFile = isSubagent
+            ? join(targetSubagentsDir, `${agentName}.md`)
+            : join(targetDir, `${agentName}.md`);
         return {
             name: agentName,
-            type: agentType,
-            description,
-            domain,
+            type: this.getAgentType(agentName, isSubagent),
+            description: this.getAgentDescription(targetFile),
+            domain: this.getAgentDomain(agentName),
         };
     }
     /**
@@ -629,7 +641,8 @@ ${subagents.map(a => `- **${a.name}**${a.description ? `: ${a.description}` : ''
         if (!existsSync(docsDir)) {
             mkdirSync(docsDir, { recursive: true });
         }
-        writeFileSync(join(docsDir, 'v3-agents-index.md'), indexContent, 'utf-8');
+        // #778: ignore the generation-timestamp footer when deciding to rewrite.
+        writeTextIfChangedIgnoring(join(docsDir, 'v3-agents-index.md'), indexContent, GENERATED_ON_LINE);
     }
 }
 /**

package/dist/init/codex-installer.js

@@ -9,6 +9,8 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSyn
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { toErrorMessage } from '../shared/error-utils.js';
+import { findPackageRoot } from './find-package-root.js';
+import { writeFileIfChanged } from './idempotent-write.js';
 import { selectCodexSkills } from './codex-skill-manifest.js';
 import { createPlatformConfigGenerator, } from './platform-config-generator.js';
 export const CODEX_COMPACT_GUIDANCE_MAX_BYTES = 512;
@@ -111,7 +113,7 @@ export class CodexInstaller {
                 result.ownedGuidanceBytes = Buffer.byteLength(marked);
                 result.components.rules.status = 'installed';
             }
-            else if (this.overwrite || policy === 'compact') {
+            else {
                 const content = policy === 'compact' ? COMPACT_CODEX_GUIDANCE : rules.content;
                 const existing = readFileSync(agentsMdPath, 'utf-8');
                 const merged = this.mergeExistingAgentsMdContent(existing, content);
@@ -125,10 +127,6 @@ export class CodexInstaller {
                 }
                 result.ownedGuidanceBytes = this.measureOwnedAgentsSection(merged);
             }
-            else {
-                result.components.rules.status = 'preserved';
-                result.ownedGuidanceBytes = this.measureOwnedAgentsSection(readFileSync(agentsMdPath, 'utf-8'));
-            }
         }
         catch (error) {
             this.recordComponentFailure(result, 'rules', error);
@@ -147,6 +145,13 @@ export class CodexInstaller {
         catch (error) {
             this.recordComponentFailure(result, 'skills', error);
         }
+        for (const component of ['hooks', 'skills']) {
+            if (result.components[component].status === 'unavailable') {
+                const message = `Codex ${component} unavailable: packaged assets could not be located`;
+                result.components[component].error = message;
+                result.errors.push(message);
+            }
+        }
         result.success = result.errors.length === 0;
         return result;
     }
@@ -232,9 +237,10 @@ export class CodexInstaller {
             const userGroups = (existing.hooks?.[event] || []).filter((group) => !owned(group));
             mergedHooks[event] = [...userGroups, ...(generated.hooks?.[event] || [])];
         }
-        writeFileSync(targetConfig, JSON.stringify({ ...existing, description: generated.description, hooks: mergedHooks }, null, 2) + '\n');
+        // #778: a converged hooks.json is left untouched (no mtime churn).
+        const changed = writeFileIfChanged(targetConfig, JSON.stringify({ ...existing, description: generated.description, hooks: mergedHooks }, null, 2) + '\n');
         result.hooksConfigured = true;
-        return 'updated';
+        return changed ? 'updated' : 'preserved';
     }
     /** Install the curated repo-scoped AQE skills Codex discovers automatically. */
     installCodexSkills() {
@@ -297,6 +303,11 @@ export class CodexInstaller {
         }
     }
     resolvePackageRoot() {
+        // Bundled chunks retain their real package location even when npm's aqe
+        // bin is a symlink in a global prefix.
+        const packagedRoot = findPackageRoot(import.meta.url);
+        if (packagedRoot)
+            return packagedRoot;
         const moduleDir = dirname(fileURLToPath(import.meta.url));
         const candidates = [
             join(moduleDir, '..', '..'),
@@ -348,7 +359,10 @@ export class CodexInstaller {
             return merged;
         if (existing.length === 0)
             return marked;
-        return existing.trimEnd() + `${eol}${eol}---${eol}${eol}` + marked;
+        // The owned block starts at the original EOF. Keeping every pre-existing
+        // byte outside the sentinel lets `none` remove the block exactly, even
+        // when the user's file has no trailing newline.
+        return existing + marked;
     }
     removeOwnedAgentsSections(existing) {
         this.assertOwnedAgentsSectionsWellFormed(existing);

package/dist/init/idempotent-write.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Idempotent file writers for `aqe init` (#778).
+ *
+ * A repeat `aqe init` on an unchanged project must be a byte-stable
+ * convergence step: files whose content would not change are left alone (no
+ * rewrite, so the mtime is preserved too), and volatile fields such as
+ * generation timestamps are carried over from the existing file unless
+ * something else in that file actually changed.
+ */
+/**
+ * Write `content` to `path` only when the bytes on disk differ.
+ * @returns true when the file was written.
+ */
+export declare function writeFileIfChanged(path: string, content: string | Buffer): boolean;
+/**
+ * Copy `src` to `dest` only when `dest` is missing or its bytes differ.
+ * Uses copyFileSync for the actual copy so file-mode semantics are unchanged.
+ * @returns true when the file was copied.
+ */
+export declare function copyFileIfChanged(src: string, dest: string): boolean;
+/**
+ * Write a text file whose content embeds a volatile line (e.g. a generation
+ * timestamp). When the existing file matches `content` on every line except
+ * the lines matching `volatileLine`, the file is left untouched.
+ * @returns true when the file was written.
+ */
+export declare function writeTextIfChangedIgnoring(path: string, content: string, volatileLine: RegExp): boolean;
+/** The `*Generated by AQE v3 init on <ISO>*` footer of generated index docs. */
+export declare const GENERATED_ON_LINE: RegExp;
+/** JSON serialization with object keys sorted, for order-insensitive comparison. */
+export declare function canonicalJson(value: unknown): string;
+/** Deep structural equality of two JSON values, ignoring object key order. */
+export declare function jsonEquivalent(a: unknown, b: unknown): boolean;
+/**
+ * Carry volatile fields (timestamps) over from `previous` into `next` when
+ * `next` is otherwise identical to `previous`.
+ *
+ * - Unchanged (apart from the volatile fields): `next` is mutated to hold the
+ *   previous values and `false` is returned — the caller should not write.
+ * - Changed, or no previous document: `next` keeps its fresh values and
+ *   `true` is returned — the caller should write.
+ */
+export declare function stabilizeVolatileFields(previous: unknown, next: Record<string, unknown>, volatilePaths: ReadonlyArray<readonly string[]>): boolean;
+/** Read and parse a JSON file, or return undefined when missing/unparseable. */
+export declare function readJsonIfPresent(path: string): unknown;
+/**
+ * Write a generated JSON document (2-space indent) unless it is equivalent to
+ * the one already on disk, preserving the existing values of `volatilePaths`
+ * (e.g. `[['createdAt']]`) when nothing else changed.
+ * @returns true when the file was written.
+ */
+export declare function writeJsonIfChanged(path: string, doc: Record<string, unknown>, volatilePaths?: ReadonlyArray<readonly string[]>): boolean;
+//# sourceMappingURL=idempotent-write.d.ts.map