@moxxy/core 0.5.0 → 0.5.2

package/src/registries/modes.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { defineMode } from '@moxxy/sdk';
 import { ModeRegistry } from './modes.js';
 
@@ -63,4 +63,24 @@ describe('ModeRegistry legacy-name migration', () => {
     reg.replace(mode('goal')); // not the active mode
     expect(fired).toBe(0);
   });
+
+  it('isolates a throwing change listener so register/setActive never aborts', () => {
+    const reg = new ModeRegistry();
+    const after = vi.fn();
+    reg.onActiveChange(() => {
+      throw new Error('observer down (e.g. dead socket on InfoChanged)');
+    });
+    reg.onActiveChange(after);
+    // A throwing observer must NOT abort the remaining listeners nor unwind into
+    // the registration that triggered the notification.
+    expect(() => reg.register(mode('default'))).not.toThrow();
+    expect(after).toHaveBeenCalledTimes(1);
+    expect(reg.getActive().name).toBe('default');
+
+    // Same isolation on an explicit setActive (mode switch).
+    reg.register(mode('goal'));
+    after.mockClear();
+    expect(() => reg.setActive('goal')).not.toThrow();
+    expect(after).toHaveBeenCalledTimes(1);
+  });
 });

package/src/registries/modes.ts

@@ -37,7 +37,7 @@ export class ModeRegistry {
       // active behaviour changed under them, or remote clients keep driving the
       // stale def. `activate()` would early-return on the name match, so notify
       // directly.
-      for (const fn of this.changeListeners) fn();
+      this.notifyChange();
     }
   }
 
@@ -75,6 +75,19 @@ export class ModeRegistry {
   private activate(mode: ModeDef): void {
     if (this.active === mode.name) return;
     this.active = mode.name;
-    for (const fn of this.changeListeners) fn();
+    this.notifyChange();
+  }
+
+  /** Fan out to change listeners, isolating each fault so a single throwing
+   *  observer (e.g. the runner's InfoChanged broadcast hitting a dead socket)
+   *  can't abort the rest or unwind into register()/replace()/setActive(). */
+  private notifyChange(): void {
+    for (const fn of this.changeListeners) {
+      try {
+        fn();
+      } catch {
+        // Swallow: an observer fault must not break mode activation.
+      }
+    }
   }
 }

package/src/registries/providers.ts

@@ -69,6 +69,14 @@ export class ProviderRegistry {
     return !this.disabled.has(name);
   }
 
+  /**
+   * Activate a provider, building its client on first activation. NOTE: once an
+   * instance is cached, a later `setActive(name, newConfig)` REUSES the cached
+   * instance and DROPS `newConfig` — re-config requires `replace()` first
+   * (which clears the cache), the flow the sole production caller follows.
+   * Reconfiguring by rebuilding here is intentionally avoided so callers don't
+   * silently lose instance identity / in-flight state on a redundant activate.
+   */
   setActive(name: string, config?: Record<string, unknown>): LLMProvider {
     const def = this.defs.get(name);
     if (!def) throw new Error(`Provider not registered: ${name}`);

package/src/registries/semantics.test.ts

@@ -1,5 +1,6 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import type { CompactorDef, ModeDef, ProviderDef } from '@moxxy/sdk';
+import { silentLogger } from '../logger.js';
 import { ProviderRegistry } from './providers.js';
 import { ModeRegistry } from './modes.js';
 import { CompactorRegistry } from './compactors.js';
@@ -114,4 +115,35 @@ describe('Registry consistency (PR3-1)', () => {
     expect(r.byName('bar')?.body).toBe('two');
     expect(r.list()).toHaveLength(1);
   });
+
+  it('SkillRegistryImpl: warns (not silent) when two distinct skills share a frontmatter name', () => {
+    const warn = vi.fn();
+    const r = new SkillRegistryImpl({ logger: { ...silentLogger, warn } });
+    const a = {
+      id: 'project/a' as never,
+      path: '/a.md',
+      scope: 'project' as const,
+      frontmatter: { name: 'dupe', description: 'd' },
+      body: 'a',
+    };
+    const b = { ...a, id: 'project/b' as never, path: '/b.md', body: 'b' };
+    r.register(a);
+    r.register(b); // same frontmatter.name, different id → must warn
+    expect(warn).toHaveBeenCalledTimes(1);
+    // Last-wins by name is preserved, but no longer silent.
+    expect(r.byName('dupe')?.id).toBe('project/b');
+    // Both are still reachable by id.
+    expect(r.list()).toHaveLength(2);
+  });
+
+  it('SkillRegistryImpl: replaceAll warns on a frontmatter-name collision within the batch', () => {
+    const warn = vi.fn();
+    const r = new SkillRegistryImpl({ logger: { ...silentLogger, warn } });
+    r.replaceAll([
+      { id: 'p/a' as never, path: '/a.md', scope: 'project' as const, frontmatter: { name: 'n', description: 'd' }, body: 'a' },
+      { id: 'p/b' as never, path: '/b.md', scope: 'project' as const, frontmatter: { name: 'n', description: 'd' }, body: 'b' },
+    ]);
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(r.byName('n')?.id).toBe('p/b');
+  });
 });

