@moxxy/core 0.3.0

package/src/events/log.ts

@@ -0,0 +1,256 @@
+import type {
+  EmittedEvent,
+  EventLogReader,
+  MoxxyEvent,
+  MoxxyEventOfType,
+  MoxxyEventType,
+  TurnId,
+} from '@moxxy/sdk';
+import { materializeEvent } from './factory.js';
+
+export type EventListener = (event: MoxxyEvent) => void | Promise<void>;
+
+export class EventLog implements EventLogReader {
+  private readonly events: MoxxyEvent[] = [];
+  private readonly listeners = new Set<EventListener>();
+  private readonly clearListeners = new Set<() => void>();
+  private readonly now: () => number;
+  /**
+   * Lazy secondary indexes so `ofType`/`byTurn` are O(matches) instead of an
+   * O(n) full-array `filter` per call (these back hot paths: token-accounting's
+   * `ofType('provider_response')`, lazy-tool gating's
+   * `ofType('tool_call_requested')`, and remote-session's per-turn
+   * `byTurn(turnId)` priming). Built lazily on first query so a cold/seeded log
+   * pays the one-time O(n) build only if anything ever queries it, then kept
+   * O(1) per append/ingest. Reset to `null` (rebuild-on-next-query) by
+   * `clear`/`rebase`, which mutate `events` wholesale.
+   *
+   * Each index holds the SAME event object references in their original
+   * append order — so a query returns an array deep-equal to the old
+   * `events.filter(...)` for every input.
+   */
+  private byType: Map<MoxxyEventType, MoxxyEvent[]> | null = null;
+  private byTurnId: Map<TurnId, MoxxyEvent[]> | null = null;
+  /**
+   * Seq of the FIRST event this log holds. 0 for an authoring log; a mirror
+   * primed by a partial attach replay (runner protocol v6 `replay.start`)
+   * rebases to the first replayed seq so `ingest`'s contiguity gate lines up
+   * with the runner's stream instead of expecting history we never received.
+   * `seq === base + index` for every held event.
+   */
+  private base = 0;
+
+  constructor(seed: ReadonlyArray<MoxxyEvent> = [], opts: { now?: () => number } = {}) {
+    this.now = opts.now ?? Date.now;
+    for (const e of seed) this.events.push(e);
+    // Align `base` to the first seeded event so `seq === base + index` holds
+    // regardless of where the seed starts. Today every caller seeds a log
+    // re-sequenced to 0..n-1 (so this is a no-op), but a caller seeding a tail
+    // slice (e.g. seq 50..) would otherwise get silently wrong at()/slice()
+    // seq-addressing and an off-by-`base` ingest() contiguity gate.
+    if (seed.length > 0) this.base = seed[0]!.seq;
+  }
+
+  get length(): number {
+    return this.events.length;
+  }
+
+  /** Seq of the first held event (see {@link rebase}). */
+  get baseSeq(): number {
+    return this.base;
+  }
+
+  at(seq: number): MoxxyEvent | undefined {
+    const index = seq - this.base;
+    if (index < 0 || index >= this.events.length) return undefined;
+    return this.events[index];
+  }
+
+  slice(from = 0, to: number = this.base + this.events.length): ReadonlyArray<MoxxyEvent> {
+    // Seq-addressed, like `at`. Events below the base were never held, so a
+    // `from` before it just clamps to everything we have.
+    return this.events.slice(Math.max(0, from - this.base), Math.max(0, to - this.base));
+  }
+
+  /** Build both secondary indexes from the current `events` array, preserving
+   * append order. Bucket arrays hold the original event references. */
+  private buildIndexes(): void {
+    const byType = new Map<MoxxyEventType, MoxxyEvent[]>();
+    const byTurnId = new Map<TurnId, MoxxyEvent[]>();
+    for (const e of this.events) {
+      let typeBucket = byType.get(e.type);
+      if (!typeBucket) byType.set(e.type, (typeBucket = []));
+      typeBucket.push(e);
+      let turnBucket = byTurnId.get(e.turnId);
+      if (!turnBucket) byTurnId.set(e.turnId, (turnBucket = []));
+      turnBucket.push(e);
+    }
+    this.byType = byType;
+    this.byTurnId = byTurnId;
+  }
+
+  /** Append one event to the live indexes (no-op while they're cold). Called
+   * after the event is pushed to `events`, so order is preserved. */
+  private indexEvent(e: MoxxyEvent): void {
+    if (this.byType) {
+      const bucket = this.byType.get(e.type);
+      if (bucket) bucket.push(e);
+      else this.byType.set(e.type, [e]);
+    }
+    if (this.byTurnId) {
+      const bucket = this.byTurnId.get(e.turnId);
+      if (bucket) bucket.push(e);
+      else this.byTurnId.set(e.turnId, [e]);
+    }
+  }
+
+  ofType<T extends MoxxyEventType>(type: T): ReadonlyArray<MoxxyEventOfType<T>> {
+    if (!this.byType) this.buildIndexes();
+    // The bucket already holds exactly the matching events in append order —
+    // identical to the old `events.filter(e => e.type === type)`. Return a copy
+    // so callers can't mutate the index (filter() also returned a fresh array).
+    const bucket = this.byType!.get(type);
+    // Bucket holds only events whose `type === T`, so the cast is sound; route
+    // through `unknown` because TS can't narrow the heterogeneous union here.
+    return (bucket ? [...bucket] : []) as unknown as ReadonlyArray<MoxxyEventOfType<T>>;
+  }
+
+  byTurn(turnId: TurnId): ReadonlyArray<MoxxyEvent> {
+    if (!this.byTurnId) this.buildIndexes();
+    const bucket = this.byTurnId!.get(turnId);
+    return bucket ? [...bucket] : [];
+  }
+
+  toJSON(): ReadonlyArray<MoxxyEvent> {
+    return [...this.events];
+  }
+
+  async append(partial: EmittedEvent): Promise<MoxxyEvent> {
+    const event = materializeEvent(partial, this.base + this.events.length, this.now);
+    this.events.push(event);
+    this.indexEvent(event);
+    // Snapshot listeners so a subscribe/unsubscribe during dispatch (e.g.,
+    // a runTurn finishing and unsubscribing while we're still mid-fanout)
+    // doesn't change the iteration target.
+    const snapshot = [...this.listeners];
+    for (const fn of snapshot) {
+      try {
+        await fn(event);
+      } catch {
+        // Listeners must not block the log; failures are non-fatal here. Hook
+        // failures are recorded as ErrorEvents by the dispatcher above this.
+      }
+    }
+    return event;
+  }
+
+  subscribe(fn: EventListener): () => void {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+
+  /**
+   * Append an already-materialized event, preserving its `id`/`seq`/`ts`
+   * rather than minting new ones. This is how a thin client mirrors the
+   * runner's log: the server is the sole authority for event identity, so the
+   * mirror must keep the originals. De-dupes by `seq` (idempotent replay) and
+   * fires listeners fire-and-forget - a mirror has no dispatcher to await.
+   *
+   * Not for normal authoring; use {@link append} for that.
+   */
+  ingest(event: MoxxyEvent): void {
+    // Contiguous, ordered delivery over a single socket means
+    // seq === base + index. Accept ONLY the next-expected seq: this drops
+    // duplicates (overlap between attach-replay and the live stream,
+    // seq < base + length) AND refuses a gap (seq > base + length) rather than
+    // pushing it at the wrong index, which would permanently desync `seq` from
+    // the array index. A gap can't happen over the reliable in-order
+    // transport, so refusing one is fail-safe.
+    if (event.seq !== this.base + this.events.length) return;
+    this.events.push(event);
+    this.indexEvent(event);
+    const snapshot = [...this.listeners];
+    for (const fn of snapshot) {
+      try {
+        // Fire-and-forget, but attach a rejection handler: an async listener
+        // that rejects must be swallowed the same way append()'s awaited
+        // try/catch swallows it — otherwise it surfaces as an unhandled
+        // rejection and (under Node's default policy) can kill the process.
+        void Promise.resolve(fn(event)).catch(() => {
+          // Mirror listeners must not break ingestion.
+        });
+      } catch {
+        // Mirror listeners must not break ingestion (synchronous throw).
+      }
+    }
+  }
+
+  /**
+   * Start this (empty) log at `seq` instead of 0. A mirror primed by a
+   * PARTIAL attach replay (`replay: 'none'` / `{ tail }`) calls this with the
+   * runner's announced first seq so {@link ingest}'s contiguity gate accepts
+   * the stream. Only valid while empty — rebasing held events would detach
+   * their seqs from their indices.
+   */
+  rebase(seq: number): void {
+    if (this.events.length > 0) {
+      throw new Error(`EventLog.rebase(${seq}): log already holds ${this.events.length} events`);
+    }
+    if (!Number.isInteger(seq) || seq < 0) {
+      throw new Error(`EventLog.rebase(${seq}): seq must be a non-negative integer`);
+    }
+    this.base = seq;
+    // Rebase only runs on an empty log, so the indexes (if warm) are already
+    // empty — but null them to stay defensive about the events-array invariant.
+    this.byType = null;
+    this.byTurnId = null;
+  }
+
+  /**
+   * Drop every event from the log. Used by `/new` to start a fresh
+   * session without rebuilding the entire Session object — the
+   * registries, resolvers, and active provider stay; only the
+   * conversation context vanishes. Per-event listeners are NOT
+   * notified (there's no "event removed" event in the schema), but
+   * {@link onClear} subscribers fire — that's how the persistence
+   * sidecar truncates its JSONL (so `--resume` can't resurrect wiped
+   * history) and how the runner broadcasts a reset to attached
+   * mirrors, in lockstep with the wipe.
+   *
+   * Safe to call only when no turn is in flight — callers should abort
+   * their AbortController and await any pending runTurn() first.
+   */
+  clear(): void {
+    this.events.length = 0;
+    // The secondary indexes mirror `events`; drop them so the next query
+    // rebuilds from the now-empty array (cheap) rather than serving stale
+    // buckets.
+    this.byType = null;
+    this.byTurnId = null;
+    // A session reset restarts the authoritative stream at seq 0 — a rebased
+    // mirror must follow, or it would wait forever for seqs that never come.
+    this.base = 0;
+    const snapshot = [...this.clearListeners];
+    for (const fn of snapshot) {
+      try {
+        fn();
+      } catch {
+        // A clear listener must not block the wipe.
+      }
+    }
+  }
+
+  /**
+   * Subscribe to {@link clear}. Fires synchronously after the events array
+   * empties, so a listener reading the log observes the post-wipe state.
+   * Returns the unsubscribe callback.
+   */
+  onClear(fn: () => void): () => void {
+    this.clearListeners.add(fn);
+    return () => this.clearListeners.delete(fn);
+  }
+
+  asReader(): EventLogReader {
+    return this;
+  }
+}

package/src/index.ts

@@ -0,0 +1,102 @@
+export { Session, type SessionOptions } from './session.js';
+export { runTurn, collectTurn, type RunTurnOptions } from './run-turn.js';
+export {
+  setupAgent,
+  type Agent,
+  type SetupAgentOptions,
+  type AgentPreset,
+} from './setup-agent.js';
+// Re-export the @moxxy/sdk types that appear in the setupAgent / Agent surface,
+// so the programmatic API is fully typed from a single `@moxxy/core` import.
+export type { MoxxyEvent, Plugin, ToolDef, PermissionResolver } from '@moxxy/sdk';
+export { createSubagentSpawner, clearRetainedChildren, type SubagentRuntime } from './subagents.js';
+export {
+  loadPreferences,
+  savePreferences,
+  preferencesPath,
+  type MoxxyPreferences,
+} from './preferences.js';
+export {
+  loadUsageStats,
+  mergeUsageStats,
+  clearUsageStats,
+  usageStatsPath,
+  type UsageStatsFile,
+  type StoredModelUsage,
+} from './usage-stats.js';
+export { SkillRegistryImpl } from './registries/skills.js';
+export {
+  parseSkillFile,
+  parseFrontmatter,
+  discoverSkills,
+  defaultUserSkillsDir,
+  defaultProjectSkillsDir,
+  synthesizeSkill,
+  buildSynthesizeSkillPlugin,
+  type SkillLoadOptions,
+  type DiscoveredSkill,
+  type SynthesizeOptions,
+  type SynthesizedSkill,
+} from './skills/index.js';
+export { EventLog, type EventListener } from './events/log.js';
+// newEventId + materializeEvent are module-private helpers used only by
+// EventLog.append; not re-exported.
+export { newTurnId, newSessionId } from './events/factory.js';
+export { ToolRegistryImpl, type ToolRegistry } from './registries/tools.js';
+export { ProviderRegistry } from './registries/providers.js';
+export { ModeRegistry } from './registries/modes.js';
+export { CompactorRegistry } from './registries/compactors.js';
+export { CacheStrategyRegistry } from './registries/cache-strategies.js';
+export { ViewRendererRegistry } from './registries/view-renderers.js';
+export { defaultViewRenderer } from './view/default-renderer.js';
+export { parseView, validateDoc, countNodes } from './view/parse.js';
+export { TunnelProviderRegistry } from './registries/tunnel-providers.js';
+export { localhostTunnel } from './tunnel/localhost.js';
+export { ChannelRegistryImpl } from './registries/channels.js';
+export { AgentRegistry } from './registries/agents.js';
+export { CommandRegistry } from './registries/commands.js';
+export { TranscriberRegistry } from './registries/transcribers.js';
+export { SynthesizerRegistry } from './registries/synthesizers.js';
+export { EmbedderRegistry } from './registries/embedders.js';
+export { IsolatorRegistry as ContributedIsolatorRegistry } from './registries/isolators.js';
+export { RequirementRegistry, type RequirementRegistryOptions } from './requirements.js';
+export {
+  SessionPersistence,
+  defaultSessionsDir,
+  readIndex as readSessionIndex,
+  restoreEvents as restoreSessionEvents,
+  deleteSession,
+  type SessionMeta,
+  type SessionPersistenceOpts,
+} from './sessions/persistence.js';
+export {
+  PluginHost,
+  PluginRequirementError,
+  type PluginLoader,
+  type PluginSkipReason,
+  type PluginSkipRecord,
+  type PluginSkipSource,
+  type RegisterStaticOptions,
+} from './plugins/host.js';
+export { HookDispatcherImpl } from './plugins/lifecycle.js';
+export { discoverPlugins } from './plugins/discovery.js';
+export { toposortPluginManifests, PluginCycleError } from './plugins/toposort.js';
+export { readPackageMoxxyRequirements } from './plugins/package-requirements.js';
+export { createPluginLoader, type JitiLoaderOptions } from './plugins/loader.js';
+export {
+  PermissionEngine,
+  permissionPolicySchema,
+  type PermissionPolicy,
+  type PolicyRule,
+} from './permissions/engine.js';
+export {
+  autoAllowResolver,
+  denyByDefaultResolver,
+  createCallbackResolver,
+  createDeferredPermissionResolver,
+  type DeferredPermissionResolver,
+  type DeferredPermissionResolverOptions,
+  type PermissionPromptHandler,
+  createAllowListResolver,
+} from './permissions/resolvers.js';
+export { createLogger, silentLogger, type Logger, type LogLevel } from './logger.js';

package/src/logger.ts

@@ -0,0 +1,46 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface Logger {
+  debug(msg: string, meta?: Record<string, unknown>): void;
+  info(msg: string, meta?: Record<string, unknown>): void;
+  warn(msg: string, meta?: Record<string, unknown>): void;
+  error(msg: string, meta?: Record<string, unknown>): void;
+  child(bindings: Record<string, unknown>): Logger;
+}
+
+const levelRank: Record<LogLevel, number> = { debug: 10, info: 20, warn: 30, error: 40 };
+
+export interface LoggerOptions {
+  minLevel?: LogLevel;
+  sink?: (line: string) => void;
+  bindings?: Record<string, unknown>;
+}
+
+export function createLogger(opts: LoggerOptions = {}): Logger {
+  const minLevel = opts.minLevel ?? 'info';
+  const sink = opts.sink ?? ((line) => process.stderr.write(line + '\n'));
+  const bindings = opts.bindings ?? {};
+
+  const emit = (level: LogLevel, msg: string, meta?: Record<string, unknown>): void => {
+    if (levelRank[level] < levelRank[minLevel]) return;
+    const payload = { ts: new Date().toISOString(), level, msg, ...bindings, ...(meta ?? {}) };
+    sink(JSON.stringify(payload));
+  };
+
+  return {
+    debug: (msg, meta) => emit('debug', msg, meta),
+    info: (msg, meta) => emit('info', msg, meta),
+    warn: (msg, meta) => emit('warn', msg, meta),
+    error: (msg, meta) => emit('error', msg, meta),
+    child: (extra) =>
+      createLogger({ minLevel, sink, bindings: { ...bindings, ...extra } }),
+  };
+}
+
+export const silentLogger: Logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  child: () => silentLogger,
+};

