@moxxy/core 0.3.0

package/src/session.ts

@@ -0,0 +1,491 @@
+import type {
+  AppContext,
+  ClientSession,
+  MoxxyEvent,
+  RunTurnOptions,
+  SessionId,
+  SessionInfo,
+} from '@moxxy/sdk';
+import { newSessionId, newTurnId } from './events/factory.js';
+import { runTurn as runTurnImpl } from './run-turn.js';
+import type { SessionRuntime } from './session-runtime.js';
+import { EventLog } from './events/log.js';
+import { HookDispatcherImpl } from './plugins/lifecycle.js';
+import { PluginHost, type PluginLoader } from './plugins/host.js';
+import { ProviderRegistry } from './registries/providers.js';
+import { ModeRegistry } from './registries/modes.js';
+import { CacheStrategyRegistry } from './registries/cache-strategies.js';
+import { ViewRendererRegistry } from './registries/view-renderers.js';
+import { defaultViewRenderer } from './view/default-renderer.js';
+import { TunnelProviderRegistry } from './registries/tunnel-providers.js';
+import { localhostTunnel } from './tunnel/localhost.js';
+import { CompactorRegistry } from './registries/compactors.js';
+import { ChannelRegistryImpl } from './registries/channels.js';
+import { SurfaceRegistryImpl } from './registries/surfaces.js';
+import { SurfaceHostImpl } from './surfaces/host.js';
+import { SkillRegistryImpl } from './registries/skills.js';
+import { ToolRegistryImpl, type ToolRegistry } from './registries/tools.js';
+import { AgentRegistry } from './registries/agents.js';
+import { CommandRegistry } from './registries/commands.js';
+import { TranscriberRegistry } from './registries/transcribers.js';
+import { SynthesizerRegistry } from './registries/synthesizers.js';
+import { EmbedderRegistry } from './registries/embedders.js';
+import { IsolatorRegistry } from './registries/isolators.js';
+import { WorkflowExecutorRegistry } from './registries/workflow-executors.js';
+import { RequirementRegistry } from './requirements.js';
+import { PermissionEngine } from './permissions/engine.js';
+import { autoAllowResolver } from './permissions/resolvers.js';
+import { evaluateToolRule } from '@moxxy/sdk';
+import type {
+  ApprovalResolver,
+  CredentialResolver,
+  ElisionSettings,
+  McpAdminView,
+  ProviderAdminView,
+  WorkflowsView,
+  PluginsAdminView,
+  PendingToolCall,
+  PermissionContext,
+  PermissionDecision,
+  PermissionResolver,
+  PermissionRule,
+} from '@moxxy/sdk';
+import { createLogger, silentLogger, type Logger } from './logger.js';
+import { clearRetainedChildren } from './subagents/registry.js';
+
+export interface SessionOptions {
+  readonly cwd: string;
+  readonly logger?: Logger;
+  readonly sessionId?: SessionId;
+  readonly permissionEngine?: PermissionEngine;
+  readonly permissionResolver?: PermissionResolver;
+  readonly hookTimeoutMs?: number;
+  readonly silent?: boolean;
+  /**
+   * Optional plugin loader. When provided, `session.pluginHost.discoverAndLoad()`
+   * can dynamic-import discovered plugins; without one, only static plugins
+   * registered via `registerStatic()` are wired up.
+   */
+  readonly pluginLoader?: PluginLoader;
+  /**
+   * Extra directories to scan for plugins, on top of the cwd-rooted
+   * `node_modules` walk. The CLI sets this to `~/.moxxy/plugins` (and its
+   * `node_modules` subtree) so runtime-installed / scaffolded plugins are
+   * discoverable. Crucially these are remembered by the host and reused on
+   * `pluginHost.reload()`, so a hot-reload neither drops user plugins nor
+   * fails to pick up freshly written ones.
+   */
+  readonly pluginDiscoveryPaths?: ReadonlyArray<string>;
+  /**
+   * Predicate (by package name) for whether a discovered plugin is disabled.
+   * Forwarded to the PluginHost so `pluginHost.reload()` never resurrects a
+   * plugin the user turned off via config `plugins[name].enabled = false`.
+   * Reads live state, so a runtime enable/disable applies on the next reload.
+   */
+  readonly isPluginDisabled?: (packageName: string) => boolean;
+  /**
+   * Vault-backed secret resolver. When provided, every tool handler gets
+   * `ctx.getSecret(name)` so plugins can read an API key / token at call
+   * time. The plaintext never enters the model's context or `process.env`;
+   * only the handler that asks receives it. The CLI/runner wires this to
+   * the session vault's `get`.
+   */
+  readonly secretResolver?: (name: string) => Promise<string | null>;
+  /**
+   * Pre-seeded event log. Used by `moxxy resume` to restore the
+   * conversation from a persisted JSONL. Subscribers don't re-fire for
+   * seeded events (the constructor pushes them directly), so plugin
+   * hooks won't run for historical entries.
+   */
+  readonly log?: EventLog;
+}
+
+export class Session implements ClientSession, SessionRuntime {
+  readonly id: SessionId;
+  readonly cwd: string;
+  readonly log: EventLog;
+  readonly logger: Logger;
+  readonly tools: ToolRegistry;
+  readonly providers: ProviderRegistry;
+  readonly modes: ModeRegistry;
+  readonly compactors: CompactorRegistry;
+  readonly cacheStrategies: CacheStrategyRegistry;
+  readonly viewRenderers: ViewRendererRegistry;
+  readonly tunnelProviders: TunnelProviderRegistry;
+  readonly channels: ChannelRegistryImpl;
+  /** Registry of surface defs (terminal, browser, …) contributed by plugins. */
+  readonly surfaceRegistry: SurfaceRegistryImpl;
+  /**
+   * Manages the live, open surface instances for this session. The runner
+   * drives it for thin clients; the agent's tools reach the same resources via
+   * plugin module state. See {@link SurfaceHostImpl}.
+   */
+  readonly surfaces: SurfaceHostImpl;
+  readonly skills: SkillRegistryImpl;
+  readonly agents: AgentRegistry;
+  readonly commands: CommandRegistry;
+  readonly transcribers: TranscriberRegistry;
+  readonly synthesizers: SynthesizerRegistry;
+  readonly embedders: EmbedderRegistry;
+  readonly isolators: IsolatorRegistry;
+  readonly workflowExecutors: WorkflowExecutorRegistry;
+  readonly requirements: RequirementRegistry;
+  readonly permissions: PermissionEngine;
+  /** Current PermissionResolver. Update via `setPermissionResolver(r)`. */
+  resolver: PermissionResolver;
+  /**
+   * Optional generic approval resolver. Loop strategies use this to ask
+   * the user a checkpoint question (plan validation, command preview,
+   * diff review, etc.). Null when running headless or before the TUI
+   * registers one — strategies that have no resolver simply skip the
+   * approval step.
+   */
+  approvalResolver: ApprovalResolver | null = null;
+  /**
+   * Elision (context-on-demand) settings, resolved from `config.context.elision`
+   * at setup and updated on config reload. Null → built-in defaults apply
+   * (elision on). Read into each turn's ModeContext.
+   */
+  elisionSettings: ElisionSettings | null = null;
+  /** Lazy tool loading toggle, from `config.context.lazyTools`. Default off. */
+  lazyTools = false;
+  /**
+   * Reasoning/thinking preference, from `config.context.reasoning`. Forwarded
+   * to each turn's ModeContext and on to the provider, which honors it only
+   * when the active model advertises `supportsReasoning`. Undefined → off.
+   */
+  reasoning: { readonly effort?: 'low' | 'medium' | 'high' } | boolean | undefined = undefined;
+  /**
+   * Model id resolved by the most recent `runTurn()` (see SessionRuntime).
+   * Last-writer-wins for concurrent turns; null until the first turn runs.
+   */
+  lastResolvedModel: string | null = null;
+  /**
+   * Live runtime capabilities the host installs on a local Session (see
+   * SessionLike). A RemoteSession leaves them undefined. Declared here — rather
+   * than monkey-patched on via `as unknown as` — so the host and channels get
+   * type-checked access.
+   */
+  readyProviders?: Set<string>;
+  credentialResolver?: CredentialResolver;
+  mcpAdmin?: McpAdminView;
+  providerAdmin?: ProviderAdminView;
+  workflows?: WorkflowsView;
+  pluginsAdmin?: PluginsAdminView;
+  readonly dispatcher: HookDispatcherImpl;
+  readonly pluginHost: PluginHost;
+  private readonly controller = new AbortController();
+
+  constructor(opts: SessionOptions) {
+    this.id = opts.sessionId ?? newSessionId();
+    this.cwd = opts.cwd;
+    this.logger = opts.logger ?? (opts.silent ? silentLogger : createLogger());
+    this.log = opts.log ?? new EventLog();
+    this.tools = new ToolRegistryImpl({
+      logger: this.logger,
+      cwd: this.cwd,
+      ...(opts.secretResolver ? { secretResolver: opts.secretResolver } : {}),
+    });
+    this.providers = new ProviderRegistry();
+    this.modes = new ModeRegistry();
+    this.compactors = new CompactorRegistry();
+    this.cacheStrategies = new CacheStrategyRegistry();
+    this.viewRenderers = new ViewRendererRegistry();
+    // Seed the built-in renderer so `present_view` always has one to parse
+    // with; plugins can register/replace and `setActive` an alternative.
+    this.viewRenderers.register(defaultViewRenderer);
+    this.tunnelProviders = new TunnelProviderRegistry();
+    // Seed the no-op localhost provider so the web surface always resolves a
+    // URL; plugins (cloudflared) register/setActive a real tunnel.
+    this.tunnelProviders.register(localhostTunnel);
+    this.channels = new ChannelRegistryImpl();
+    this.surfaceRegistry = new SurfaceRegistryImpl();
+    this.surfaces = new SurfaceHostImpl(this.surfaceRegistry, { cwd: this.cwd, logger: this.logger }, this.logger);
+    this.skills = new SkillRegistryImpl();
+    this.agents = new AgentRegistry();
+    this.commands = new CommandRegistry();
+    this.transcribers = new TranscriberRegistry();
+    this.synthesizers = new SynthesizerRegistry({
+      ...(opts.secretResolver ? { secretResolver: opts.secretResolver } : {}),
+    });
+    this.embedders = new EmbedderRegistry();
+    this.isolators = new IsolatorRegistry();
+    this.workflowExecutors = new WorkflowExecutorRegistry();
+    this.requirements = new RequirementRegistry({
+      tools: this.tools,
+      providers: this.providers,
+      modes: this.modes,
+      compactors: this.compactors,
+      channels: this.channels,
+      agents: this.agents,
+      commands: this.commands,
+      transcribers: this.transcribers,
+      synthesizers: this.synthesizers,
+    });
+    this.permissions = opts.permissionEngine ?? new PermissionEngine();
+    // Always wrap the user-supplied resolver with the persistent
+    // policy engine, so saved `allow_always` / `deny` rules from
+    // ~/.moxxy/permissions.json short-circuit the resolver's prompt
+    // path. Without this wrap the engine is dead weight — the
+    // permissions JSON updates on every "allow always" click but no
+    // future turn ever consults it.
+    this.resolver = wrapWithPolicy(
+      opts.permissionResolver ?? autoAllowResolver,
+      this.permissions,
+      (name) => this.tools.get(name)?.permission,
+    );
+    this.dispatcher = new HookDispatcherImpl({
+      logger: this.logger,
+      hookTimeoutMs: opts.hookTimeoutMs,
+    });
+    this.pluginHost = new PluginHost({
+      cwd: this.cwd,
+      logger: this.logger,
+      tools: this.tools,
+      providers: this.providers,
+      modes: this.modes,
+      compactors: this.compactors,
+      cacheStrategies: this.cacheStrategies,
+      viewRenderers: this.viewRenderers,
+      tunnelProviders: this.tunnelProviders,
+      channels: this.channels,
+      surfaces: this.surfaceRegistry,
+      agents: this.agents,
+      commands: this.commands,
+      transcribers: this.transcribers,
+      synthesizers: this.synthesizers,
+      embedders: this.embedders,
+      isolators: this.isolators,
+      workflowExecutors: this.workflowExecutors,
+      requirements: this.requirements,
+      dispatcher: this.dispatcher,
+      loader: opts.pluginLoader,
+      ...(opts.pluginDiscoveryPaths ? { userPaths: opts.pluginDiscoveryPaths } : {}),
+      ...(opts.isPluginDisabled ? { isDisabled: opts.isPluginDisabled } : {}),
+    });
+
+    // Fan every appended event out to plugin `onEvent` hooks. Without this
+    // wiring the hook is dead code — declared on the SDK, dispatched by
+    // HookDispatcherImpl, but nothing ever calls dispatchEvent.
+    this.log.subscribe((event) => {
+      // appContext() clones the whole process.env; only pay that per-event cost
+      // when a plugin actually has an onEvent hook to receive it. With none,
+      // dispatchEvent would iterate an empty hook list anyway.
+      if (!this.dispatcher.hasEventHooks()) return;
+      return this.dispatcher.dispatchEvent(event, this.appContext());
+    });
+  }
+
+  get signal(): AbortSignal {
+    return this.controller.signal;
+  }
+
+  abort(reason = 'user-requested abort'): void {
+    this.controller.abort(reason);
+  }
+
+  /**
+   * Swap the active PermissionResolver. Channels call this after they're
+   * constructed so the session uses the channel's interactive resolver
+   * (TUI prompt, Telegram inline keyboard, HTTP allow-list, etc.).
+   * Replaces the previous monkey-patching of the private `resolver` field
+   * from CLI command code.
+   */
+  setPermissionResolver(resolver: PermissionResolver): void {
+    // Re-wrap so policy rules continue to short-circuit prompts when a
+    // channel installs its own resolver mid-session.
+    this.resolver = wrapWithPolicy(
+      resolver,
+      this.permissions,
+      (name) => this.tools.get(name)?.permission,
+    );
+  }
+
+  /** Install/replace the generic approval resolver. Pass null to clear. */
+  setApprovalResolver(resolver: ApprovalResolver | null): void {
+    this.approvalResolver = resolver;
+  }
+
+  /**
+   * `SessionLike.reset` — the authoritative `/new`. Clears the event log;
+   * the log's clear listeners propagate the wipe to whatever observes it
+   * (the persistence sidecar truncates its JSONL so `--resume` sees an
+   * empty session; a wrapping RunnerServer broadcasts a reset so attached
+   * mirrors clear in lockstep). Registries, resolvers, and the active
+   * provider survive — only the conversation context vanishes. Callers
+   * must abort any in-flight turn first (same contract as `log.clear()`).
+   */
+  async reset(): Promise<void> {
+    this.log.clear();
+  }
+
+  /**
+   * Graceful shutdown: fire every plugin's `onShutdown` hook, then abort
+   * the session. Idempotent — safe to call multiple times (subsequent
+   * calls are no-ops once `closed` is set).
+   *
+   * Channels' SIGINT handlers should call this before exiting so plugins
+   * can flush state (memory journal, vault, audit logs, etc.).
+   */
+  async close(reason = 'shutdown'): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    try {
+      // Tear down any open surfaces (PTYs, browser screencasts) before the
+      // plugin shutdown hooks dispose their underlying resources.
+      await this.surfaces.closeAll();
+      await this.dispatcher.dispatchShutdown(this.appContext());
+    } finally {
+      // Drop THIS session's retained child sessions (the workflow `awaitInput`
+      // flow keeps them in a process-local registry until a
+      // `continue()`/`release()`). A paused run that never resumes would
+      // otherwise pin them for the whole process lifetime — release them on
+      // shutdown so they don't leak. Scoped to this session's id so closing one
+      // session never wipes another live session's paused children.
+      clearRetainedChildren(this.id);
+      this.abort(reason);
+    }
+  }
+
+  private closed = false;
+
+  appContext(): AppContext {
+    return {
+      sessionId: this.id,
+      cwd: this.cwd,
+      log: this.log.asReader(),
+      env: { ...process.env },
+    };
+  }
+
+  startTurn(): { turnId: ReturnType<typeof newTurnId> } {
+    return { turnId: newTurnId() };
+  }
+
+  subscribe(fn: (e: MoxxyEvent) => void | Promise<void>): () => void {
+    return this.log.subscribe(fn);
+  }
+
+  /**
+   * Drive one turn against this session. Method form of the `runTurn` free
+   * function so a local `Session` satisfies `SessionLike` (the channel-facing
+   * contract a `RemoteSession` proxy also implements).
+   */
+  runTurn(prompt: string, opts: RunTurnOptions = {}): AsyncIterable<MoxxyEvent> {
+    return runTurnImpl(this, prompt, opts);
+  }
+
+  /**
+   * Wire-friendly snapshot of the registries for channels to render. Mirrors
+   * what a `RemoteSession` fetches from the runner over RPC - keep the two in
+   * sync.
+   */
+  getInfo(): SessionInfo {
+    let activeMode: string | null = null;
+    let activeModeBadge: SessionInfo['activeModeBadge'] = null;
+    try {
+      const mode = this.modes.getActive();
+      activeMode = mode.name;
+      // Surface the active mode's presentation hint so channels can render a
+      // persistent badge (e.g. goal mode) without hard-coding mode names.
+      activeModeBadge = mode.badge ? { label: mode.badge.label, ...(mode.badge.tone ? { tone: mode.badge.tone } : {}) } : null;
+    } catch {
+      // No mode active yet (registry empty pre-boot) - report null.
+    }
+    const active = this.providers.getActiveName();
+    const ready = this.readyProviders;
+    return {
+      sessionId: this.id,
+      cwd: this.cwd,
+      activeProvider: active,
+      providers: this.providers.list().map((p) => ({
+        name: p.name,
+        models: p.models,
+        authKind: p.auth?.kind === 'oauth' ? 'oauth' : 'api-key',
+        // Built-in providers ship hard-coded model lists, so live
+        // discovery on /v1/models isn't required from the host. Admin-
+        // registered providers (kind: 'apiKey' without a builtin def)
+        // are the ones the desktop's "Fetch live" affordance targets;
+        // they advertise this via the provider-admin factory by
+        // setting `supportsLiveModelDiscovery: true` on their def.
+        supportsLiveModelDiscovery:
+          (p as { supportsLiveModelDiscovery?: boolean }).supportsLiveModelDiscovery === true,
+        enabled: this.providers.isEnabled(p.name),
+      })),
+      activeMode,
+      activeModeBadge,
+      modes: this.modes.list().map((m) => m.name),
+      tools: this.tools.list().map((t) => ({
+        name: t.name,
+        description: t.description,
+        ...(t.compact ? { compact: t.compact } : {}),
+      })),
+      skills: this.skills.list().map((s) => ({ id: s.id, name: s.frontmatter.name })),
+      commands: this.commands.list().map((c) => ({
+        name: c.name,
+        description: c.description,
+        ...(c.aliases ? { aliases: c.aliases } : {}),
+        ...(c.channels ? { channels: c.channels } : {}),
+        ...(c.pendingNotice ? { pendingNotice: c.pendingNotice } : {}),
+      })),
+      readyProviders: ready ? [...ready] : active ? [active] : [],
+      // hasTranscriber reports whether any backend is *registered*,
+      // not whether one is active. The active selection is per-flow
+      // (the TUI activates Codex on its first voice toggle; the
+      // desktop relies on handleTranscribe's candidate fallback).
+      // For UI affordance gating (showing / hiding a mic button),
+      // any registered transcriber means "voice is wired."
+      hasTranscriber: this.transcribers.list().length > 0,
+      activeTranscriber: this.transcribers.getActiveName(),
+      hasSynthesizer: this.synthesizers.list().length > 0,
+      activeSynthesizer: this.synthesizers.getActiveName(),
+    };
+  }
+}
+
+/**
+ * Wrap a `PermissionResolver` so the persistent `PermissionEngine` runs
+ * first. If the engine has a matching allow/deny rule from
+ * `~/.moxxy/permissions.json`, that decision short-circuits the
+ * resolver's prompt path. Otherwise the resolver runs as usual.
+ *
+ * The wrapper is a Proxy that intercepts only `check` (and provides the
+ * prompt-free `policyCheck` probe); every other property (e.g. `abortAll`
+ * and any channel-specific helpers) passes straight through to the
+ * underlying resolver, so callers reach those methods exactly as before.
+ */
+function wrapWithPolicy(
+  inner: PermissionResolver,
+  engine: PermissionEngine,
+  getToolRule: (name: string) => PermissionRule | undefined,
+): PermissionResolver {
+  // The policy-only decision: user policy (permissions.json) wins, then the
+  // tool's own declared rule (so a tool marked `allow` is never blocked in
+  // headless runs). Returns null when neither decides — `check` then falls
+  // through to the channel resolver's prompt / deny-by-default path, while
+  // `policyCheck` callers (auto-approving modes) supply their own fallback
+  // so no prompt can ever fire.
+  const policyDecision = (call: PendingToolCall): PermissionDecision | null => {
+    const policy = engine.check(call);
+    if (policy) return policy;
+    return evaluateToolRule(getToolRule(call.name), call);
+  };
+  // Use a Proxy so any extra methods on the underlying resolver
+  // (`abortAll`, channel-specific helpers) remain accessible — only
+  // `check`/`policyCheck` are intercepted.
+  return new Proxy(inner, {
+    get(target, prop, receiver) {
+      if (prop === 'check') {
+        return async (call: PendingToolCall, ctx: PermissionContext) => {
+          const decided = policyDecision(call);
+          if (decided) return decided;
+          return target.check(call, ctx);
+        };
+      }
+      if (prop === 'policyCheck') {
+        return async (call: PendingToolCall) => policyDecision(call);
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+  });
+}

package/src/sessions/persistence.flush.test.ts

@@ -0,0 +1,100 @@
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { EventLog } from '../events/log.js';
+import { SessionPersistence, type SessionMeta } from './persistence.js';
+
+const tempDirs: string[] = [];
+
+async function makeTempDir(): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'moxxy-flush-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+});
+
+async function readMeta(dir: string, id: string): Promise<SessionMeta> {
+  const raw = await fs.readFile(path.join(dir, `${id}.meta.json`), 'utf8');
+  return JSON.parse(raw) as SessionMeta;
+}
+
+describe('SessionPersistence final-write on detach (async-error-3)', () => {
+  it('flush() persists the latest meta immediately, bypassing the 250ms debounce', async () => {
+    const dir = await makeTempDir();
+    const id = '01FLUSHBYPASS0000000000000';
+    const log = new EventLog();
+    const persistence = new SessionPersistence({ sessionId: id as never, cwd: '/tmp/p', dir });
+    const detach = persistence.attach(log);
+
+    // An append schedules a debounced index write but does NOT flush it.
+    await log.append({
+      type: 'user_prompt',
+      sessionId: id as never,
+      turnId: 't1' as never,
+      source: 'user',
+      text: 'hello',
+    });
+
+    // flush() forces the pending write through now. If it waited on the
+    // debounce this would still read the pre-append (eventCount 0) sidecar.
+    await persistence.flush();
+    const after = await readMeta(dir, id);
+    expect(after.eventCount).toBe(1);
+    expect(after.firstPrompt).toBe('hello');
+
+    detach();
+  });
+
+  it('detach writes the final index row without waiting for the debounce window', async () => {
+    const dir = await makeTempDir();
+    const id = '01DETACHFINAL00000000000000';
+    const log = new EventLog();
+    const persistence = new SessionPersistence({ sessionId: id as never, cwd: '/tmp/p', dir });
+    const detach = persistence.attach(log);
+
+    await log.append({
+      type: 'user_prompt',
+      sessionId: id as never,
+      turnId: 't1' as never,
+      source: 'user',
+      text: 'last activity',
+    });
+
+    // Flush the append's debounced write, then capture the timestamp.
+    await persistence.flush();
+    const beforeDetach = await readMeta(dir, id);
+
+    // Detach must fire its own final (close-time) write synchronously, not on a
+    // 250ms timer an immediate exit would drop. We poll only a microtask-scale
+    // window — far shorter than the debounce — to prove it doesn't wait on it.
+    detach();
+    await waitForCondition(async () => {
+      const meta = await readMeta(dir, id);
+      return meta.lastActivity >= beforeDetach.lastActivity && meta.eventCount === 1;
+    }, 100);
+
+    const finalMeta = await readMeta(dir, id);
+    expect(finalMeta.eventCount).toBe(1);
+    expect(finalMeta.id).toBe(id);
+  });
+});
+
+async function waitForCondition(
+  predicate: () => Promise<boolean>,
+  timeoutMs: number,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    try {
+      if (await predicate()) return;
+    } catch {
+      // sidecar may not exist yet — keep polling
+    }
+    if (Date.now() > deadline) throw new Error('Timed out waiting for condition');
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+}

package/src/sessions/persistence.ready.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Regression for u45-2: `writeIndex()` used to re-run ensureDir + ensureLogFile
+ * (an `fs.open(logPath,'a')` + close) on EVERY 250ms debounced index flush. The
+ * one-time setup is now memoized, so `fs.open` fires once (at attach), never
+ * again from the index-write path.
+ */
+
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { EventLog } from '../events/log.js';
+import { SessionPersistence, restoreEvents } from './persistence.js';
+
+const tempDirs: string[] = [];
+
+async function makeTempDir(): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'moxxy-ready-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await Promise.all(tempDirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+});
+
+describe('SessionPersistence one-time setup (no per-flush open/close)', () => {
+  it('opens the log file at most once across attach + many flushes', async () => {
+    const dir = await makeTempDir();
+    const id = '01READYONCE00000000000000A';
+    const log = new EventLog();
+    const persistence = new SessionPersistence({ sessionId: id as never, cwd: '/tmp/p', dir });
+
+    const openSpy = vi.spyOn(fs, 'open');
+    const detach = persistence.attach(log);
+
+    // Drive several index flushes (each bypasses the debounce).
+    for (let i = 0; i < 5; i += 1) {
+      await log.append({
+        type: 'user_prompt',
+        sessionId: id as never,
+        turnId: `t${i}` as never,
+        source: 'user',
+        text: `msg ${i}`,
+      });
+      await persistence.flush();
+    }
+    detach();
+    await persistence.flush();
+
+    // Exactly one open (the initial ensureLogFile) — not one per flush.
+    expect(openSpy).toHaveBeenCalledTimes(1);
+
+    // Sidecar still written correctly.
+    const raw = await fs.readFile(path.join(dir, `${id}.meta.json`), 'utf8');
+    const meta = JSON.parse(raw) as { eventCount: number; firstPrompt: string | null };
+    expect(meta.eventCount).toBe(5);
+    expect(meta.firstPrompt).toBe('msg 0');
+  });
+
+  it('first append into a not-yet-created nested dir does not race ensureDir (u45-1)', async () => {
+    // The first event arrives synchronously after attach, before the detached
+    // ensureReady() resolves, into a sessions dir that does not exist yet.
+    // appendFile(flag 'a') creates the file but NOT its parent dir, so without
+    // serializing the append behind ensureReady() this ENOENT'd, latched the
+    // "persistence degraded" warning, and lost the event.
+    const base = await makeTempDir();
+    const dir = path.join(base, 'deeply', 'nested', 'sessions'); // does not exist
+    const id = '01READYRACE00000000000000B';
+    const log = new EventLog();
+    const persistence = new SessionPersistence({ sessionId: id as never, cwd: '/tmp/p', dir });
+
+    persistence.attach(log);
+    // Append in the SAME tick as attach — before ensureReady() can resolve.
+    await log.append({
+      type: 'user_prompt',
+      sessionId: id as never,
+      turnId: 't0' as never,
+      source: 'user',
+      text: 'first ever event',
+    });
+    await persistence.flush();
+
+    // Never went degraded, and the first event survived.
+    expect(persistence.degraded).toBe(false);
+    const restored = await restoreEvents(id, dir);
+    expect(restored).toHaveLength(1);
+    expect(restored[0]!.type).toBe('user_prompt');
+  });
+});