package/src/registries/skills.ts

@@ -1,8 +1,28 @@
 import type { Skill, SkillRegistry } from '@moxxy/sdk';
+import type { Logger } from '../logger.js';
 
 export class SkillRegistryImpl implements SkillRegistry {
   private readonly byId = new Map<string, Skill>();
   private readonly byNameIdx = new Map<string, Skill>();
+  private readonly logger?: Logger;
+
+  constructor(opts: { logger?: Logger } = {}) {
+    this.logger = opts.logger;
+  }
+
+  /** Warn (don't silently last-wins) when two distinct skills fight over one
+   *  frontmatter.name — otherwise byName() is non-deterministic by load order
+   *  and the first skill becomes unreachable by name. */
+  private warnNameCollision(name: string, incomingId: string): void {
+    const existing = this.byNameIdx.get(name);
+    if (existing && existing.id !== incomingId) {
+      this.logger?.warn('SkillRegistry: two skills share a frontmatter name; last one wins by name', {
+        name,
+        existingId: existing.id,
+        incomingId,
+      });
+    }
+  }
 
   list(): ReadonlyArray<Skill> {
     return [...this.byId.values()];
@@ -34,6 +54,7 @@ export class SkillRegistryImpl implements SkillRegistry {
     if (this.byId.has(skill.id)) {
       throw new Error(`Skill already registered: ${skill.id}`);
     }
+    this.warnNameCollision(skill.frontmatter.name, skill.id);
     this.byId.set(skill.id, skill);
     this.byNameIdx.set(skill.frontmatter.name, skill);
   }
@@ -74,6 +95,13 @@ export class SkillRegistryImpl implements SkillRegistry {
     const nextByName = new Map<string, Skill>();
     for (const s of skills) {
       nextById.set(s.id, s);
+      const priorForName = nextByName.get(s.frontmatter.name);
+      if (priorForName && priorForName.id !== s.id) {
+        this.logger?.warn(
+          'SkillRegistry: two skills share a frontmatter name; last one wins by name',
+          { name: s.frontmatter.name, existingId: priorForName.id, incomingId: s.id },
+        );
+      }
       nextByName.set(s.frontmatter.name, s);
     }
     // Synchronous swap: callers between these lines still see the OLD

package/src/registries/transcribers.test.ts

@@ -67,4 +67,17 @@ describe('TranscriberRegistry', () => {
       expect(r.text).toBe('new');
     });
   });
+
+  it('replacing the ACTIVE def eagerly rebuilds so getActive() never strands (non-buildOnRead)', async () => {
+    const reg = new TranscriberRegistry();
+    reg.register(fake('whisper', 'old'));
+    reg.setActive('whisper');
+    // A hot-reloaded plugin re-registers via replace() WITHOUT calling setActive
+    // again. For a non-buildOnRead registry, getActive() reads the cached
+    // instance directly; dropping it must not leave getActive() throwing.
+    reg.replace(fake('whisper', 'new'));
+    const active = reg.getActive(); // must NOT throw "has no instance"
+    const out = await active.transcribe(new Uint8Array());
+    expect(out.text).toBe('new'); // and it's the NEW def, not the stale one
+  });
 });

package/src/requirements.test.ts

@@ -87,6 +87,41 @@ describe('RequirementRegistry', () => {
     expect(check.issues[0]).toMatchObject({ code: 'not_ready' });
   });
 
