@moxxy/core 0.5.0 → 0.5.2

package/src/subagents/run-child.ts

@@ -46,9 +46,10 @@ import {
 } from './events.js';
 import { buildFilteredToolRegistry } from './tools.js';
 import {
-  getRetainedChild,
+  claimRetainedChild,
   registerRetainedChild,
   releaseRetainedChild,
+  unclaimRetainedChild,
   type RetainedChildSession,
 } from './registry.js';
 
@@ -86,10 +87,13 @@ export async function runChildTurn(args: {
   if ('failure' in resolved) return resolved.failure;
   const { strategy, strategyName } = resolved;
 
+  // `undefined` means "inherit the full parent registry"; a present-but-empty
+  // array means "deny all" (least-privilege). Collapsing the two would turn an
+  // explicit [] into full tool inheritance — the opposite of the caller's intent.
   const toolRegistry: ToolRegistry =
-    spec.allowedTools && spec.allowedTools.length > 0
-      ? buildFilteredToolRegistry(parentSession.tools, new Set(spec.allowedTools))
-      : parentSession.tools;
+    spec.allowedTools === undefined
+      ? parentSession.tools
+      : buildFilteredToolRegistry(parentSession.tools, new Set(spec.allowedTools));
 
   const childModel = await resolveChildModel(rt, spec, label, childSessionId);
 
@@ -122,7 +126,7 @@ export async function runChildTurn(args: {
   });
 
   if (retainSession) {
-    registerRetainedChild({
+    const evicted = registerRetainedChild({
       label,
       childSessionId,
       childTurnId,
@@ -133,53 +137,98 @@ export async function runChildTurn(args: {
       strategyName,
       parentSession,
       parentTurnId,
+      tokensUsed: capture.tokensUsed,
     });
+    // A capped/TTL-expired paused child is now unreachable: its `continue()`
+    // will fail. Surface that on the EVICTED child's own parent log (best-effort
+    // — a warning append must never take this spawn down) so the operator who
+    // started it isn't left waiting on a resume that can no longer happen.
+    await warnEvicted(evicted);
   }
 
   return capture.result;
 }
 
+/**
+ * Emit a `subagent_warning` on each evicted child's OWN parent log so the
+ * operator who spawned a now-unreachable paused child sees why its `continue()`
+ * will fail. Best-effort: a warning-append reject (or a since-closed parent
+ * session) must never propagate out of the spawn that triggered the eviction.
+ */
+async function warnEvicted(evicted: ReadonlyArray<RetainedChildSession>): Promise<void> {
+  for (const e of evicted) {
+    try {
+      await emitSubagentWarning(
+        e.parentSession,
+        e.parentTurnId,
+        e.label,
+        e.childSessionId,
+        `retained subagent "${e.label}" was evicted before resume ` +
+          `(retention cap or TTL reached); its continue() will no longer work`,
+      );
+    } catch {
+      // A closed/failing parent log must not abort the spawn that evicted it.
+    }
+  }
+}
+
 export async function continueChildTurn(args: {
   childSessionId: SessionId;
   prompt: string;
   label?: string;
 }): Promise<SubagentResult> {
-  const retained = getRetainedChild(args.childSessionId);
+  // Claim-then-run: atomically remove the entry from the registry and mark it
+  // busy so a racing continue()/release() for the same id can't observe the
+  // live entry and drive strategy.run over the same childLog/childCtx in
+  // parallel (interleaved appends, double-seeded prompts, double release).
+  const retained = claimRetainedChild(args.childSessionId);
   if (!retained) {
     throw new Error(`no retained subagent session for "${String(args.childSessionId)}"`);
   }
 
-  await retained.childLog.append({
-    type: 'user_prompt',
-    sessionId: retained.childSessionId,
-    turnId: retained.childTurnId,
-    source: 'user',
-    text: args.prompt,
-  });
+  try {
+    await retained.childLog.append({
+      type: 'user_prompt',
+      sessionId: retained.childSessionId,
+      turnId: retained.childTurnId,
+      source: 'user',
+      text: args.prompt,
+    });
 
-  const rt: SubagentRuntime = {
-    parentSession: retained.parentSession,
-    parentTurnId: retained.parentTurnId,
-    parentSignal: retained.childCtx.signal,
-    parentModel: retained.childCtx.model,
-  };
+    const rt: SubagentRuntime = {
+      parentSession: retained.parentSession,
+      parentTurnId: retained.parentTurnId,
+      // Re-derive the resume signal from the still-live owning session rather
+      // than reusing the possibly-already-aborted per-turn signal captured at
+      // first-turn spawn time (which would cancel the resume before any work).
+      parentSignal: retained.parentSession.signal,
+      parentModel: retained.childCtx.model,
+    };
 
-  const capture = await executeChildLoop({
-    rt,
-    spec: retained.spec,
-    label: args.label ?? retained.label,
-    childSessionId: retained.childSessionId,
-    childTurnId: retained.childTurnId,
-    childLog: retained.childLog,
-    childCtx: retained.childCtx,
-    strategy: retained.strategy,
-    strategyName: retained.strategyName,
-    emitCompleted: true,
-    skipStartEvent: true,
-  });
+    const capture = await executeChildLoop({
+      rt,
+      spec: retained.spec,
+      label: args.label ?? retained.label,
+      childSessionId: retained.childSessionId,
+      childTurnId: retained.childTurnId,
+      childLog: retained.childLog,
+      childCtx: retained.childCtx,
+      strategy: retained.strategy,
+      strategyName: retained.strategyName,
+      emitCompleted: true,
+      skipStartEvent: true,
+      // Carry forward the cost accumulated across prior turns so the deferred
+      // subagent_completed reports the retained session's cumulative usage, not
+      // just this last continue's delta.
+      priorTokensUsed: retained.tokensUsed ?? 0,
+    });
 
-  releaseRetainedChild(args.childSessionId);
-  return capture.result;
+    return capture.result;
+  } finally {
+    // The entry was already removed by the claim; just drop the busy marker so
+    // a future continue() (if the session were re-registered) isn't blocked.
+    unclaimRetainedChild(args.childSessionId);
+  }
 }
 
 async function executeChildLoop(args: {
@@ -194,7 +243,8 @@ async function executeChildLoop(args: {
   strategyName: string;
   emitCompleted: boolean;
   skipStartEvent?: boolean;
-}): Promise<{ result: SubagentResult }> {
+  priorTokensUsed?: number;
+}): Promise<{ result: SubagentResult; tokensUsed: number }> {
   const {
     rt,
     spec,
@@ -207,6 +257,7 @@ async function executeChildLoop(args: {
     strategyName,
     emitCompleted,
     skipStartEvent,
+    priorTokensUsed = 0,
   } = args;
   const { parentSession, parentTurnId } = rt;
 
@@ -214,7 +265,7 @@ async function executeChildLoop(args: {
     text: '',
     stopReason: 'end_turn' as StopReason,
     error: null as string | null,
-    tokensUsed: 0,
+    tokensUsed: priorTokensUsed,
   };
 
   const unsubCapture = childLog.subscribe((e) => {
@@ -280,7 +331,7 @@ async function executeChildLoop(args: {
     );
   }
 
-  return { result };
+  return { result, tokensUsed: capture.tokensUsed };
 }
 
 async function resolveStrategy(
@@ -296,23 +347,26 @@ async function resolveStrategy(
   const exact = parentSession.modes.list().find((s) => s.name === requestedStrategy);
   if (exact) return { strategy: exact, strategyName: requestedStrategy };
 
-  // Fall back to the default mode if the model invented a name
-  // (e.g. "react"). Failing the child outright wastes the user's turn —
-  // any reasonable agent task can run on the default mode. We surface the
-  // fallback as a non-fatal warning event so the operator sees it.
-  const fallback = parentSession.modes.list().find((s) => s.name === 'default');
+  // Fall back when the model invented a name (e.g. "react"). Failing the child
+  // outright wastes the user's turn — any reasonable agent task can run on the
+  // session's current strategy. Prefer a mode literally named "default", then
+  // the session's active mode (a host may ship a renamed/alternative default),
+  // surfacing the fallback as a non-fatal warning so the operator sees it.
+  const fallback =
+    parentSession.modes.list().find((s) => s.name === 'default') ??
+    safeActiveMode(parentSession);
   if (fallback) {
     await emitSubagentWarning(
       parentSession,
       parentTurnId,
       label,
       childSessionId,
-      `unknown mode "${requestedStrategy}" — falling back to "default"`,
+      `unknown mode "${requestedStrategy}" — falling back to "${fallback.name}"`,
     );
-    return { strategy: fallback, strategyName: 'default' };
+    return { strategy: fallback, strategyName: fallback.name };
   }
 
-  // No default mode either — that's a config error, not a model mistake.
+  // No fallback mode at all — that's a config error, not a model mistake.
   await emitSubagentStart(parentSession, parentTurnId, label, childSessionId, spec, requestedStrategy);
   const errorMsg = `Subagent failed: unknown mode "${requestedStrategy}" and no fallback available`;
   await emitSubagentCompleted(parentSession, parentTurnId, label, childSessionId, '', 'error', errorMsg, spec.agentType ?? 'default', 0);
@@ -327,6 +381,17 @@ async function resolveStrategy(
   };
 }
 
+/** `modes.getActive()` throws when no mode is active; treat that as "no fallback". */
+function safeActiveMode(
+  parentSession: SessionRuntime,
+): ReturnType<SessionRuntime['modes']['list']>[number] | undefined {
+  try {
+    return parentSession.modes.getActive();
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Resolve the child's effective model. A `spec.model` usually comes from the
  * calling LLM (dispatch_agent's free-form string field), which sometimes
@@ -405,15 +470,54 @@ function buildChildContext(
   };
 }
 
+/**
+ * Build an error-bearing {@link SubagentResult} for a spec whose `runChildTurn`
+ * threw during setup (before it could degrade the error into a result itself).
+ * Keeps `spawnAll` total: one result per spec, in input order, never a thrown
+ * batch. The real child id is unknown here (setup failed before it was captured),
+ * so a fresh placeholder id is minted; the result still carries the failing
+ * spec's label and the error message.
+ */
+function spawnFailureResult(spec: SubagentSpec, reason: unknown): SubagentResult {
+  const message = reason instanceof Error ? reason.message : String(reason);
+  return {
+    label: spec.label ?? 'subagent',
+    childSessionId: newSessionId(),
+    text: '',
+    stopReason: 'error' as StopReason,
+    error: { message },
+  };
+}
+
 export function createSubagentSpawner(rt: SubagentRuntime): SubagentSpawner {
   return {
     async spawn(spec) {
       return runChildTurn({ rt, spec, retainSession: spec.retainSession === true });
     },
     async spawnAll(specs) {
-      return Promise.all(
-        specs.map((s) => runChildTurn({ rt, spec: s, retainSession: s.retainSession === true })),
+      // Per-child degradation: a single child's PRE-`try` setup throw (no active
+      // provider, a `compactors.getActive()` config error, a log-append reject in
+      // `resolveStrategy`) must NOT reject the whole batch, and must NEVER abort or
+      // orphan its still-running siblings (whose later settlement would otherwise
+      // surface as an `unhandledRejection`). `Promise.all` short-circuits on the
+      // first rejection and leaks the rest — `Promise.allSettled` always waits for
+      // every child and never rejects. Each spec yields exactly one result, in
+      // input order; a setup throw becomes an error-bearing `SubagentResult` so a
+      // fan-out partially succeeds instead of taking the parent turn down with it.
+      const outcomes = await Promise.allSettled(
+        specs.map((spec) =>
+          runChildTurn({ rt, spec, retainSession: spec.retainSession === true }),
+        ),
       );
+      return outcomes.map((outcome, i): SubagentResult => {
+        if (outcome.status === 'fulfilled') return outcome.value;
+        // `specs[i]` is always defined here (i indexes the same array we mapped),
+        // but `noUncheckedIndexedAccess` widens it to `| undefined`; narrow so the
+        // failure result still carries the failing spec's label rather than the
+        // generic fallback.
+        const spec = specs[i];
+        return spawnFailureResult(spec ?? { prompt: '' }, outcome.reason);
+      });
     },
     async continue(args: SubagentContinueArgs) {
       return continueChildTurn(args);

package/src/surfaces/host.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, vi } from 'vitest';
 import {
   defineSurface,
   type SurfaceDataMessage,
@@ -93,6 +93,76 @@ describe('SurfaceHostImpl viewer ref-counting', () => {
   });
 });
 
+describe('SurfaceHostImpl shutdown leak/hang hardening', () => {
+  it('closeAll closes an open() that resolves AFTER teardown (no leaked instance)', async () => {
+    // The open()'s def.open promise resolves only after closeAll has run; the
+    // freshly-created instance must be torn down, not installed as an orphan.
+    let resolveOpen!: () => void;
+    const gate = new Promise<void>((r) => {
+      resolveOpen = r;
+    });
+    const state = { closed: 0, instances: [] as SurfaceInstance[] };
+    const def = defineSurface({
+      kind: 'terminal',
+      open: async () => {
+        await gate;
+        const instance: SurfaceInstance = {
+          id: 'terminal',
+          kind: 'terminal',
+          onData: () => () => {},
+          input: () => {},
+          close: () => {
+            state.closed += 1;
+          },
+        };
+        state.instances.push(instance);
+        return instance;
+      },
+    });
+    const host = makeHost(def);
+
+    const openPromise = host.open('terminal'); // in-flight, parked on the gate
+    const closeAll = host.closeAll(); // sets disposed; awaits the in-flight open
+    resolveOpen(); // open resolves only now, after teardown began
+    await expect(openPromise).rejects.toThrow(/has been closed/);
+    await closeAll;
+
+    // The instance was created — and immediately closed, never installed.
+    expect(state.instances).toHaveLength(1);
+    expect(state.closed).toBe(1);
+    // A stray open() after shutdown is rejected before creating anything.
+    await expect(host.open('terminal')).rejects.toThrow(/has been closed/);
+  });
+
+  it('a wedged instance.close() does not hang closeAll forever', async () => {
+    vi.useFakeTimers();
+    try {
+      const state = { closed: 0 };
+      const def = defineSurface({
+        kind: 'terminal',
+        open: () => ({
+          id: 'terminal',
+          kind: 'terminal',
+          onData: () => () => {},
+          input: () => {},
+          // Never resolves: a wedged PTY/browser teardown.
+          close: () => new Promise<void>(() => {}),
+        }),
+      });
+      const host = makeHost(def);
+      await host.open('terminal');
+
+      const done = host.closeAll();
+      // Without the timeout this would never settle; advance past it.
+      await vi.advanceTimersByTimeAsync(6000);
+      await expect(done).resolves.toBeUndefined();
+      expect(state.closed).toBe(0); // close() never resolved, but we moved on
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
 /**
  * A controllable surface whose instance lets the test PUSH frames (`emit`),
  * record resize calls, and run unsubscribe on close — enough to assert the

package/src/surfaces/host.ts

@@ -25,6 +25,8 @@ import type { SurfaceRegistryImpl } from '../registries/surfaces.js';
  * existing resource and gets its {@link SurfaceInstance.snapshot}.
  */
 export class SurfaceHostImpl implements SurfaceHost {
+  /** Upper bound on a single instance.close() before we give up waiting on it. */
+  private static readonly CLOSE_TIMEOUT_MS = 5000;
   /** Open instances, keyed by kind (one shared instance per kind). */
   private readonly instances = new Map<SurfaceKind, SurfaceInstance>();
   /** Per-instance unsubscribe from its onData, dropped on close. */
@@ -44,6 +46,8 @@ export class SurfaceHostImpl implements SurfaceHost {
    * snapshot, but keystrokes/navigation silently vanish).
    */
   private readonly refs = new Map<SurfaceKind, number>();
+  /** Set once closeAll() runs: rejects/ tears down any open() that races teardown. */
+  private disposed = false;
 
   constructor(
     private readonly registry: SurfaceRegistryImpl,
@@ -77,6 +81,7 @@ export class SurfaceHostImpl implements SurfaceHost {
   }
 
   async open(kind: SurfaceKind): Promise<OpenSurfaceResult> {
+    if (this.disposed) throw new Error('SurfaceHost has been closed');
     const existing = this.instances.get(kind);
     if (existing) {
       this.retain(kind);
@@ -95,6 +100,12 @@ export class SurfaceHostImpl implements SurfaceHost {
 
     const promise = (async (): Promise<OpenSurfaceResult> => {
       const instance = await def.open(this.ctx);
+      // If teardown raced this create, never install the live resource — close
+      // it immediately so we don't leak a PTY/page/child process post-shutdown.
+      if (this.disposed) {
+        await this.safeClose(instance);
+        throw new Error('SurfaceHost has been closed');
+      }
       this.instances.set(kind, instance);
       this.refs.set(kind, 1);
       // Re-emit this instance's frames as multiplexed SurfaceDataMessages.
@@ -138,13 +149,33 @@ export class SurfaceHostImpl implements SurfaceHost {
     this.unsubs.get(surfaceId)?.();
     this.unsubs.delete(surfaceId);
     this.instances.delete(kind);
+    await this.safeClose(instance, surfaceId);
+  }
+
+  /**
+   * Tear an instance down without ever blocking forever: a wedged PTY/browser
+   * whose close() neither resolves nor rejects must not stall session shutdown.
+   * Races close() against a timeout and swallows (logs) any rejection.
+   */
+  private async safeClose(instance: SurfaceInstance, surfaceId = instance.id): Promise<void> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
     try {
-      await instance.close();
+      await Promise.race([
+        Promise.resolve(instance.close()),
+        new Promise<void>((resolve) => {
+          timer = setTimeout(() => {
+            this.logger?.warn?.('SurfaceHost: close timed out', { surfaceId });
+            resolve();
+          }, SurfaceHostImpl.CLOSE_TIMEOUT_MS);
+        }),
+      ]);
     } catch (err) {
       this.logger?.warn?.('SurfaceHost: close failed', {
         surfaceId,
         err: err instanceof Error ? err.message : String(err),
       });
+    } finally {
+      if (timer) clearTimeout(timer);
     }
   }
 
@@ -168,9 +199,15 @@ export class SurfaceHostImpl implements SurfaceHost {
 
   async closeAll(): Promise<void> {
     // Session shutdown: tear every instance down regardless of viewer refs.
+    this.disposed = true;
+    // Drain in-flight opens first. With `disposed` set, each racing open closes
+    // its freshly-created instance itself and rejects, so nothing new lands in
+    // `instances` after this await — no leaked PTY/page/child process.
+    await Promise.allSettled([...this.opening.values()]);
     for (const kind of [...this.instances.keys()]) this.refs.set(kind, 1);
+    // Run closes concurrently so one wedged instance can't block the others.
     const ids = [...this.unsubs.keys()];
-    for (const id of ids) await this.close(id);
+    await Promise.allSettled(ids.map((id) => this.close(id)));
   }
 
   private byId(surfaceId: string): SurfaceInstance | undefined {

package/src/usage-stats.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { promises as fs } from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
@@ -74,4 +74,102 @@ describe('usage-stats store', () => {
     await fs.writeFile(statsPath, '{ not json', 'utf8');
     expect((await loadUsageStats(statsPath)).models).toEqual({});
   });
+
+  it('rejects a shape-valid file with a non-numeric counter (no string-concat corruption)', async () => {
+    // A hand-edited / partially-written file where a counter is a string used to
+    // pass the old `typeof models === 'object'` cast and flow straight into
+    // addModelTotals, corrupting the aggregate via "100" + 50 = "10050".
+    await fs.writeFile(
+      statsPath,
+      JSON.stringify({
+        version: 1,
+        updatedAt: new Date().toISOString(),
+        models: {
+          'anthropic/opus': {
+            calls: 1,
+            inputTokens: '100',
+            outputTokens: 0,
+            cacheReadTokens: 0,
+            cacheCreationTokens: 0,
+            firstSeen: new Date().toISOString(),
+            lastSeen: new Date().toISOString(),
+          },
+        },
+      }),
+      'utf8',
+    );
+    // Shape-invalid → fall through to empty, exactly like malformed JSON.
+    expect((await loadUsageStats(statsPath)).models).toEqual({});
+
+    // And a subsequent merge produces purely numeric totals (no concatenation).
+    await mergeUsageStats({ 'anthropic/opus': totals({ inputTokens: 50 }) }, statsPath);
+    const file = await loadUsageStats(statsPath);
+    expect(file.models['anthropic/opus']!.inputTokens).toBe(50);
+    expect(typeof file.models['anthropic/opus']!.inputTokens).toBe('number');
+  });
+
+  it('clear and merge serialize on the same mutex (clear cannot resurrect a cleared aggregate)', async () => {
+    await mergeUsageStats({ 'anthropic/opus': totals({ inputTokens: 100 }) }, statsPath);
+    // Fire a clear and a merge concurrently. Whatever the interleaving, the two
+    // must serialize against each other so the file is never the stale
+    // pre-clear snapshot reconstituted by a merge that read before the clear.
+    // The only sound end-states are: empty (merge ran then clear), or exactly
+    // the merged delta (clear ran then merge) — never the resurrected old 100
+    // plus delta.
+    await Promise.all([
+      clearUsageStats(statsPath),
+      mergeUsageStats({ 'anthropic/opus': totals({ inputTokens: 7 }) }, statsPath),
+    ]);
+    const file = await loadUsageStats(statsPath);
+    const entry = file.models['anthropic/opus'];
+    if (entry) {
+      // clear-then-merge ordering: only the post-clear delta survives.
+      expect(entry.inputTokens).toBe(7);
+    } else {
+      // merge-then-clear ordering: aggregate is empty.
+      expect(file.models).toEqual({});
+    }
+  });
+
+  it('swallows a write failure on merge: logs to stderr, returns the merged file, never throws', async () => {
+    // mergeUsageStats runs on shutdown and is documented best-effort — losing one
+    // session's stats must never block shutdown. Force an unwritable target by
+    // pointing the file *under a regular file* so the atomic writer's
+    // `mkdir(dirname)` fails with ENOTDIR.
+    const blocker = path.join(tmpDir, 'blocker');
+    await fs.writeFile(blocker, 'x', 'utf8');
+    const unwritable = path.join(blocker, 'nested', 'usage.json');
+    const stderr = vi.spyOn(process.stderr, 'write').mockReturnValue(true);
+    try {
+      const result = await mergeUsageStats(
+        { 'anthropic/opus': totals({ inputTokens: 5 }) },
+        unwritable,
+      );
+      // Resolves with the in-memory merged file (the caller still sees the delta),
+      // and surfaces the persist failure on stderr rather than throwing.
+      expect(result.models['anthropic/opus']!.inputTokens).toBe(5);
+      expect(stderr).toHaveBeenCalled();
+    } finally {
+      stderr.mockRestore();
+    }
+  });
+
+  it('clearUsageStats rejects (loud) if it cannot write — a clear that did not persist must not look successful', async () => {
+    // Unlike merge, clear is an explicit user action (`/usage clear`); silently
+    // swallowing its failure would tell the user the aggregate was wiped when it
+    // was not. We pin the current behavior so a future refactor can't quietly
+    // turn it into a no-op success.
+    const blocker = path.join(tmpDir, 'clear-blocker');
+    await fs.writeFile(blocker, 'x', 'utf8');
+    const unwritable = path.join(blocker, 'nested', 'usage.json');
+    await expect(clearUsageStats(unwritable)).rejects.toBeInstanceOf(Error);
+  });
+
+  it('coalesces a missing firstSeen on merge rather than emitting undefined', async () => {
+    // Defense in depth: even if an entry somehow lacks firstSeen, a merge must
+    // not propagate `firstSeen: undefined` forward.
+    await mergeUsageStats({ 'anthropic/opus': totals({ inputTokens: 1 }) }, statsPath);
+    const file = await loadUsageStats(statsPath);
+    expect(file.models['anthropic/opus']!.firstSeen).toBeTruthy();
+  });
 });