create-walle 0.9.21 → 0.9.23

package/template/claude-task-manager/lib/node-pin-guard.js

@@ -0,0 +1,93 @@
+'use strict';
+// Local-only Node.js version guard for the CTM + Wall-E monorepo.
+//
+// Why: the daemon, /ctm-dev, and skill subprocesses share a single compiled
+// better-sqlite3 / sqlite-vec / tree-sitter binary, which is built for ONE Node
+// major (ABI). Launching under a different major corrupts that binary and
+// crash-loops the daemon ("MCP never became ready" + skill-failure storm).
+//
+// This guard activates ONLY inside the owner's repo, identified by a
+// `.node-version` pin file sitting beside `wall-e/` and `claude-task-manager/`.
+// In a shipped create-walle install the pin is excluded from the package
+// (see create-walle/build.sh), so findPinRoot() returns null and this is a
+// silent no-op — it never constrains other users' Node version.
+
+const fs = require('fs');
+const path = require('path');
+
+// Walk up from startDir until we find the monorepo root: a directory that has a
+// `.node-version` pin AND both project dirs. The triple condition prevents us
+// from hijacking an unrelated `.node-version` somewhere above a user's install.
+function findPinRoot(startDir) {
+  let dir = startDir;
+  for (;;) {
+    if (
+      fs.existsSync(path.join(dir, '.node-version')) &&
+      fs.existsSync(path.join(dir, 'wall-e')) &&
+      fs.existsSync(path.join(dir, 'claude-task-manager'))
+    ) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function readPin(root) {
+  try {
+    return fs.readFileSync(path.join(root, '.node-version'), 'utf8').replace(/[v\s]/g, '');
+  } catch {
+    return '';
+  }
+}
+
+// Assert the running Node matches the pinned MAJOR (the ABI-critical part — a
+// patch bump within the line keeps the same NODE_MODULE_VERSION). On mismatch:
+// hard-fail with remediation (default) or throw when opts.throwInstead is set.
+// Returns {pinned:false} as a no-op when there is no pin (shipped / non-owner).
+function assertPinnedNode(opts = {}) {
+  const startDir = opts.startDir || __dirname;
+  const root = findPinRoot(startDir);
+  if (!root) return { pinned: false };
+  const pin = readPin(root);
+  if (!pin) return { pinned: false };
+
+  const pinnedMajor = pin.split('.')[0];
+  const runningMajor = process.versions.node.split('.')[0];
+  if (runningMajor === pinnedMajor) {
+    return { pinned: true, ok: true, root, pin, running: process.versions.node };
+  }
+
+  if (opts.throwInstead) {
+    const err = new Error(
+      `Node version mismatch: pinned v${pin} (major ${pinnedMajor}), running v${process.versions.node}`
+    );
+    err.code = 'NODE_PIN_MISMATCH';
+    throw err;
+  }
+
+  const resolver = path.join(root, 'bin', 'node-bin.sh');
+  const devSh = path.join(root, 'bin', 'dev.sh');
+  process.stderr.write(
+    [
+      '',
+      '  ✖ Wrong Node.js version for CTM + Wall-E.',
+      `      pinned : v${pin}  (ABI line ${pinnedMajor}.x)`,
+      `      running: v${process.versions.node}  (NODE_MODULE_VERSION ${process.versions.modules})`,
+      '',
+      '  The shared native modules (better-sqlite3, sqlite-vec, tree-sitter) are',
+      '  compiled for ONE Node major. Launching under another major corrupts that',
+      '  binary and crash-loops the daemon. Start through the pinned launcher:',
+      '',
+      `      "$(bash ${resolver})" <script>      # resolves the pinned node`,
+      `      bash ${devSh}                        # isolated dev instance`,
+      `      fnm use ${pin}   |   nvm use ${pin}    # then re-run`,
+      '',
+    ].join('\n') + '\n'
+  );
+  process.exit(78); // EX_CONFIG
+  return { pinned: true, ok: false }; // unreachable
+}
+
+module.exports = { assertPinnedNode, findPinRoot, readPin };

package/template/claude-task-manager/lib/perf-tracker.js

@@ -12,9 +12,177 @@
 // Cost: two property writes per wrapped call. Negligible.
 
 let _current = null;
+let _lastCompleted = null;
 const _debug = process.env.CTM_PERF_DEBUG === '1';
 
-function getOp() { return _current; }
+// Perf diagnostic console output ([perf-lag] / [freeze-probe]) is OFF by default — once the hot
+// paths are tuned, the per-block log lines are noise. The rolling stats are STILL recorded (always
+// queryable at GET /api/diagnostics/event-loop), and CRITICAL freezes (>= PERF_CRITICAL_MS) are
+// ALWAYS logged so a genuine multi-second stall is never silently swallowed. Flip CTM_PERF_LOGS=1
+// (or CTM_PERF_DEBUG=1) to restore full verbose perf logging while debugging.
+const PERF_CRITICAL_MS = (() => {
+  const n = Number(process.env.CTM_PERF_CRITICAL_MS);
+  return Number.isFinite(n) && n > 0 ? n : 2000;
+})();
+// Re-read the env each call so the flag is runtime-toggleable (and testable) — no restart needed
+// to flip verbose perf logging on/off. Cheap: a couple of process.env property reads.
+function perfLogsEnabled() {
+  return process.env.CTM_PERF_LOGS === '1' || process.env.CTM_PERF_DEBUG === '1';
+}
+function shouldLogPerf(durMs) { return perfLogsEnabled() || Number(durMs) >= PERF_CRITICAL_MS; }
+
+// Ring buffer of recently-completed spans. `getOp()` only names the single op active
+// (or last completed within 1s) when a [perf-lag] block fires — but a freeze is often
+// the SUM of several sync chunks running back-to-back after awaits, the last of which
+// is `(unknown)`. This trail ("what ran in the last few seconds, and for how long")
+// turns an anonymous block into an attributable one. Cheap: one push per span over a
+// small threshold, capped length.
+const _RECENT_SPAN_MIN_MS = (() => {
+  const n = Number(process.env.CTM_PERF_SPAN_MIN_MS);
+  return Number.isFinite(n) && n >= 0 ? n : 20;
+})();
+const _RECENT_SPANS_MAX = 24;
+const _recentSpans = []; // {name, dur, end}
+function _recordSpan(name, dur) {
+  if (dur < _RECENT_SPAN_MIN_MS) return;
+  _recentSpans.push({ name, dur, end: Date.now() });
+  if (_recentSpans.length > _RECENT_SPANS_MAX) _recentSpans.shift();
+}
+// Most-recent-first list of spans that ended within maxAgeMs, plus their summed time
+// grouped by name. Read only on the slow path (when a lag line is being emitted).
+function getRecentSpans({ maxAgeMs = 3000, limit = 8 } = {}) {
+  const cutoff = Date.now() - maxAgeMs;
+  const recent = [];
+  const byName = new Map();
+  for (let i = _recentSpans.length - 1; i >= 0; i--) {
+    const s = _recentSpans[i];
+    if (s.end < cutoff) break;
+    if (recent.length < limit) recent.push(s);
+    byName.set(s.name, (byName.get(s.name) || 0) + s.dur);
+  }
+  const top = Array.from(byName.entries())
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit)
+    .map(([name, ms]) => ({ name, ms }));
+  return { recent, top };
+}
+
+// Phase 5: continuous event-loop budget. The lag detector feeds every block here so a
+// rolling window of "blocked ms attributed by op" is queryable (GET /api/diagnostics/
+// event-loop) instead of only grep-able after the fact. Cumulative-since-reset (?reset=1
+// for windowed sampling), matching the write-lock diagnostics. Blocks >= the sleep
+// threshold (laptop suspend → a giant wall-clock gap, not a real freeze) are bucketed
+// separately so they don't pollute the named op stats.
+const _SLEEP_BLOCK_MS = (() => {
+  const n = Number(process.env.CTM_SLEEP_BLOCK_MS);
+  return Number.isFinite(n) && n > 0 ? n : 20000;
+})();
+let _blockSince = Date.now();
+let _blockCount = 0;
+let _blockSumMs = 0;
+let _blockMaxMs = 0;
+let _blockUnknownMs = 0;
+let _sleepCount = 0;
+let _sleepMs = 0;
+const _blockByOp = new Map(); // name -> { count, sumMs, maxMs }
+
+// GC-pause attribution. A major GC on CTM's multi-GB heap can pause the loop
+// 100-400ms, and the lag detector blames that pause on whatever synchronous op
+// happened to be running (pty:processData, scrollback-snapshot, ...) — producing
+// scattered ~400ms blocks with no single fixable cause. Observing GC directly
+// lets the diagnostic answer "was that block GC or real CPU?": compare gc.maxMs
+// to maxBlockMs (close → the big block was a GC pause, not code to optimize).
+// Read-only: receiving GC entries does not change GC behavior. The observer is
+// cheap (V8 emits these regardless; the callback only bumps counters). Disable
+// with CTM_TRACK_GC=0 if the observer itself is ever suspected.
+let _gcCount = 0;
+let _gcMs = 0;
+let _gcMaxMs = 0;
+const _gcByKind = new Map(); // kind -> { count, ms, maxMs }
+// performance GC entry `kind` flags (perf_hooks NODE_PERFORMANCE_GC_*).
+const _GC_KIND = { 1: 'minor', 2: 'major', 4: 'incremental', 8: 'weakcb' };
+let _gcObserver = null;
+function _startGcObserver() {
+  if (_gcObserver || process.env.CTM_TRACK_GC === '0') return;
+  try {
+    const { PerformanceObserver } = require('perf_hooks');
+    _gcObserver = new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        const ms = Number(entry.duration) || 0;
+        _gcCount += 1;
+        _gcMs += ms;
+        if (ms > _gcMaxMs) _gcMaxMs = ms;
+        const flag = entry.detail ? entry.detail.kind : entry.kind;
+        const kind = _GC_KIND[flag] || 'gc';
+        const e = _gcByKind.get(kind) || { count: 0, ms: 0, maxMs: 0 };
+        e.count += 1; e.ms += ms; if (ms > e.maxMs) e.maxMs = ms;
+        _gcByKind.set(kind, e);
+      }
+    });
+    _gcObserver.observe({ entryTypes: ['gc'], buffered: false });
+    if (typeof _gcObserver.unref === 'function') _gcObserver.unref();
+  } catch { _gcObserver = null; }
+}
+_startGcObserver();
+function recordEventLoopBlock(name, blockedMs) {
+  const ms = Math.max(0, Number(blockedMs) || 0);
+  if (ms <= 0) return;
+  if (ms >= _SLEEP_BLOCK_MS) { _sleepCount += 1; _sleepMs += ms; return; }
+  _blockCount += 1;
+  _blockSumMs += ms;
+  if (ms > _blockMaxMs) _blockMaxMs = ms;
+  const key = String(name || '(unknown)');
+  if (key.includes('(unknown)')) _blockUnknownMs += ms;
+  const e = _blockByOp.get(key) || { count: 0, sumMs: 0, maxMs: 0 };
+  e.count += 1; e.sumMs += ms; if (ms > e.maxMs) e.maxMs = ms;
+  _blockByOp.set(key, e);
+}
+function getEventLoopStats({ reset = false } = {}) {
+  const now = Date.now();
+  const windowMs = Math.max(1, now - _blockSince);
+  const topOps = Array.from(_blockByOp.entries())
+    .map(([name, e]) => ({ name, count: e.count, sumMs: e.sumMs, maxMs: e.maxMs }))
+    .sort((a, b) => b.sumMs - a.sumMs)
+    .slice(0, 15);
+  const gcByKind = Array.from(_gcByKind.entries())
+    .map(([kind, e]) => ({ kind, count: e.count, ms: Math.round(e.ms), maxMs: Math.round(e.maxMs) }))
+    .sort((a, b) => b.ms - a.ms);
+  const snap = {
+    windowMs,
+    blocks: _blockCount,
+    totalBlockedMs: _blockSumMs,
+    maxBlockMs: _blockMaxMs,
+    busyPct: Math.round(1000 * _blockSumMs / windowMs) / 10, // % of wall-clock spent in >threshold blocks
+    unknownMs: _blockUnknownMs,
+    unknownSharePct: _blockSumMs > 0 ? Math.round(100 * _blockUnknownMs / _blockSumMs) : 0,
+    suspectedSleep: { count: _sleepCount, ms: _sleepMs },
+    topOps,
+    // GC pauses over the same window. Compare gc.maxMs to maxBlockMs: if they're
+    // close, the worst block was a GC pause (heap pressure), not a sync op to
+    // optimize. enabled:false means the observer was turned off (CTM_TRACK_GC=0).
+    gc: {
+      enabled: !!_gcObserver,
+      count: _gcCount,
+      ms: Math.round(_gcMs),
+      maxMs: Math.round(_gcMaxMs),
+      byKind: gcByKind,
+    },
+  };
+  if (reset) {
+    _blockSince = now; _blockCount = 0; _blockSumMs = 0; _blockMaxMs = 0;
+    _blockUnknownMs = 0; _sleepCount = 0; _sleepMs = 0; _blockByOp.clear();
+    _gcCount = 0; _gcMs = 0; _gcMaxMs = 0; _gcByKind.clear();
+  }
+  return snap;
+}
+
+function getOp() {
+  if (_current) return _current;
+  if (_lastCompleted && Date.now() - _lastCompleted.end <= 1000) {
+    return { name: `${_lastCompleted.name} (last completed)`, start: _lastCompleted.start };
+  }
+  return null;
+}
 
 function eventLoopBlockMs(deltaMs, intervalMs = 100) {
   return Math.max(0, Number(deltaMs || 0) - Number(intervalMs || 0));
@@ -44,17 +212,27 @@ function wrap(name, fn) {
       if (_debug && Date.now() - t0 > 100) console.warn(`[perf] ${name} threw after ${Date.now() - t0}ms`);
       throw e;
     }
+    // Synchronous-prefix duration: the time fn() ran on the loop before returning. For an
+    // async function this is the only part that BLOCKED the event loop — the awaited time
+    // afterward is I/O wait, not a block. Recording wall-clock for async spans made the
+    // recent-spans trail over-attribute (e.g. an async health tick showed "1243ms" that was
+    // mostly network wait, not a freeze). Record the sync prefix so the trail is faithful.
+    const syncDur = Date.now() - t0;
     // Promise/thenable: the synchronous prefix is done. Clear the tag now so
     // unrelated timers do not inherit a stale "active op" while this awaits I/O.
     if (result && typeof result.then === 'function') {
       _current = prev;
+      _recordSpan(name, syncDur); // only the sync prefix counts as a loop block
       return result.finally(() => {
-        const dur = Date.now() - t0;
-        if (_debug && dur > 100) console.warn(`[perf] ${name} took ${dur}ms`);
+        const dur = Date.now() - t0; // wall-clock — for the "(last completed)" attribution only
+        if (dur > 100) _lastCompleted = { name, start: t0, end: Date.now(), dur };
+        if (_debug && dur > 100) console.warn(`[perf] ${name} took ${dur}ms (incl await)`);
       });
     }
-    // Sync: restore immediately and pass through.
-    const dur = Date.now() - t0;
+    // Sync: restore immediately and pass through. The whole call blocked the loop.
+    const dur = syncDur;
+    if (dur > 100) _lastCompleted = { name, start: t0, end: Date.now(), dur };
+    _recordSpan(name, dur);
     _current = prev;
     if (_debug && dur > 100) console.warn(`[perf] ${name} took ${dur}ms`);
     return result;
@@ -64,4 +242,62 @@ function wrap(name, fn) {
 // Back-compat alias — both behave identically now (smart sync/async detection).
 const wrapAsync = wrap;
 
-module.exports = { eventLoopBlockMs, getOp, shouldReportLag, wrap, wrapAsync };
+/**
+ * Run a synchronous block as a named span and return its result.
+ *
+ * Why this exists: `wrap()` tags an async function only for its synchronous
+ * prefix, then clears the tag at the first `await`. So a heavy synchronous
+ * CHUNK that runs *after* an await (a per-row DB loop, a big JSON.parse) is
+ * invisible — the event-loop-lag detector fires in a later timer tick and sees
+ * `(unknown)`. Wrapping that chunk with `runSync('name', () => {...})` records
+ * it into `_lastCompleted`, so `getOp()` can attribute the block within 1s.
+ * Use around whole chunks, not per loop iteration (one closure alloc per call).
+ */
+function runSync(name, fn) {
+  return wrap(name, fn)();
+}
+
+// Default freeze-probe threshold (ms). A single synchronous span over this bound
+// is a user-perceptible stall on a single-threaded server. Overridable per call.
+const FREEZE_PROBE_MS = (() => {
+  const n = Number(process.env.CTM_FREEZE_PROBE_MS);
+  return Number.isFinite(n) && n > 0 ? n : 150;
+})();
+
+/**
+ * Run a synchronous block as a named span AND emit a one-line `[freeze-probe]`
+ * diagnostic when it exceeds a threshold. Builds on runSync() (so the span is
+ * still attributed to getOp()), but additionally logs WHY the loop froze with
+ * caller-supplied context — turning the next freeze into a self-describing log
+ * entry instead of an anonymous `(unknown)` lag block.
+ *
+ * @param {string} name span name (also the freeze-probe `where`)
+ * @param {() => any} fn the synchronous work
+ * @param {object} [opts]
+ * @param {number} [opts.thresholdMs] override the default threshold
+ * @param {() => object} [opts.context] lazily-built context object, only invoked
+ *        on the slow path (so the common fast path pays nothing). Keys are logged
+ *        as `k=v` pairs.
+ */
+function runSyncProbed(name, fn, opts = {}) {
+  const t0 = Date.now();
+  try {
+    return wrap(name, fn)();
+  } finally {
+    const dur = Date.now() - t0;
+    const threshold = Number(opts.thresholdMs) > 0 ? Number(opts.thresholdMs) : FREEZE_PROBE_MS;
+    if (dur >= threshold && shouldLogPerf(dur)) {
+      let ctxStr = '';
+      try {
+        const ctx = typeof opts.context === 'function' ? opts.context() : null;
+        if (ctx && typeof ctx === 'object') {
+          ctxStr = Object.keys(ctx).map((k) => `${k}=${ctx[k]}`).join(' ');
+        }
+      } catch { /* context build must never break the probe */ }
+      // eslint-disable-next-line no-console
+      console.warn(`[freeze-probe] ${name} blocked ${dur}ms${ctxStr ? ' ' + ctxStr : ''}`);
+    }
+  }
+}
+
+module.exports = { eventLoopBlockMs, getOp, getRecentSpans, recordEventLoopBlock, getEventLoopStats, shouldReportLag, wrap, wrapAsync, runSync, runSyncProbed, FREEZE_PROBE_MS, perfLogsEnabled, shouldLogPerf, PERF_CRITICAL_MS };

package/template/claude-task-manager/lib/permission-match.js

@@ -0,0 +1,76 @@
+'use strict';
+
+// Match a detected approval command against the user's Permission Manager rules
+// (the `perm_rules` table — Claude-syntax "Bash(node:*)" allow/deny entries).
+//
+// These rules otherwise only configure Claude Code's own settings.json, so they
+// don't apply to Codex/other providers and the shadow approver never honored
+// them. This lets the approver respect the user's explicit allow/deny across ALL
+// providers: an allow match → auto-approve (skip the verifier); a deny match →
+// escalate. An allow rule marked always_ask is treated as "ask" (no auto-approve).
+
+// Parse a "Tool(spec)" rule into { tool, wildcard|prefix|exact }.
+function parseRule(rule) {
+  const raw = String(rule || '').trim();
+  const m = raw.match(/^([A-Za-z_][\w-]*)\((.*)\)$/);
+  if (!m) {
+    // Bare tool name (e.g. "Read") = the whole tool is covered.
+    return raw ? { tool: raw, wildcard: true } : null;
+  }
+  const tool = m[1];
+  const spec = m[2].trim();
+  if (spec === '' || spec === '*') return { tool, wildcard: true };
+  if (spec.endsWith(':*')) return { tool, prefix: spec.slice(0, -2).trim() };
+  return { tool, exact: spec };
+}
+
+// Reduce a displayed tool header ("⏺ Bash command", "Bash(...)", "Edit") to a
+// bare tool word ("Bash", "Edit").
+function toolOf(toolName) {
+  const t = String(toolName || '').replace(/^[^A-Za-z]+/, '').trim();
+  return (t.split(/[\s(]/)[0] || '');
+}
+
+// Does `command` fall under a parsed rule's spec? Prefix matches require a word
+// boundary so "Bash(node:*)" does not match "nodejs ...".
+function commandMatchesSpec(command, parsed) {
+  if (!parsed) return false;
+  if (parsed.wildcard) return true;
+  const cmd = String(command || '').trim();
+  if (parsed.exact != null) return cmd === parsed.exact;
+  const p = parsed.prefix;
+  if (!p) return false;
+  if (cmd === p) return true;
+  if (cmd.startsWith(p)) {
+    // Boundary: the next char must not continue a word, so "node" does not match
+    // "nodejs" but "node -e require" still matches "node -e require(...)".
+    const next = cmd.charAt(p.length);
+    return next === '' || !/[A-Za-z0-9_]/.test(next);
+  }
+  return false;
+}
+
+// Evaluate a command against the user's perm_rules.
+// Returns { action: 'deny', rule } | { action: 'allow', rule } | null.
+// Deny wins over allow. allow rules with always_ask are skipped (the user wants
+// to keep being asked).
+function matchPermission({ toolName, command } = {}, rules = []) {
+  const tool = toolOf(toolName);
+  const looksBash = /^bash$/i.test(tool) || /\bbash\b/i.test(String(toolName || ''));
+  let allowHit = null;
+  for (const r of rules || []) {
+    const parsed = parseRule(r.rule);
+    if (!parsed) continue;
+    const ruleTool = String(parsed.tool || '').toLowerCase();
+    const toolMatch = ruleTool === tool.toLowerCase() || (looksBash && ruleTool === 'bash');
+    if (!toolMatch) continue;
+    if (!commandMatchesSpec(command, parsed)) continue;
+    if (r.list_type === 'deny') return { action: 'deny', rule: r.rule };
+    if (r.list_type === 'allow' && !(r.always_ask)) {
+      if (!allowHit) allowHit = { action: 'allow', rule: r.rule };
+    }
+  }
+  return allowHit;
+}
+
+module.exports = { parseRule, toolOf, commandMatchesSpec, matchPermission };

package/template/claude-task-manager/lib/permission-sync.js

@@ -19,12 +19,26 @@ function readJsonFile(filePath) {
   }
 }
 
+async function readJsonFileAsync(filePath) {
+  try {
+    return JSON.parse(await fs.promises.readFile(filePath, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
 function writeJsonFile(filePath, data) {
   const dir = path.dirname(filePath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
   fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
 }
 
+async function writeJsonFileAsync(filePath, data) {
+  const dir = path.dirname(filePath);
+  await fs.promises.mkdir(dir, { recursive: true });
+  await fs.promises.writeFile(filePath, JSON.stringify(data, null, 2));
+}
+
 function getProjectSettingsPath(projectPath) {
   return path.join(projectPath, '.claude', 'settings.local.json');
 }
@@ -35,6 +49,21 @@ function isValidPermRule(rule) {
   return true;
 }
 
+function pushSettingsRules(rules, settings, { scope, project }) {
+  const permissions = settings && settings.permissions || {};
+  for (const tool of permissions.allow || []) {
+    if (!isValidPermRule(tool)) {
+      console.warn(`  Skipping invalid perm rule: ${tool}`);
+      continue;
+    }
+    rules.push({ rule: tool, listType: 'allow', scope, project });
+  }
+  for (const tool of permissions.deny || []) {
+    if (!isValidPermRule(tool)) continue;
+    rules.push({ rule: tool, listType: 'deny', scope, project });
+  }
+}
+
 function getSettingsAllowList(settingsPath) {
   const settings = readJsonFile(settingsPath);
   return (settings.permissions && settings.permissions.allow) || [];
@@ -50,35 +79,40 @@ function collectJsonRules({ homeDir = process.env.HOME } = {}) {
   const globalSettingsPath = getGlobalSettingsPath(homeDir);
   const claudeJsonPath = getClaudeJsonPath(homeDir);
 
-  for (const tool of getSettingsAllowList(globalSettingsPath)) {
-    if (!isValidPermRule(tool)) {
-      console.warn(`  Skipping invalid perm rule: ${tool}`);
-      continue;
-    }
-    rules.push({ rule: tool, listType: 'allow', scope: 'global', project: '__global__' });
-  }
-  for (const tool of getSettingsDenyList(globalSettingsPath)) {
-    if (!isValidPermRule(tool)) continue;
-    rules.push({ rule: tool, listType: 'deny', scope: 'global', project: '__global__' });
-  }
+  pushSettingsRules(rules, readJsonFile(globalSettingsPath), { scope: 'global', project: '__global__' });
 
   const claudeJson = readJsonFile(claudeJsonPath);
   const projectPaths = Object.keys(claudeJson.projects || {});
   for (const projectPath of projectPaths) {
     const settingsPath = getProjectSettingsPath(projectPath);
-    for (const tool of getSettingsAllowList(settingsPath)) {
-      if (!isValidPermRule(tool)) {
-        console.warn(`  Skipping invalid perm rule: ${tool}`);
-        continue;
-      }
-      rules.push({ rule: tool, listType: 'allow', scope: 'project', project: projectPath });
-    }
-    for (const tool of getSettingsDenyList(settingsPath)) {
+    pushSettingsRules(rules, readJsonFile(settingsPath), { scope: 'project', project: projectPath });
+  }
+
+  for (const [projectPath, projectData] of Object.entries(claudeJson.projects || {})) {
+    const allowedTools = projectData.allowedTools || [];
+    for (const tool of allowedTools) {
       if (!isValidPermRule(tool)) continue;
-      rules.push({ rule: tool, listType: 'deny', scope: 'project', project: projectPath });
+      rules.push({ rule: tool, listType: 'allow', scope: 'project', project: projectPath });
     }
   }
 
+  return rules;
+}
+
+async function collectJsonRulesAsync({ homeDir = process.env.HOME } = {}) {
+  const rules = [];
+  const globalSettingsPath = getGlobalSettingsPath(homeDir);
+  const claudeJsonPath = getClaudeJsonPath(homeDir);
+
+  pushSettingsRules(rules, await readJsonFileAsync(globalSettingsPath), { scope: 'global', project: '__global__' });
+
+  const claudeJson = await readJsonFileAsync(claudeJsonPath);
+  const projectPaths = Object.keys(claudeJson.projects || {});
+  for (const projectPath of projectPaths) {
+    const settingsPath = getProjectSettingsPath(projectPath);
+    pushSettingsRules(rules, await readJsonFileAsync(settingsPath), { scope: 'project', project: projectPath });
+  }
+
   for (const [projectPath, projectData] of Object.entries(claudeJson.projects || {})) {
     const allowedTools = projectData.allowedTools || [];
     for (const tool of allowedTools) {
@@ -101,6 +135,32 @@ function mergeJsonRulesIntoDb(dbApi, options = {}) {
   return imported;
 }
 
+async function mergeJsonRulesIntoDbAsync(dbApi, options = {}) {
+  const jsonRules = await collectJsonRulesAsync(options);
+  return applyJsonRulesToDb(dbApi, jsonRules, { mergeOnly: true }).imported;
+}
+
+function applyJsonRulesToDb(dbApi, jsonRules, { mergeOnly = false } = {}) {
+  const rules = Array.isArray(jsonRules) ? jsonRules : [];
+  const existing = dbApi.listPermRules();
+  if (existing.length > 0 || mergeOnly) {
+    const before = existing.length;
+    for (const rule of rules) dbApi.addPermRule(rule);
+    const imported = dbApi.listPermRules().length - before;
+    if (imported > 0) {
+      console.log(`  Merged ${imported} new permission rules from JSON files into DB`);
+    }
+    return { imported, mode: 'merge' };
+  }
+
+  if (rules.length > 0) {
+    dbApi.bulkSetPermRules(rules);
+    console.log(`  Imported ${rules.length} permission rules from JSON files into DB`);
+    return { imported: rules.length, mode: 'bulk' };
+  }
+  return { imported: 0, mode: 'empty' };
+}
+
 function syncDbToJsonFiles(dbApi, { homeDir = process.env.HOME } = {}) {
   for (const rule of collectJsonRules({ homeDir })) dbApi.addPermRule(rule);
   for (const row of dbApi.listPermRules()) {
@@ -132,6 +192,37 @@ function syncDbToJsonFiles(dbApi, { homeDir = process.env.HOME } = {}) {
   }
 }
 
+async function syncDbToJsonFilesAsync(dbApi, { homeDir = process.env.HOME } = {}) {
+  for (const rule of await collectJsonRulesAsync({ homeDir })) dbApi.addPermRule(rule);
+  for (const row of dbApi.listPermRules()) {
+    if (!isValidPermRule(row.rule)) {
+      console.warn(`  Removing invalid perm rule from DB: ${row.rule}`);
+      dbApi.removePermRule({ rule: row.rule, listType: row.list_type, project: row.project });
+    }
+  }
+
+  const byProject = dbApi.getPermRulesByProject();
+  const globalSettingsPath = getGlobalSettingsPath(homeDir);
+  const globalRules = byProject.__global__ || { allow: [], deny: [] };
+  const globalSettings = await readJsonFileAsync(globalSettingsPath);
+  if (!globalSettings.permissions) globalSettings.permissions = {};
+  globalSettings.permissions.allow = globalRules.allow.filter(isValidPermRule);
+  globalSettings.permissions.deny = globalRules.deny.filter(isValidPermRule);
+  await writeJsonFileAsync(globalSettingsPath, globalSettings);
+
+  for (const [project, lists] of Object.entries(byProject)) {
+    if (project === '__global__') continue;
+    const settingsPath = getProjectSettingsPath(project);
+    try {
+      const settings = await readJsonFileAsync(settingsPath);
+      if (!settings.permissions) settings.permissions = {};
+      settings.permissions.allow = lists.allow.filter(isValidPermRule);
+      settings.permissions.deny = lists.deny.filter(isValidPermRule);
+      await writeJsonFileAsync(settingsPath, settings);
+    } catch {}
+  }
+}
+
 function importPermissionsToDb(dbApi, { syncBack = true, homeDir = process.env.HOME } = {}) {
   const existing = dbApi.listPermRules();
   if (existing.length > 0) {
@@ -148,15 +239,37 @@ function importPermissionsToDb(dbApi, { syncBack = true, homeDir = process.env.H
   }
 }
 
+async function importPermissionsToDbAsync(dbApi, {
+  syncBack = true,
+  homeDir = process.env.HOME,
+  applyWith = null,
+  applyRulesWith = null,
+} = {}) {
+  const rules = await collectJsonRulesAsync({ homeDir });
+  const apply = () => applyJsonRulesToDb(dbApi, rules);
+  const result = typeof applyRulesWith === 'function'
+    ? await applyRulesWith(rules, apply)
+    : (typeof applyWith === 'function' ? await applyWith(apply) : apply());
+  if (syncBack) await syncDbToJsonFilesAsync(dbApi, { homeDir });
+  return result;
+}
+
 module.exports = {
+  applyJsonRulesToDb,
   collectJsonRules,
+  collectJsonRulesAsync,
   getClaudeJsonPath,
   getGlobalSettingsPath,
   getProjectSettingsPath,
   importPermissionsToDb,
+  importPermissionsToDbAsync,
   isValidPermRule,
   mergeJsonRulesIntoDb,
+  mergeJsonRulesIntoDbAsync,
   readJsonFile,
+  readJsonFileAsync,
   syncDbToJsonFiles,
+  syncDbToJsonFilesAsync,
   writeJsonFile,
+  writeJsonFileAsync,
 };