+  it('does not report version_mismatch for a non-plugin kind carrying a version', () => {
+    // `version` is only resolvable for the plugin kind. A version on any other
+    // kind used to compare against an always-undefined target.version and emit a
+    // permanent spurious version_mismatch ("(unknown)") even though the target
+    // was present and active.
+    const { requirements, providers } = makeRequirements();
+    providers.register(
+      defineProvider({
+        name: 'openai-codex',
+        models: [],
+        createClient: () => ({ name: 'openai-codex', models: [], stream: async function* () {}, countTokens: async () => 0 }),
+      }),
+    );
+    providers.setActive('openai-codex');
+
+    const check = requirements.check([
+      { kind: 'provider', name: 'openai-codex', state: 'active', version: '1.0.0' },
+    ]);
+
+    expect(check.ready).toBe(true);
+    expect(check.issues).toEqual([]);
+  });
+
+  it('still honors a version mismatch for the plugin kind', () => {
+    const { requirements } = makeRequirements();
+    requirements.registerPlugin('@moxxy/plugin-example', '2.0.0');
+
+    const check = requirements.check([
+      { kind: 'plugin', name: '@moxxy/plugin-example', version: '1.0.0' },
+    ]);
+
+    expect(check.ready).toBe(false);
+    expect(check.issues[0]).toMatchObject({ code: 'version_mismatch' });
+  });
+
   it('isReady checks a single named target without composing per-def requirements', () => {
     const { requirements, transcribers } = makeRequirements();
     transcribers.register(

package/src/requirements.ts

@@ -141,7 +141,13 @@ export class RequirementRegistry {
       return issue(requirement, 'missing', `Required ${label(requirement.kind)} is not registered: ${requirement.name}`);
     }
 
-    if (requirement.version && target.version !== requirement.version) {
+    // `version` is only resolvable for the `plugin` kind (the sole kind whose
+    // `targetInfo` populates a version — see {@link targetInfo}). The SDK type
+    // permits `version` on every kind, so without this gate a `version` on any
+    // non-plugin kind would compare against an always-undefined `target.version`
+    // and report a permanent, spurious `version_mismatch` (target shown as
+    // `(unknown)`) even though the target is present and active.
+    if (requirement.kind === 'plugin' && requirement.version && target.version !== requirement.version) {
       return issue(
         requirement,
         'version_mismatch',

package/src/run-turn.test.ts

@@ -176,3 +176,222 @@ describe('runTurn threads real cwd/env into onToolCall hooks', () => {
     expect(captured.envFoo).toBe(process.env.PATH);
   });
 });
+
+describe('runTurn worst-case hardening', () => {
+  it('aborting iteration early aborts the strategy promptly (no full background run)', async () => {
+    let observedAbort = false;
+    // A mode that loops indefinitely until its signal aborts. If the consumer's
+    // early `break` did NOT abort the turn, this would run forever and the
+    // generator's `finally` would hang awaiting it.
+    const foreverMode = defineMode({
+      name: 'forever',
+      run: async function* (ctx: ModeContext): AsyncIterable<MoxxyEvent> {
+        for (let i = 0; ; i++) {
+          if (ctx.signal.aborted) {
+            observedAbort = true;
+            return;
+          }
+          await ctx.emit({
+            type: 'assistant_message',
+            sessionId: ctx.sessionId,
+            turnId: ctx.turnId,
+            source: 'assistant',
+            text: `tick-${i}`,
+          });
+          await new Promise((r) => setTimeout(r, 5));
+        }
+      },
+    });
+
+    const session = new Session({ cwd: '/tmp', silent: true });
+    session.pluginHost.registerStatic(
+      definePlugin({
+        name: 'forever-plugin',
+        version: '0.0.0',
+        providers: [makeNoopProvider()],
+        modes: [foreverMode],
+      }),
+    );
+    session.providers.setActive('noop');
+    session.modes.setActive('forever');
+
+    // Break out after the first event — the generator must abort the strategy
+    // in its finally and return promptly (this await would never resolve if the
+    // turn ran to its non-existent completion in the background).
+    for await (const event of runTurn(session, 'go')) {
+      if (event.type === 'assistant_message') break;
+    }
+
+    expect(observedAbort).toBe(true);
+    expect(session.signal.aborted).toBe(false); // session-level signal untouched
+  });
+
+  it('an abandoned turn does NOT apply a mode switch it requested before being abandoned', async () => {
+    // A mode that immediately requests a hand-off, then loops until aborted and
+    // returns CLEANLY (no throw) on `signal.aborted` — so strategyError stays
+    // null. If the post-turn switch were gated only on `!strategyError`, an
+    // abandoned (consumer-broke-early) turn would silently flip the session into
+    // 'other' behind the user's back. It must stay on the original mode.
+    const requestThenLoop = defineMode({
+      name: 'requester',
+      run: async function* (ctx: ModeContext): AsyncIterable<MoxxyEvent> {
+        ctx.requestModeSwitch('other');
+        for (let i = 0; ; i++) {
+          if (ctx.signal.aborted) return; // clean return on abandonment
+          await ctx.emit({
+            type: 'assistant_message',
+            sessionId: ctx.sessionId,
+            turnId: ctx.turnId,
+            source: 'assistant',
+            text: `tick-${i}`,
+          });
+          await new Promise((r) => setTimeout(r, 5));
+        }
+      },
+    });
+
+    const session = new Session({ cwd: '/tmp', silent: true });
+    session.pluginHost.registerStatic(
+      definePlugin({
+        name: 'switch-on-abandon',
+        version: '0.0.0',
+        providers: [makeNoopProvider()],
+        modes: [requestThenLoop, defineMode({ name: 'other', run: async function* () {} })],
+      }),
+    );
+    session.providers.setActive('noop');
+    session.modes.setActive('requester');
+
+    // Abandon after the first event — the strategy aborts and returns cleanly.
+    for await (const event of runTurn(session, 'go')) {
+      if (event.type === 'assistant_message') break;
+    }
+
+    // The requested switch must be DROPPED because the turn was abandoned.
+    expect(session.modes.getActive().name).toBe('requester');
+  });
+
+  it('a completed turn still applies a requested mode switch', async () => {
+    // The positive case: a mode that requests a switch and completes normally
+    // hands off as before — the abandonment gate must not regress this.
+    const requestThenDone = defineMode({
+      name: 'handoff',
+      run: async function* (ctx: ModeContext): AsyncIterable<MoxxyEvent> {
+        ctx.requestModeSwitch('target');
+      },
+    });
+    const session = new Session({ cwd: '/tmp', silent: true });
+    session.pluginHost.registerStatic(
+      definePlugin({
+        name: 'switch-on-complete',
+        version: '0.0.0',
+        providers: [makeNoopProvider()],
+        modes: [requestThenDone, defineMode({ name: 'target', run: async function* () {} })],
+      }),
+    );
+    session.providers.setActive('noop');
+    session.modes.setActive('handoff');
+
+    await collectTurn(session, 'go');
+    expect(session.modes.getActive().name).toBe('target');
+  });
+
+  it('fires turnEnd even when the strategy throws (paired with turnStart)', async () => {
+    const calls: string[] = [];
+    const throwingMode = defineMode({
+      name: 'throws',
+      run: async function* (): AsyncIterable<MoxxyEvent> {
+        throw new Error('strategy boom');
+      },
+    });
+
+    const session = new Session({ cwd: '/tmp', silent: true });
+    session.pluginHost.registerStatic(
+      definePlugin({
+        name: 'lifecycle-probe',
+        version: '0.0.0',
+        providers: [makeNoopProvider()],
+        modes: [throwingMode],
+        hooks: {
+          onTurnStart: () => {
+            calls.push('start');
+          },
+          onTurnEnd: () => {
+            calls.push('end');
+          },
+        },
+      }),
+    );
+    session.providers.setActive('noop');
+    session.modes.setActive('throws');
+
+    let threw = false;
+    try {
+      await collectTurn(session, 'go');
+    } catch {
+      threw = true;
+    }
+    expect(threw).toBe(true);
+    // turnEnd must pair with turnStart even on the error path — no leaked
+    // turn-scoped plugin state.
+    expect(calls).toEqual(['start', 'end']);
+  });
+
+  it('a missing active provider records the prompt + a structured error, then rejects', async () => {
+    const session = new Session({ cwd: '/tmp', silent: true });
+    // No provider registered/active — getActive() throws.
+    session.pluginHost.registerStatic(
+      definePlugin({
+        name: 'mode-only',
+        version: '0.0.0',
+        modes: [makeMarkerLoop('marker', 1)],
+      }),
+    );
+    session.modes.setActive('marker');
+
+    let threw = false;
+    try {
+      await collectTurn(session, 'remember me');
+    } catch {
+      threw = true;
+    }
+    expect(threw).toBe(true);
+
+    // The user prompt is preserved (not silently discarded) and a structured
+    // error event was logged so channels see a normal failed turn.
+    const events = session.log.slice();
+    const prompt = events.find((e) => e.type === 'user_prompt');
+    expect((prompt as { text?: string } | undefined)?.text).toBe('remember me');
+    const error = events.find((e) => e.type === 'error');
+    expect(error).toBeDefined();
+    expect((error as { kind?: string }).kind).toBe('fatal');
+  });
+
+  it('a provider advertising no models fails fast (no opaque "default" model id)', async () => {
+    const emptyModelsProvider = defineProvider({
+      name: 'empty',
+      models: [],
+      createClient: () => ({
+        name: 'empty',
+        models: [],
+        stream: async function* () {},
+        countTokens: async () => 0,
+      }),
+    });
+    const session = new Session({ cwd: '/tmp', silent: true });
+    session.pluginHost.registerStatic(
+      definePlugin({
+        name: 'empty-models',
+        version: '0.0.0',
+        providers: [emptyModelsProvider],
+        modes: [makeMarkerLoop('marker', 1)],
+      }),
+    );
+    session.providers.setActive('empty');
+    session.modes.setActive('marker');
+
+    await expect(collectTurn(session, 'go')).rejects.toThrow(/no models configured/i);
+    // lastResolvedModel never gets the bogus sentinel.
+    expect(session.lastResolvedModel).toBeNull();
+  });
+});

package/src/run-turn.ts

@@ -1,4 +1,4 @@
-import type { EmittedEvent, ModeContext, MoxxyEvent, RunTurnOptions } from '@moxxy/sdk';
+import type { EmittedEvent, LLMProvider, ModeContext, MoxxyEvent, RunTurnOptions } from '@moxxy/sdk';
 import type { SessionRuntime } from './session-runtime.js';
 import { createSubagentSpawner } from './subagents.js';
 
@@ -20,16 +20,11 @@ export async function* runTurn(
   // Use a caller-supplied turnId when present (the runner mints it up front so
   // it can return the id before the turn runs); otherwise mint one here.
   const turnId = opts.turnId ?? session.startTurn().turnId;
-  const provider = session.providers.getActive();
-  const model = opts.model ?? provider.models[0]?.id ?? 'default';
-  // Record the resolution so out-of-band spawns (workflow triggers) can
-  // inherit the conversation's current model. Last-writer-wins when turns
-  // run concurrently — see the field's doc in SessionRuntime.
-  session.lastResolvedModel = model;
 
   const queue: MoxxyEvent[] = [];
   const waiters: Array<() => void> = [];
   let done = false;
+  let completed = false;
   let strategyError: unknown = null;
   // A mode can ask (via ctx.requestModeSwitch) to hand off to another mode
   // once this turn finishes — applied after the strategy drains, below.
@@ -42,6 +37,12 @@ export async function* runTurn(
     wake();
   });
 
+  // Generator-scoped controller so an early consumer return/throw (HTTP client
+  // disconnect, channel teardown) can abort the in-flight strategy instead of
+  // leaving it to run the whole agentic loop to completion in the background
+  // (burning tokens, holding resources) while the abandoned `finally` blocks on
+  // `strategyPromise`.
+  const turnController = new AbortController();
   let strategyPromise: Promise<void> | null = null;
 
   try {
@@ -56,12 +57,46 @@ export async function* runTurn(
         : {}),
     });
 
+    // Resolve provider + model AFTER the prompt is recorded so a
+    // missing/misconfigured provider doesn't silently discard the user's
+    // prompt or orphan the turnId. On failure, append a structured error event
+    // (channels see a normal failed turn) and rethrow.
+    let provider: LLMProvider;
+    let model: string;
+    try {
+      provider = session.providers.getActive();
+      const resolvedModel = opts.model ?? provider.models[0]?.id;
+      if (!resolvedModel) {
+        throw new Error(
+          `Active provider '${provider.name}' has no models configured`,
+        );
+      }
+      model = resolvedModel;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      await session.log.append({
+        type: 'error',
+        sessionId: session.id,
+        turnId,
+        source: 'system',
+        kind: 'fatal',
+        message,
+      });
+      throw err;
+    }
+    // Record the resolution so out-of-band spawns (workflow triggers) can
+    // inherit the conversation's current model. Last-writer-wins when turns
+    // run concurrently — see the field's doc in SessionRuntime.
+    session.lastResolvedModel = model;
+
     const strategy = session.modes.getActive();
-    // Combine the session's signal with the per-turn one (if provided)
-    // so either firing cancels the turn.
-    const effectiveSignal = opts.signal
-      ? AbortSignal.any([session.signal, opts.signal])
-      : session.signal;
+    // Combine the session's signal, the per-turn one (if provided), and the
+    // generator-scoped abandonment signal so any of them firing cancels the turn.
+    const effectiveSignal = AbortSignal.any(
+      opts.signal
+        ? [session.signal, opts.signal, turnController.signal]
+        : [session.signal, turnController.signal],
+    );
     // The session's working dir + environment, mirrored onto the ModeContext
     // so the shared tool dispatcher can hand onToolCall hooks the real cwd/env
     // (path-based policy hooks gate on these) instead of empty placeholders.
@@ -105,16 +140,21 @@ export async function* runTurn(
     const turnStartCtx = { ...appCtx, turnId, iteration: 0 };
 
     strategyPromise = (async () => {
+      let started = false;
       try {
         await session.dispatcher.dispatchTurnStart(turnStartCtx);
+        started = true;
         for await (const _ of strategy.run(ctx)) {
           // Events are surfaced via the log subscription above.
           void _;
         }
-        await session.dispatcher.dispatchTurnEnd(turnStartCtx);
       } catch (err) {
         strategyError = err;
       } finally {
+        // turnEnd must pair with turnStart even when the strategy throws/aborts,
+        // so plugins that allocate turn-scoped state in onTurnStart (spans,
+        // timers, token meters) always get the matching teardown.
+        if (started) await session.dispatcher.dispatchTurnEnd(turnStartCtx);
         done = true;
         wake();
       }
@@ -125,15 +165,25 @@ export async function* runTurn(
       if (done) break;
       await new Promise<void>((resolve) => waiters.push(resolve));
     }
+    completed = true;
   } finally {
     unsubscribe();
+    // If the consumer abandoned iteration early (broke out of the `for await`,
+    // an outer error), `completed` is still false: abort the strategy so it
+    // unwinds promptly instead of running the full loop in the background while
+    // this `finally` blocks on `strategyPromise`.
+    if (!completed) turnController.abort('runTurn iteration abandoned');
     if (strategyPromise) await strategyPromise;
     // Apply a mode hand-off the strategy requested, now that the turn has
-    // fully drained. Only on clean completion (a thrown/aborted turn keeps
-    // the current mode); an unknown target is ignored so a bad name can't
-    // wedge the session. The registry's setActive triggers the runner's
-    // InfoChanged broadcast, so channels see the new mode.
-    if (requestedModeSwitch && !strategyError) {
+    // fully drained. Only on clean completion: a thrown turn (strategyError) OR
+    // an ABANDONED turn (consumer broke out early — `completed` is false, and a
+    // mode that returns cleanly on `signal.aborted` leaves strategyError null)
+    // keeps the current mode, so an unwatched/cancelled turn can't silently
+    // flip the session into a different mode behind the user's back. An unknown
+    // target is ignored so a bad name can't wedge the session. The registry's
+    // setActive triggers the runner's InfoChanged broadcast, so channels see the
+    // new mode.
+    if (requestedModeSwitch && completed && !strategyError) {
       try {
         session.modes.setActive(requestedModeSwitch);
       } catch {

package/src/session.test.ts

@@ -72,6 +72,30 @@ describe('Session', () => {
     expect(s.signal.aborted).toBe(true);
   });
 
+  it('close() still runs plugin onShutdown when surface teardown rejects', async () => {
+    const s = new Session({ cwd: '/tmp', silent: true });
+    const onShutdown = vi.fn();
+    s.pluginHost.registerStatic(
+      definePlugin({ name: 'p', version: '0.0.0', hooks: { onShutdown } }),
+    );
+    // A flaky native surface (PTY/browser) throwing during teardown must not
+    // pre-empt the plugin shutdown hooks — those are how plugins flush state.
+    vi.spyOn(s.surfaces, 'closeAll').mockRejectedValue(new Error('PTY teardown blew up'));
+
+    await expect(s.close()).resolves.toBeUndefined();
+    expect(onShutdown).toHaveBeenCalledTimes(1);
+    expect(s.signal.aborted).toBe(true);
+  });
+
+  it('appContext env is a frozen, stable snapshot (reused across calls)', () => {
+    const s = new Session({ cwd: '/tmp', silent: true });
+    const a = s.appContext();
+    const b = s.appContext();
+    // Memoized: the same frozen object is handed out, not a fresh clone each call.
+    expect(a.env).toBe(b.env);
+    expect(Object.isFrozen(a.env)).toBe(true);
+  });
+
   it('close() is idempotent', async () => {
     const s = new Session({ cwd: '/tmp', silent: true });
     const onShutdown = vi.fn();