@ghl-ai/aw 0.1.93 → 0.2.0

package/aw-usage-wiring.mjs

@@ -0,0 +1,386 @@
+// aw-usage-wiring.mjs — single owner of where the aw-usage telemetry hook
+// scripts live on a laptop and how Claude Code is wired to them.
+//
+// This repo (libs/aw/hooks/aw-usage/) is the only source of the aw-usage
+// scripts. They are installed to ~/.aw/aw-usage/{hooks,lib,package.json}
+// and every harness (Claude Code, Codex, git post-commit, and the Cursor
+// adapter in aw-ecc) runs them from there.
+//
+// Both writers of ~/.claude/settings.json — startup.mjs (runs on init, link,
+// pull, startup and post-upgrade) and install-aw-usage-hooks.mjs (runs on
+// init) — use the entry builders below, so they always agree.
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as fmt from './fmt.mjs';
+
+const PACKAGE_ROOT = dirname(fileURLToPath(import.meta.url));
+const BUNDLED_ROOT = join(PACKAGE_ROOT, 'hooks', 'aw-usage');
+
+// hook_version (B8, P5): the aw CLI version that installed ~/.aw/aw-usage.
+// The hooks read it from the installed package.json and send it on every event.
+const CLI_VERSION = readJsonVersion(join(PACKAGE_ROOT, 'package.json'));
+
+export const AW_USAGE_DIR_SEGMENTS = ['.aw', 'aw-usage'];
+export const AW_USAGE_SHELL_ROOT = '$HOME/.aw/aw-usage';
+
+export const AW_USAGE_HOOK_SCRIPTS = [
+  'aw-usage-prompt-submit.js',
+  'aw-usage-post-tool-use.js',
+  'aw-usage-post-tool-use-failure.js',
+  'aw-usage-session-start.js',
+  'aw-usage-stop.js',
+  'aw-usage-telemetry-send.js',
+  'aw-usage-commit-created.js',
+];
+
+// The aw-ecc Cursor adapter checks for these lib files, package.json and
+// hooks/aw-usage-telemetry-send.js before using ~/.aw/aw-usage
+// (scripts/cursor-aw-hooks/adapter.js, AW_USAGE_REQUIRED_FILES). Keep in sync.
+export const AW_USAGE_LIB_FILES = ['aw-usage-telemetry.js', 'aw-pricing.js', 'aw-usage-envelope.js', 'aw-usage-queue.js', 'aw-usage-commands.js', 'aw-usage-skill-source.js', 'aw-usage-stage-events.js'];
+
+export const CLAUDE_TELEMETRY_DESCRIPTION = 'AW usage telemetry';
+export const CLAUDE_MEMORY_STOP_DESCRIPTION = 'AW-managed: aw-memory stop hooks';
+
+// The AW memory scripts still ship with aw-ecc; only telemetry moved here.
+const CLAUDE_MEMORY_STOP_COMMAND =
+  'STDIN="$(cat)"; ' +
+  'test -f "$HOME/.aw-ecc/scripts/hooks/aw-memory-intent-capture.js" && printf \'%s\' "$STDIN" | node "$HOME/.aw-ecc/scripts/hooks/aw-memory-intent-capture.js" || true; ' +
+  'test -f "$HOME/.aw-ecc/scripts/hooks/aw-memory-sync.js" && printf \'%s\' "$STDIN" | node "$HOME/.aw-ecc/scripts/hooks/aw-memory-sync.js" || true';
+
+const CLAUDE_TELEMETRY_PHASES = [
+  { phase: 'SessionStart', script: 'aw-usage-session-start.js' },
+  { phase: 'UserPromptSubmit', script: 'aw-usage-prompt-submit.js' },
+  { phase: 'PostToolUse', script: 'aw-usage-post-tool-use.js', matcher: '*' },
+  { phase: 'PostToolUseFailure', script: 'aw-usage-post-tool-use-failure.js', matcher: '*' },
+  { phase: 'Stop', script: 'aw-usage-stop.js', matcher: '*' },
+];
+
+// ── Paths ────────────────────────────────────────────────────────────
+
+export function awUsageRoot(homeDir) {
+  return join(homeDir, ...AW_USAGE_DIR_SEGMENTS);
+}
+
+export function awUsageShellScriptPath(scriptName) {
+  return `${AW_USAGE_SHELL_ROOT}/hooks/${scriptName}`;
+}
+
+// ── Copy step ────────────────────────────────────────────────────────
+
+// Tri-state: 'copied' wrote bytes, 'unchanged' already identical, 'failed'
+// source missing or the read/write threw (permissions, ENOTDIR, EBUSY…).
+function copyIfChanged(src, dest) {
+  if (!existsSync(src)) return 'failed';
+  try {
+    if (existsSync(dest) && readFileSync(src).equals(readFileSync(dest))) return 'unchanged';
+    copyFileSync(src, dest);
+    return 'copied';
+  } catch {
+    return 'failed';
+  }
+}
+
+function readJsonVersion(path) {
+  try {
+    const version = JSON.parse(readFileSync(path, 'utf8')).version;
+    return typeof version === 'string' && version ? version : null;
+  } catch {
+    // Missing or unreadable: no version known; callers treat null as "not stamped".
+    return null;
+  }
+}
+
+// package.json is the bundled file plus "version": cliVersion.
+function writeStampedPackageJson(src, dest, cliVersion) {
+  try {
+    const content = `${JSON.stringify({ ...JSON.parse(readFileSync(src, 'utf8')), version: cliVersion }, null, 2)}\n`;
+    if (existsSync(dest) && readFileSync(dest, 'utf8') === content) return 'unchanged';
+    // Not atomic: a hook reading mid-write sends no hook_version for that one event.
+    writeFileSync(dest, content);
+    return 'copied';
+  } catch {
+    // Reported as 'failed' to the caller, like every other copy failure.
+    return 'failed';
+  }
+}
+
+function ensureDir(dir) {
+  try {
+    mkdirSync(dir, { recursive: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Copy the bundled aw-usage scripts to ~/.aw/aw-usage/. Idempotent.
+ * package.json is written with "version": cliVersion (the running aw CLI).
+ * @param {string} homeDir
+ * @param {{ cliVersion?: string | null }} [opts]
+ * @returns {{ copied: number, unchanged: number, failed: number, missing: string[],
+ *   byDir: Record<'hooks'|'lib'|'root', { copied: number, unchanged: number, failed: number }> }}
+ *   `missing` lists relative paths that could not be written.
+ */
+export function copyAwUsageScripts(homeDir, { cliVersion = CLI_VERSION } = {}) {
+  const root = awUsageRoot(homeDir);
+  const result = { copied: 0, unchanged: 0, failed: 0, missing: [], byDir: {} };
+  const groups = [
+    { key: 'hooks', dir: 'hooks', files: AW_USAGE_HOOK_SCRIPTS },
+    { key: 'lib', dir: 'lib', files: AW_USAGE_LIB_FILES },
+    { key: 'root', dir: '', files: ['package.json'] },
+  ];
+
+  for (const { key, dir, files } of groups) {
+    const counts = { copied: 0, unchanged: 0, failed: 0 };
+    result.byDir[key] = counts;
+    const destDir = dir ? join(root, dir) : root;
+    const dirReady = ensureDir(destDir);
+    for (const name of files) {
+      const rel = dir ? `${dir}/${name}` : name;
+      const src = join(BUNDLED_ROOT, dir, name);
+      const dest = join(destDir, name);
+      let outcome = 'failed';
+      if (dirReady) {
+        outcome = key === 'root' && cliVersion
+          ? writeStampedPackageJson(src, dest, cliVersion)
+          : copyIfChanged(src, dest);
+      }
+      result[outcome]++;
+      counts[outcome]++;
+      if (outcome === 'failed') result.missing.push(rel);
+    }
+  }
+  return result;
+}
+
+/**
+ * Relative paths under ~/.aw/aw-usage/ that are absent. The scripts only work
+ * as a set (hooks require lib/, lib/ needs package.json), so wiring treats
+ * copy A as installed only when this is empty.
+ */
+export function missingAwUsageFiles(homeDir) {
+  const root = awUsageRoot(homeDir);
+  return [
+    ...AW_USAGE_HOOK_SCRIPTS.map(name => `hooks/${name}`),
+    ...AW_USAGE_LIB_FILES.map(name => `lib/${name}`),
+    'package.json',
+  ].filter(rel => !isFile(join(root, ...rel.split('/'))));
+}
+
+/** The CLI version stamped in ~/.aw/aw-usage/package.json, or null. */
+export function installedAwUsageVersion(homeDir) {
+  return readJsonVersion(join(awUsageRoot(homeDir), 'package.json'));
+}
+
+/**
+ * B8: an installed hook version different from the running CLI means the
+ * refresh did not land. Copy once more; if the stamp is still wrong, warn
+ * once. Never throws.
+ * @returns {boolean} true when the installed version matches
+ */
+export function ensureAwUsageVersion(homeDir, { cliVersion = CLI_VERSION } = {}) {
+  if (!cliVersion || installedAwUsageVersion(homeDir) === cliVersion) return true;
+  copyAwUsageScripts(homeDir, { cliVersion });
+  const installed = installedAwUsageVersion(homeDir);
+  if (installed === cliVersion) return true;
+  warnOnce('aw-usage-version', `aw-usage hooks in ${awUsageRoot(homeDir)} are version ${installed ?? 'unknown'}, `
+    + `but this aw CLI is ${cliVersion}, and AW could not update them. `
+    + 'Telemetry keeps using the old hooks. Check that folder\'s permissions, then run aw init.');
+  return false;
+}
+
+function isFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+// ── Warnings (printed once per process; init runs both Claude writers) ─
+
+const warned = new Set();
+
+function warnOnce(key, message) {
+  if (warned.has(key)) return;
+  warned.add(key);
+  fmt.logWarn(message);
+}
+
+export function warnIncompleteAwUsageInstall(missing) {
+  warnOnce('aw-usage-incomplete', `aw-usage telemetry files are missing from ~/.aw/aw-usage (${missing.join(', ')}). `
+    + 'Existing Claude telemetry hooks were kept. Check that folder\'s permissions, then run aw init.');
+}
+
+export function warnStuckAwUsageFiles(stuck) {
+  warnOnce('aw-usage-stuck', `AW could not update these files in ~/.aw/aw-usage (${stuck.join(', ')}). `
+    + 'They are still the old version. Existing Claude telemetry hooks were kept. Check that folder\'s permissions, then run aw init.');
+}
+
+export function warnUnreadableClaudeSettings(settingsPath) {
+  warnOnce(`unreadable:${settingsPath}`, `${settingsPath} is not valid JSON. `
+    + 'AW left it unchanged and did not update its hooks. Fix the file, then run aw init.');
+}
+
+// ── Claude settings.json entries ─────────────────────────────────────
+
+export function claudeTelemetryPhases() {
+  return CLAUDE_TELEMETRY_PHASES.map(def => ({ ...def }));
+}
+
+export function buildClaudeTelemetryEntry(phaseDef) {
+  const entry = {
+    hooks: [{
+      type: 'command',
+      command: `node "${awUsageShellScriptPath(phaseDef.script)}"`,
+      async: true,
+      timeout: 10,
+    }],
+    description: CLAUDE_TELEMETRY_DESCRIPTION,
+  };
+  if (phaseDef.matcher) entry.matcher = phaseDef.matcher;
+  return entry;
+}
+
+export function buildClaudeMemoryStopEntry() {
+  return {
+    hooks: [{ type: 'command', command: CLAUDE_MEMORY_STOP_COMMAND }],
+    description: CLAUDE_MEMORY_STOP_DESCRIPTION,
+  };
+}
+
+function entryCommands(entry) {
+  return Array.isArray(entry?.hooks)
+    ? entry.hooks.map(hook => (typeof hook?.command === 'string' ? hook.command : ''))
+    : [];
+}
+
+// Every place an aw-usage script has been installed from:
+// <root>/scripts/hooks/<name> (aw-ecc, ${CLAUDE_PLUGIN_ROOT}, ~/.claude/scripts)
+// and ~/.aw/aw-usage/hooks/<name>. AW memory scripts have only ever been
+// wired from ~/.aw-ecc/scripts/hooks/. Anchoring on these paths keeps user and
+// project hooks with similar names out of reach.
+const AW_USAGE_SCRIPT_PATTERN = /\/(?:scripts\/hooks|aw-usage\/hooks)\/aw-usage-[a-z-]+\.js/;
+const AW_MEMORY_SCRIPT_PATTERN = /\/\.aw-ecc\/scripts\/hooks\/aw-memory-[a-z-]+\.js/;
+const COPY_A_SCRIPT_PATTERN = /\/aw-usage\/hooks\/aw-usage-[a-z-]+\.js/;
+
+function commandsMatch(entry, pattern) {
+  return entryCommands(entry).some(command => pattern.test(command.split('\\').join('/')));
+}
+
+/** True for the canonical telemetry entry and every legacy aw-usage entry
+ *  (aw-ecc, ${CLAUDE_PLUGIN_ROOT}, ~/.claude/scripts, combined Stop). */
+export function isClaudeTelemetryEntry(entry) {
+  if (entry?.description === CLAUDE_TELEMETRY_DESCRIPTION) return true;
+  return commandsMatch(entry, AW_USAGE_SCRIPT_PATTERN);
+}
+
+/** True for the memory-only Stop entry, described or not. A combined legacy
+ *  entry that also runs aw-usage telemetry is a telemetry entry instead. */
+export function isClaudeMemoryStopEntry(entry) {
+  if (entry?.description === CLAUDE_MEMORY_STOP_DESCRIPTION) return true;
+  if (isClaudeTelemetryEntry(entry)) return false;
+  return commandsMatch(entry, AW_MEMORY_SCRIPT_PATTERN);
+}
+
+// ── Merge / remove (pure; return new objects) ────────────────────────
+
+// A managed entry can also hold the user's own commands next to the AW ones.
+// Returns the entry with only the user's commands, or null when none are
+// left. An entry carrying an AW description belongs to AW and is dropped whole.
+function userPart(entry, pattern) {
+  if (entry?.description === CLAUDE_TELEMETRY_DESCRIPTION || entry?.description === CLAUDE_MEMORY_STOP_DESCRIPTION) return null;
+  const hooks = Array.isArray(entry?.hooks)
+    ? entry.hooks.filter(hook => !(typeof hook?.command === 'string' && pattern.test(hook.command.split('\\').join('/'))))
+    : [];
+  return hooks.length > 0 ? { ...entry, hooks } : null;
+}
+
+function removeManaged(entries, isManaged, pattern) {
+  return entries.flatMap(entry => {
+    if (!isManaged(entry)) return [entry];
+    const rest = userPart(entry, pattern);
+    return rest ? [rest] : [];
+  });
+}
+
+// Keeps unmanaged entries in order. The first managed entry is replaced in
+// place by `desired`; any further managed entries are dropped. The user's own
+// commands in a managed entry are kept, after it. When nothing managed exists,
+// `desired` is appended.
+function upsertManaged(entries, isManaged, pattern, desired) {
+  const out = [];
+  let placed = false;
+  for (const entry of entries) {
+    if (!isManaged(entry)) {
+      out.push(entry);
+      continue;
+    }
+    if (!placed) {
+      out.push(desired);
+      placed = true;
+    }
+    const rest = userPart(entry, pattern);
+    if (rest) out.push(rest);
+  }
+  if (!placed) out.push(desired);
+  return out;
+}
+
+function phaseEntries(hooks, phase) {
+  return Array.isArray(hooks?.[phase]) ? hooks[phase] : [];
+}
+
+function withPhase(hooks, phase, entries) {
+  const next = { ...hooks };
+  if (entries.length > 0) next[phase] = entries;
+  else delete next[phase];
+  return next;
+}
+
+/**
+ * Return a new Claude `hooks` object. Unrelated hooks keep their order.
+ *
+ * installed (every ~/.aw/aw-usage file present): exactly one aw-usage
+ * telemetry entry per phase and exactly one AW memory Stop entry.
+ *
+ * not installed (a copy failed): only entries pointing at ~/.aw/aw-usage are
+ * removed, since they would crash. Older entries that still work (aw-ecc, a
+ * combined telemetry + memory Stop) stay exactly as they are, and the memory
+ * entry is added only when nothing already runs the memory scripts.
+ * @param {Record<string, unknown[]>} hooks
+ * @param {{ installed: boolean }} opts
+ */
+export function mergeClaudeAwUsageHooks(hooks, { installed }) {
+  let next = hooks && typeof hooks === 'object' && !Array.isArray(hooks) ? { ...hooks } : {};
+  if (!installed) {
+    for (const def of CLAUDE_TELEMETRY_PHASES) {
+      next = withPhase(next, def.phase, removeManaged(phaseEntries(next, def.phase), entry => commandsMatch(entry, COPY_A_SCRIPT_PATTERN), COPY_A_SCRIPT_PATTERN));
+    }
+    const stop = phaseEntries(next, 'Stop');
+    const memoryRuns = stop.some(entry => isClaudeMemoryStopEntry(entry) || commandsMatch(entry, AW_MEMORY_SCRIPT_PATTERN));
+    return memoryRuns ? next : withPhase(next, 'Stop', [...stop, buildClaudeMemoryStopEntry()]);
+  }
+  for (const def of CLAUDE_TELEMETRY_PHASES) {
+    next = withPhase(next, def.phase, upsertManaged(phaseEntries(next, def.phase), isClaudeTelemetryEntry, AW_USAGE_SCRIPT_PATTERN, buildClaudeTelemetryEntry(def)));
+  }
+  return withPhase(next, 'Stop', upsertManaged(phaseEntries(next, 'Stop'), isClaudeMemoryStopEntry, AW_MEMORY_SCRIPT_PATTERN, buildClaudeMemoryStopEntry()));
+}
+
+/** Return a new Claude `hooks` object without aw-usage telemetry or AW memory
+ *  Stop entries. Only the five telemetry phases are cleaned; aw-usage entries
+ *  under any other event are left alone, as they were never AW-managed. */
+export function removeClaudeAwUsageHooks(hooks) {
+  let next = hooks && typeof hooks === 'object' && !Array.isArray(hooks) ? { ...hooks } : {};
+  for (const def of CLAUDE_TELEMETRY_PHASES) {
+    if (!Array.isArray(next[def.phase])) continue;
+    next = withPhase(next, def.phase, removeManaged(phaseEntries(next, def.phase), isClaudeTelemetryEntry, AW_USAGE_SCRIPT_PATTERN));
+  }
+  if (Array.isArray(next.Stop)) {
+    next = withPhase(next, 'Stop', removeManaged(phaseEntries(next, 'Stop'), isClaudeMemoryStopEntry, AW_MEMORY_SCRIPT_PATTERN));
+  }
+  return next;
+}

package/codex.mjs

@@ -17,6 +17,8 @@ const CLAUDE_PROMPT_COMMAND = 'bash "${CLAUDE_PROJECT_DIR}/scripts/hooks/session
 const CONFIG_FILE_MARKER = '# aw-managed-file: codex-ecc-baseline';
 const HOOK_LINE_MARKER = '# aw-managed: codex_hooks';
 const HOOK_LINE_REPLACED_MARKER = '# aw-managed: codex_hooks restored-from-false';
+const HOOKS_FEATURE_MARKER = '# aw-managed: hooks';
+const FEATURES_LINES = ['[features]', 'hooks = true', 'codex_hooks = true'];
 const FEATURES_BLOCK_NAME = 'features';
 const AW_SESSION_START_MARKER = '# aw-managed: codex-aw-session-start';
 const SUPPORTED_CODEX_WORKSPACE_PHASES = new Set(
@@ -207,7 +209,7 @@ function ensureCodexConfig(filePath) {
   }
 
   let next = existing;
-  next = ensureCodexHookEnabled(next);
+  next = ensureCodexHooksFeature(next, { marked: true });
   next = ensureManagedServerBlocks(next);
 
   if (next === existing) {
@@ -673,6 +675,10 @@ function removeManagedCodexConfig(filePath) {
     new RegExp(`^\\s*codex_hooks\\s*=\\s*true\\s*${escapeRegExp(HOOK_LINE_REPLACED_MARKER)}\\s*$\\n?`, 'm'),
     'codex_hooks = false\n'
   );
+  next = next.replace(
+    new RegExp(`^\\s*hooks\\s*=\\s*true\\s*${escapeRegExp(HOOKS_FEATURE_MARKER)}\\s*$\\n?`, 'm'),
+    ''
+  );
 
   next = tidyToml(next);
 
@@ -703,25 +709,74 @@ function ensureManagedServerBlocks(content) {
   return tidyToml(next);
 }
 
-function ensureCodexHookEnabled(content) {
-  if (/^\s*codex_hooks\s*=\s*true\b/m.test(content)) {
-    return content;
-  }
+// ── Codex hooks feature flag ─────────────────────────────────────────
+// Codex runs hooks only when [features] enables them. Codex 0.155.1 reads
+// `hooks` and warns that the older `codex_hooks` is deprecated; older Codex
+// versions read only `codex_hooks`. AW writes both and treats either as
+// enabled. A `hooks = false` the user wrote wins and is never overridden.
+// Used by this file (workspace config, aw-managed markers) and startup.mjs
+// (~/.codex/config.toml, no markers) so both writers agree.
+
+const FEATURES_HEADER = /^\[features\][ \t]*(?:#[^\r\n]*)?\r?$/m;
+// `features.hooks = …` or `features = { … }`: a form this writer does not edit.
+const FEATURES_OTHER_FORM = /^[ \t]*features[ \t]*[.=]/m;
+
+// [start, end) of the [features] table body, or null when there is none.
+function featuresBody(content) {
+  const header = content.match(FEATURES_HEADER);
+  if (!header || header.index === undefined) return null;
+  const start = header.index + header[0].length;
+  const nextTable = content.slice(start).search(/^[ \t]*\[/m);
+  return { start, end: nextTable === -1 ? content.length : start + nextTable };
+}
 
-  if (/^\s*codex_hooks\s*=\s*false\b/m.test(content)) {
-    return content.replace(
-      /^\s*codex_hooks\s*=\s*false\b.*$/m,
-      `codex_hooks = true ${HOOK_LINE_REPLACED_MARKER}`
-    );
-  }
+// true / false for `key = true|false` in [features]; 'other' for any other
+// value (left to the user); null when the key is absent.
+function featureFlag(content, key) {
+  const dotted = content.match(new RegExp(`^[ \\t]*features\\.${key}[ \\t]*=[ \\t]*(true|false)\\b`, 'm'));
+  if (dotted) return dotted[1] === 'true';
+  const body = featuresBody(content);
+  if (!body) return null;
+  const match = content.slice(body.start, body.end).match(new RegExp(`^[ \\t]*${key}[ \\t]*=[ \\t]*(\\S*)`, 'm'));
+  if (!match) return null;
+  if (/^true\b/.test(match[1])) return true;
+  if (/^false\b/.test(match[1])) return false;
+  return 'other';
+}
 
-  const featuresHeaderMatch = content.match(/^\[features\]\s*$/m);
-  if (featuresHeaderMatch && featuresHeaderMatch.index !== undefined) {
-    const insertAt = featuresHeaderMatch.index + featuresHeaderMatch[0].length;
-    return `${content.slice(0, insertAt)}\ncodex_hooks = true ${HOOK_LINE_MARKER}${content.slice(insertAt)}`;
-  }
+export function codexHooksFeatureEnabled(content) {
+  const hooks = featureFlag(content, 'hooks');
+  if (hooks === true || hooks === false) return hooks;
+  return featureFlag(content, 'codex_hooks') === true;
+}
 
-  return tidyToml(`${content.trimEnd()}\n\n${buildManagedBlock(FEATURES_BLOCK_NAME, ['[features]', 'codex_hooks = true'])}\n`);
+/**
+ * Return content with Codex hooks enabled under both feature names.
+ * @param {string} content config.toml text
+ * @param {{ marked?: boolean }} [opts] marked: tag added lines as aw-managed so remove can undo them
+ */
+export function ensureCodexHooksFeature(content, { marked = false } = {}) {
+  if (featureFlag(content, 'hooks') === false || FEATURES_OTHER_FORM.test(content)) return content;
+  const tag = marker => (marked ? ` ${marker}` : '');
+
+  let next = content;
+  if (featureFlag(next, 'codex_hooks') === false) {
+    const body = featuresBody(next);
+    const section = next.slice(body.start, body.end)
+      .replace(/^[ \t]*codex_hooks[ \t]*=[ \t]*false\b[^\r\n]*/m, `codex_hooks = true${tag(HOOK_LINE_REPLACED_MARKER)}`);
+    next = next.slice(0, body.start) + section + next.slice(body.end);
+  }
+
+  const missing = [];
+  if (featureFlag(next, 'hooks') === null) missing.push(`hooks = true${tag(HOOKS_FEATURE_MARKER)}`);
+  if (featureFlag(next, 'codex_hooks') === null) missing.push(`codex_hooks = true${tag(HOOK_LINE_MARKER)}`);
+  if (missing.length === 0) return next;
+
+  const body = featuresBody(next);
+  if (body) return `${next.slice(0, body.start)}\n${missing.join('\n')}${next.slice(body.start)}`;
+  if (marked) return tidyToml(`${next.trimEnd()}\n\n${buildManagedBlock(FEATURES_BLOCK_NAME, FEATURES_LINES)}\n`);
+  const trimmed = next.trimEnd();
+  return `${trimmed ? `${trimmed}\n\n` : ''}${FEATURES_LINES.join('\n')}\n`;
 }
 
 function buildManagedConfigFile() {
@@ -739,7 +794,7 @@ function buildManagedConfigFile() {
     lines.push('', ...buildManagedBlockLines(serverBlockName(server.name), server.lines));
   }
 
-  lines.push('', ...buildManagedBlockLines(FEATURES_BLOCK_NAME, ['[features]', 'codex_hooks = true']));
+  lines.push('', ...buildManagedBlockLines(FEATURES_BLOCK_NAME, FEATURES_LINES));
   return `${lines.join('\n')}\n`;
 }
 
@@ -827,7 +882,7 @@ function pruneEmptyDir(dirPath) {
 
 function isLegacyHookOnlyConfig(content) {
   const trimmed = content.trim();
-  return trimmed === '[features]\ncodex_hooks = true';
+  return trimmed === '[features]\ncodex_hooks = true' || trimmed === FEATURES_LINES.join('\n');
 }
 
 function escapeRegExp(value) {

package/commands/c4.mjs

@@ -101,11 +101,13 @@ function safeReaddirSync(dir) {
   try { return readdirSync(dir); } catch { return []; }
 }
 
-function safeListNamespaceDirs(dir) {
+function safeListNamespaceDirs(dir, fs = {}) {
+  const readdir = fs.readdirSync ?? readdirSync;
+  const stat = fs.statSync ?? statSync;
   try {
-    return readdirSync(dir).filter((entry) => {
+    return readdir(dir).filter((entry) => {
       if (entry.startsWith('.')) return false;
-      try { return statSync(join(dir, entry)).isDirectory(); } catch { return false; }
+      try { return stat(join(dir, entry)).isDirectory(); } catch { return false; }
     });
   } catch { return []; }
 }
@@ -411,11 +413,11 @@ export async function c4Command(rawArgs, overrides = {}) {
   // check, so we specifically look for directories (namespaces like
   // "platform") to confirm the registry content was actually pulled.
   {
-    const registryNamespaces = safeListNamespaceDirs(awRegistry);
+    const registryNamespaces = safeListNamespaceDirs(awRegistry, fs);
     if (registryNamespaces.length === 0) {
       writer.stderr('[aw-c4] registry has no namespace directories after init — retrying with aw pull\n');
       const pullRes = spawnSync('aw', ['pull'], { stdio: 'pipe' });
-      if (pullRes?.status !== 0 || safeListNamespaceDirs(awRegistry).length === 0) {
+      if (pullRes?.status !== 0 || safeListNamespaceDirs(awRegistry, fs).length === 0) {
         writer.stderr('[aw-c4] FATAL: registry commands were not fetched\n');
         return exit(1);
       }