package/src/permissions/engine.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { asToolCallId } from '@moxxy/sdk';
+import { PermissionEngine } from './engine.js';
+
+const call = (name: string, input: unknown = {}) => ({
+  callId: asToolCallId('c'),
+  name,
+  input,
+});
+
+describe('PermissionEngine', () => {
+  it('returns null when no rules match', () => {
+    const e = new PermissionEngine();
+    expect(e.check(call('Read'))).toBeNull();
+  });
+
+  it('matches exact allow rule', () => {
+    const e = new PermissionEngine({
+      allow: [{ name: 'Read' }],
+      deny: [],
+    });
+    expect(e.check(call('Read'))?.mode).toBe('allow');
+  });
+
+  it('deny takes priority over allow', () => {
+    const e = new PermissionEngine({
+      allow: [{ name: '*' }],
+      deny: [{ name: 'Bash' }],
+    });
+    expect(e.check(call('Bash'))?.mode).toBe('deny');
+    expect(e.check(call('Read'))?.mode).toBe('allow');
+  });
+
+  it('supports glob in name pattern', () => {
+    const e = new PermissionEngine({
+      allow: [{ name: 'mcp-*' }],
+      deny: [],
+    });
+    expect(e.check(call('mcp-filesystem-read'))?.mode).toBe('allow');
+    expect(e.check(call('Read'))).toBeNull();
+  });
+
+  it('respects inputMatches via regex', () => {
+    const e = new PermissionEngine({
+      allow: [{ name: 'Bash', inputMatches: { cmd: '^ls' } }],
+      deny: [],
+    });
+    expect(e.check(call('Bash', { cmd: 'ls -la' }))?.mode).toBe('allow');
+    expect(e.check(call('Bash', { cmd: 'rm -rf /' }))).toBeNull();
+  });
+
+  it('inputMatches is an unanchored substring match by design (u40-2)', () => {
+    // Documented, stable contract: `inputMatches` values are UNANCHORED regexes
+    // (re.test → substring match). An author who needs a full match anchors
+    // their own pattern. We pin both halves of that contract so it can never be
+    // silently changed (anchoring it would break existing permission files).
+    const substring = new PermissionEngine({
+      allow: [{ name: 'Read', inputMatches: { path: 'config' } }],
+      deny: [],
+    });
+    // Substring pattern matches anywhere in the candidate — by design.
+    expect(substring.check(call('Read', { path: '/etc/config' }))?.mode).toBe('allow');
+    expect(substring.check(call('Read', { path: '/etc/config-evil' }))?.mode).toBe('allow');
+    expect(substring.check(call('Read', { path: '~/.ssh/config-backup' }))?.mode).toBe('allow');
+    // A path that does not contain the pattern at all is not matched.
+    expect(substring.check(call('Read', { path: '/etc/passwd' }))).toBeNull();
+
+    // An author who wants a full match supplies their own ^…$ anchors.
+    const anchored = new PermissionEngine({
+      allow: [{ name: 'Read', inputMatches: { path: '^/etc/config$' } }],
+      deny: [],
+    });
+    expect(anchored.check(call('Read', { path: '/etc/config' }))?.mode).toBe('allow');
+    expect(anchored.check(call('Read', { path: '/etc/config-evil' }))).toBeNull();
+  });
+
+  it('deny rule with an invalid-regex inputMatches still denies (fails closed)', () => {
+    // Unbalanced bracket = uncompilable regex. The user clearly intended to
+    // block `rm -rf`; the old fallback (literal !== equality) silently turned
+    // this into a no-op deny, letting the dangerous command through.
+    const e = new PermissionEngine({
+      allow: [],
+      deny: [{ name: 'Bash', inputMatches: { cmd: 'rm -rf [' } }],
+    });
+    // A call whose input contains that substring (and any other call to the
+    // named tool) must still be denied — never silently allowed.
+    expect(e.check(call('Bash', { cmd: 'rm -rf /' }))?.mode).toBe('deny');
+    expect(e.check(call('Bash', { cmd: 'echo rm -rf [' }))?.mode).toBe('deny');
+    // A call to a different tool is unaffected by the bad rule.
+    expect(e.check(call('Read', { cmd: 'whatever' }))).toBeNull();
+  });
+
+  it('allow rule with an invalid-regex inputMatches does NOT over-grant', () => {
+    const e = new PermissionEngine({
+      allow: [{ name: 'Bash', inputMatches: { cmd: 'ls [' } }],
+      deny: [],
+    });
+    // The bad pattern can never compile, so the allow rule must not grant —
+    // not even for a call whose input literally contains the broken text.
+    expect(e.check(call('Bash', { cmd: 'ls -la' }))).toBeNull();
+    expect(e.check(call('Bash', { cmd: 'ls [' }))).toBeNull();
+  });
+
+  it('inputMatches against a structured (object/array) field matches its JSON form', () => {
+    // u40-4: a structured tool-input field used to coerce to '[object Object]',
+    // so an inputMatches regex could never match it. It is now JSON-serialized.
+    const e = new PermissionEngine({
+      allow: [],
+      deny: [{ name: 'shell', inputMatches: { argv: '"--force"' } }],
+    });
+    // The deny rule matches the serialized array element.
+    expect(e.check(call('shell', { argv: ['rm', '--force'] }))?.mode).toBe('deny');
+    // …and does not match an argv without it.
+    expect(e.check(call('shell', { argv: ['ls', '-la'] }))).toBeNull();
+  });
+
+  it('valid-regex deny rule still behaves exactly as before', () => {
+    const e = new PermissionEngine({
+      allow: [],
+      deny: [{ name: 'Bash', inputMatches: { cmd: '^rm ' } }],
+    });
+    expect(e.check(call('Bash', { cmd: 'rm -rf /' }))?.mode).toBe('deny');
+    expect(e.check(call('Bash', { cmd: 'ls -la' }))).toBeNull();
+  });
+
+  it('valid-regex allow rule still behaves exactly as before', () => {
+    const e = new PermissionEngine({
+      allow: [{ name: 'Bash', inputMatches: { cmd: '^ls' } }],
+      deny: [],
+    });
+    expect(e.check(call('Bash', { cmd: 'ls -la' }))?.mode).toBe('allow');
+    expect(e.check(call('Bash', { cmd: 'rm -rf /' }))).toBeNull();
+  });
+
+  it('loads policy from disk and handles ENOENT', async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-perm-'));
+    const file = path.join(tmp, 'permissions.json');
+    const e1 = await PermissionEngine.load(file);
+    expect(e1.check(call('Read'))).toBeNull();
+
+    await fs.writeFile(file, JSON.stringify({ allow: [{ name: 'Read' }], deny: [] }));
+    const e2 = await PermissionEngine.load(file);
+    expect(e2.check(call('Read'))?.mode).toBe('allow');
+  });
+
+  it('persists addAllow', async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-perm-'));
+    const file = path.join(tmp, 'permissions.json');
+    const e = await PermissionEngine.load(file);
+    await e.addAllow({ name: 'Edit' });
+    const raw = JSON.parse(await fs.readFile(file, 'utf8'));
+    expect(raw.allow[0].name).toBe('Edit');
+  });
+
+  it('persists inputMatches with addAllow (regression for silent drop)', async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-perm-'));
+    const file = path.join(tmp, 'permissions.json');
+    const e = await PermissionEngine.load(file);
+    await e.addAllow({
+      name: 'Bash',
+      inputMatches: { cmd: '^ls' },
+      reason: 'safe listings only',
+    });
+    const raw = JSON.parse(await fs.readFile(file, 'utf8'));
+    expect(raw.allow[0]).toEqual({
+      name: 'Bash',
+      inputMatches: { cmd: '^ls' },
+      reason: 'safe listings only',
+    });
+
+    // Reload and verify it still matches correctly.
+    const e2 = await PermissionEngine.load(file);
+    expect(e2.check(call('Bash', { cmd: 'ls -la' }))?.mode).toBe('allow');
+    expect(e2.check(call('Bash', { cmd: 'rm -rf /' }))).toBeNull();
+  });
+
+  it('writes the policy file atomically (tmp+rename, no .tmp residue)', async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-perm-'));
+    const file = path.join(tmp, 'permissions.json');
+    const e = await PermissionEngine.load(file);
+    await e.addAllow({ name: 'A' });
+    const after = await fs.readdir(tmp);
+    expect(after.filter((f) => f.startsWith('permissions.json.tmp.'))).toEqual([]);
+    expect(after).toContain('permissions.json');
+  });
+
+  it('serializes concurrent mutators so no rule is lost (in-memory + on disk)', async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-perm-'));
+    const file = path.join(tmp, 'permissions.json');
+    try {
+      const e = await PermissionEngine.load(file);
+      // Fire many adds without awaiting between them. Without the per-instance
+      // mutex, overlapping persists rename out of order and the final file
+      // reflects a stale snapshot (rows dropped).
+      await Promise.all(Array.from({ length: 20 }, (_, i) => e.addAllow({ name: `tool-${i}` })));
+      expect(e.policySnapshot.allow).toHaveLength(20);
+      const reloaded = await PermissionEngine.load(file);
+      expect(reloaded.policySnapshot.allow).toHaveLength(20);
+    } finally {
+      await fs.rm(tmp, { recursive: true, force: true });
+    }
+  });
+});