@moxxy/core 0.5.0 → 0.5.2

package/src/skills/synthesize.ts

@@ -84,12 +84,11 @@ export async function synthesizeSkill(
   }
   const frontmatter = parsed.data as Skill['frontmatter'];
 
-  const finalPath = await uniqueFilename(baseDir, slugify(frontmatter.name));
-  await fs.writeFile(finalPath, draft.raw, 'utf8');
+  const finalPath = await writeUniqueSkill(baseDir, slugify(frontmatter.name), draft.raw);
 
   // Derive the skill id from the on-disk filename, not from the LLM-supplied
   // frontmatter name — otherwise synthesizing the same name twice collides
-  // even when uniqueFilename has just bumped the filename to `<slug>-2.md`.
+  // even when writeUniqueSkill has just bumped the filename to `<slug>-2.md`.
   const basename = path.basename(finalPath, '.md');
   const skill: Skill = {
     id: asSkillId(`${scope}/${basename}`),
@@ -100,26 +99,46 @@ export async function synthesizeSkill(
   };
   session.skills.register(skill);
 
-  await session.log.append({
-    type: 'skill_created',
-    sessionId: session.id,
-    turnId: turnId ?? session.startTurn().turnId,
-    source: 'system',
-    skillId: skill.id,
-    name: skill.frontmatter.name,
-    path: finalPath,
-    scope,
-    originatingPrompt: intent,
-  });
+  // The skill file on disk + the live registration are the product; the
+  // skill_created event and the audit JSONL line are telemetry. A failure in
+  // either (listener/persistence reject, EACCES on .meta, read-only fs) must
+  // NOT throw after the skill is already written + registered — that would
+  // surface an error the model retries, orphaning the just-created skill and
+  // duplicating it. Make both best-effort and warn instead.
+  try {
+    await session.log.append({
+      type: 'skill_created',
+      sessionId: session.id,
+      turnId: turnId ?? session.startTurn().turnId,
+      source: 'system',
+      skillId: skill.id,
+      name: skill.frontmatter.name,
+      path: finalPath,
+      scope,
+      originatingPrompt: intent,
+    });
+  } catch (err) {
+    process.stderr.write(
+      `moxxy: synthesize_skill could not emit skill_created for "${skill.frontmatter.name}": ` +
+        `${err instanceof Error ? err.message : String(err)}\n`,
+    );
+  }
 
   const auditPath = opts.auditPath ?? path.join(defaultUserSkillsDir(), '.meta', 'created.jsonl');
-  await appendAudit(auditPath, {
-    slug: path.basename(finalPath, '.md'),
-    ts: new Date().toISOString(),
-    sessionId: String(session.id),
-    originatingPrompt: intent,
-    scope,
-  });
+  try {
+    await appendAudit(auditPath, {
+      slug: path.basename(finalPath, '.md'),
+      ts: new Date().toISOString(),
+      sessionId: String(session.id),
+      originatingPrompt: intent,
+      scope,
+    });
+  } catch (err) {
+    process.stderr.write(
+      `moxxy: synthesize_skill audit append failed (${auditPath}): ` +
+        `${err instanceof Error ? err.message : String(err)}\n`,
+    );
+  }
 
   return { skill, path: finalPath, scope };
 }
@@ -132,28 +151,62 @@ function slugify(name: string): string {
     .slice(0, 60);
 }
 
-async function uniqueFilename(dir: string, base: string): Promise<string> {
-  let candidate = path.join(dir, `${base}.md`);
-  let n = 2;
-  while (await exists(candidate)) {
-    candidate = path.join(dir, `${base}-${n}.md`);
-    n += 1;
+/**
+ * Pick a unique `<base>[-N].md` name AND create it atomically with the `wx`
+ * flag (fail if exists). Name selection and creation are one step, so two
+ * concurrent synthesizeSkill calls (workflows / self-improver) racing on the
+ * same slug can't both pick the same candidate and have the later writeFile
+ * truncate the earlier skill — the loser gets EEXIST and bumps the suffix.
+ */
+async function writeUniqueSkill(dir: string, base: string, data: string): Promise<string> {
+  let n = 1;
+  // Bound the search so a directory already saturated with `<base>-*.md` (or a
+  // persistent EEXIST race) can't spin forever — surface a clear error instead.
+  const MAX_ATTEMPTS = 1000;
+  for (;;) {
+    const candidate = path.join(dir, n === 1 ? `${base}.md` : `${base}-${n}.md`);
+    try {
+      await fs.writeFile(candidate, data, { encoding: 'utf8', flag: 'wx' });
+      return candidate;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
+      n += 1;
+      if (n > MAX_ATTEMPTS) {
+        throw new Error(
+          `synthesize_skill: could not find a free filename for "${base}" after ${MAX_ATTEMPTS} attempts`,
+        );
+      }
+    }
   }
-  return candidate;
 }
 
-async function exists(p: string): Promise<boolean> {
-  try {
-    await fs.access(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
+/** Cap the audit JSONL so a long-lived/self-synthesizing install can't grow it without bound. */
+const MAX_AUDIT_LINES = 2000;
 
 async function appendAudit(filePath: string, entry: Record<string, unknown>): Promise<void> {
   await fs.mkdir(path.dirname(filePath), { recursive: true });
   await fs.appendFile(filePath, JSON.stringify(entry) + '\n', 'utf8');
+  await rotateAuditIfNeeded(filePath);
+}
+
+/**
+ * Keep only the most recent {@link MAX_AUDIT_LINES} lines. Best-effort and
+ * non-atomic by design — this file is pure telemetry that nothing reads back
+ * with a bound, so a crash mid-rewrite at worst loses a few audit lines.
+ */
+async function rotateAuditIfNeeded(filePath: string): Promise<void> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(filePath, 'utf8');
+  } catch {
+    return;
+  }
+  const lines = raw.split('\n');
+  // Account for the trailing empty element from the final newline.
+  const nonEmpty = lines.filter((l) => l.length > 0);
+  if (nonEmpty.length <= MAX_AUDIT_LINES) return;
+  const kept = nonEmpty.slice(nonEmpty.length - MAX_AUDIT_LINES);
+  await fs.writeFile(filePath, kept.join('\n') + '\n', 'utf8');
 }
 
 export function buildSynthesizeSkillPlugin(

package/src/subagents/events.test.ts

@@ -53,4 +53,60 @@ describe('streamChildEventToParent', () => {
     expect(arg.type).toBe('plugin_event');
     expect(arg.subtype).toBe('subagent_tool_call');
   });
+
+  // A child Bash/Read returning a multi-MB blob must NOT be copied verbatim into
+  // the parent log (unbounded amplification): the forwarded output is truncated.
+  it('truncates an oversized child tool_result output before mirroring to the parent', async () => {
+    const append = vi.fn().mockResolvedValue(undefined);
+    const parent = {
+      id: asSessionId('parent'),
+      log: { append } as unknown as EventLog,
+    } as unknown as SessionRuntime;
+
+    const huge = 'x'.repeat(2 * 1024 * 1024); // 2 MiB
+    const bigResult = {
+      type: 'tool_result',
+      seq: 1,
+      id: 'e1',
+      ts: 0,
+      sessionId: asSessionId('child'),
+      turnId: asTurnId('ct'),
+      source: 'model',
+      callId: 'call-2',
+      ok: true,
+      output: huge,
+    } as unknown as MoxxyEvent;
+
+    await streamChildEventToParent(parent, asTurnId('pt'), 'researcher', asSessionId('child'), bigResult);
+    expect(append).toHaveBeenCalledTimes(1);
+    const arg = append.mock.calls[0]![0] as { payload: { output: string } };
+    expect(arg.payload.output.length).toBeLessThan(huge.length);
+    expect(arg.payload.output.length).toBeLessThan(64 * 1024);
+    expect(arg.payload.output).toContain('elided');
+  });
+
+  it('passes a small child tool_result output through unchanged', async () => {
+    const append = vi.fn().mockResolvedValue(undefined);
+    const parent = {
+      id: asSessionId('parent'),
+      log: { append } as unknown as EventLog,
+    } as unknown as SessionRuntime;
+
+    const smallResult = {
+      type: 'tool_result',
+      seq: 1,
+      id: 'e1',
+      ts: 0,
+      sessionId: asSessionId('child'),
+      turnId: asTurnId('ct'),
+      source: 'model',
+      callId: 'call-3',
+      ok: true,
+      output: 'short output',
+    } as unknown as MoxxyEvent;
+
+    await streamChildEventToParent(parent, asTurnId('pt'), 'researcher', asSessionId('child'), smallResult);
+    const arg = append.mock.calls[0]![0] as { payload: { output: unknown } };
+    expect(arg.payload.output).toBe('short output');
+  });
 });

package/src/subagents/events.ts

@@ -133,6 +133,32 @@ export async function streamChildEventToParent(
   }
 }
 
+/** Max chars of a forwarded child tool output/error mirrored onto the parent log. */
+const MAX_FORWARD_CHARS = 16 * 1024;
+
+/**
+ * Bound an arbitrary child tool result before mirroring it onto the parent log.
+ * Strings are truncated with an elision marker; other values pass through when
+ * their serialized length is small and are replaced with a marker when not (we
+ * avoid re-parsing — the full payload still lives in the child log).
+ */
+function truncateForward(value: unknown): unknown {
+  if (typeof value === 'string') {
+    return value.length > MAX_FORWARD_CHARS
+      ? `${value.slice(0, MAX_FORWARD_CHARS)}… [${value.length - MAX_FORWARD_CHARS} more chars elided]`
+      : value;
+  }
+  if (value === null || value === undefined || typeof value !== 'object') return value;
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(value);
+  } catch {
+    return '[unserializable subagent output elided]';
+  }
+  if (serialized.length <= MAX_FORWARD_CHARS) return value;
+  return `${serialized.slice(0, MAX_FORWARD_CHARS)}… [${serialized.length - MAX_FORWARD_CHARS} more chars elided]`;
+}
+
 function mapChildEvent(
   label: string,
   childSessionId: SessionId,
@@ -154,8 +180,12 @@ function mapChildEvent(
     case 'tool_result':
       payload.callId = String(childEvt.callId);
       payload.ok = childEvt.ok;
-      if (childEvt.ok) payload.output = childEvt.output;
-      else payload.error = childEvt.error;
+      // Child tool outputs are `unknown` and unbounded (a child Read/Bash can
+      // return multi-MB blobs). Forwarding them verbatim copies the full payload
+      // into the in-memory parent log too — doubling memory/persistence cost and
+      // multiplying it under deep nesting. The TUI only needs a preview, so cap it.
+      if (childEvt.ok) payload.output = truncateForward(childEvt.output);
+      else payload.error = truncateForward(childEvt.error);
       return { subtype: 'subagent_tool_result', payload };
     case 'error':
       payload.kind = childEvt.kind;

package/src/subagents/registry.test.ts

@@ -0,0 +1,106 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { asSessionId } from '@moxxy/sdk';
+import type { SessionRuntime } from '../session-runtime.js';
+import {
+  claimRetainedChild,
+  clearRetainedChildren,
+  getRetainedChild,
+  registerRetainedChild,
+  releaseRetainedChild,
+  unclaimRetainedChild,
+  type RetainedChildSession,
+} from './registry.js';
+
+// Minimal retained entry — the registry only reads childSessionId, parentSession.id,
+// and retainedAt; the rest can be cast through `unknown`.
+function makeEntry(id: string, parentId = 'parent'): RetainedChildSession {
+  return {
+    childSessionId: asSessionId(id),
+    parentSession: { id: asSessionId(parentId) } as unknown as SessionRuntime,
+  } as unknown as RetainedChildSession;
+}
+
+afterEach(() => {
+  clearRetainedChildren();
+  vi.useRealTimers();
+});
+
+describe('retained-child registry hardening', () => {
+  it('claim removes the entry and marks it busy so a racing claim cannot double-drive it', () => {
+    const id = asSessionId('c1');
+    registerRetainedChild(makeEntry('c1'));
+
+    const first = claimRetainedChild(id);
+    expect(first).toBeDefined();
+    // Entry is gone from the registry the instant it is claimed.
+    expect(getRetainedChild(id)).toBeUndefined();
+    // A racing claim for the same id finds nothing (and is also blocked by busy).
+    expect(claimRetainedChild(id)).toBeUndefined();
+
+    unclaimRetainedChild(id);
+    expect(claimRetainedChild(id)).toBeUndefined(); // still gone from registry
+  });
+
+  it('release while a claim is in flight drops the busy marker without resurrecting the entry', () => {
+    const id = asSessionId('c2');
+    registerRetainedChild(makeEntry('c2'));
+    expect(claimRetainedChild(id)).toBeDefined();
+    releaseRetainedChild(id); // racing release()
+    // Re-registering then claiming works again (busy was cleared).
+    registerRetainedChild(makeEntry('c2'));
+    expect(claimRetainedChild(id)).toBeDefined();
+  });
+
+  it('caps the number of retained children, evicting the oldest', () => {
+    for (let i = 0; i < 100; i++) registerRetainedChild(makeEntry(`k${i}`));
+    // The earliest entries must have been evicted; the latest survive.
+    expect(getRetainedChild(asSessionId('k0'))).toBeUndefined();
+    expect(getRetainedChild(asSessionId('k99'))).toBeDefined();
+    // Bounded: never more than the cap.
+    let live = 0;
+    for (let i = 0; i < 100; i++) if (getRetainedChild(asSessionId(`k${i}`))) live++;
+    expect(live).toBeLessThanOrEqual(64);
+  });
+
+  it('returns the entry evicted under the cap so the caller can warn the operator', () => {
+    // Fill to the cap, then one more — the registering call must hand back the
+    // oldest (k0) it dropped so run-child can emit a subagent_warning for it.
+    for (let i = 0; i < 64; i++) registerRetainedChild(makeEntry(`c${i}`));
+    const evicted = registerRetainedChild(makeEntry('overflow'));
+    expect(evicted.map((e) => String(e.childSessionId))).toContain('c0');
+    expect(getRetainedChild(asSessionId('c0'))).toBeUndefined();
+  });
+
+  it('returns TTL-expired entries it pruned on the next register', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+    registerRetainedChild(makeEntry('aged'));
+
+    vi.setSystemTime(31 * 60 * 1000);
+    const evicted = registerRetainedChild(makeEntry('newcomer'));
+    expect(evicted.map((e) => String(e.childSessionId))).toContain('aged');
+    expect(getRetainedChild(asSessionId('aged'))).toBeUndefined();
+  });
+
+  it('evicts a stale paused child after the TTL on the next register', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+    registerRetainedChild(makeEntry('stale'));
+    expect(getRetainedChild(asSessionId('stale'))).toBeDefined();
+
+    // Advance past the 30-minute TTL, then register a fresh child — that
+    // triggers pruning of the expired one.
+    vi.setSystemTime(31 * 60 * 1000);
+    registerRetainedChild(makeEntry('fresh'));
+    expect(getRetainedChild(asSessionId('stale'))).toBeUndefined();
+    expect(getRetainedChild(asSessionId('fresh'))).toBeDefined();
+  });
+
+  it('clearRetainedChildren scopes to the owning session', () => {
+    registerRetainedChild(makeEntry('a1', 'sessA'));
+    registerRetainedChild(makeEntry('b1', 'sessB'));
+    clearRetainedChildren(asSessionId('sessA'));
+    expect(getRetainedChild(asSessionId('a1'))).toBeUndefined();
+    expect(getRetainedChild(asSessionId('b1'))).toBeDefined();
+  });
+});

package/src/subagents/registry.ts

@@ -28,20 +28,93 @@ export interface RetainedChildSession {
   readonly strategyName: string;
   readonly parentSession: SessionRuntime;
   readonly parentTurnId: TurnId;
+  /** Cumulative provider token cost across this retained session's turns. */
+  tokensUsed?: number;
+  /** Wall-clock ms when the entry was (re)registered — drives TTL eviction. */
+  readonly retainedAt?: number;
 }
 
+/**
+ * Cap the number of live retained children. Each entry pins a full EventLog +
+ * ModeContext (provider, tool registry, plugin host, signal); an `awaitInput`
+ * child whose resume never arrives would otherwise leak for the life of a
+ * long-lived in-process runner. When the cap is exceeded the oldest entry is
+ * evicted (its `continue()` will then fail with "no retained subagent session").
+ */
+const MAX_RETAINED = 64;
+/** Evict a paused child this long after registration if never resumed. */
+const RETAIN_TTL_MS = 30 * 60 * 1000;
+
 const retained = new Map<string, RetainedChildSession>();
+/** Child session ids with a `continue()` currently in flight (claim-then-run). */
+const busy = new Set<string>();
 
-export function registerRetainedChild(session: RetainedChildSession): void {
-  retained.set(String(session.childSessionId), session);
+/** Drop entries past their TTL and return them so the caller can warn. */
+function pruneExpired(now: number): RetainedChildSession[] {
+  const expired: RetainedChildSession[] = [];
+  for (const [id, entry] of retained) {
+    if (entry.retainedAt !== undefined && now - entry.retainedAt >= RETAIN_TTL_MS) {
+      retained.delete(id);
+      expired.push(entry);
+    }
+  }
+  return expired;
+}
+
+/**
+ * Register (or re-register) a retained child. Returns the entries DROPPED by
+ * this call — TTL-expired children plus any evicted to make room under the cap —
+ * so the caller can surface a `subagent_warning` for each (a paused `awaitInput`
+ * child whose `continue()` will now fail with "no retained subagent session").
+ * The registry has no SessionRuntime handle of its own, so it can't emit.
+ */
+export function registerRetainedChild(session: RetainedChildSession): RetainedChildSession[] {
+  const now = Date.now();
+  const evicted = pruneExpired(now);
+  const id = String(session.childSessionId);
+  // Map preserves insertion order, so the first key is the oldest. Evict
+  // oldest until we have room for this one (Map.set on an existing id is an
+  // update, not an insert, so don't count a re-register against the cap).
+  while (retained.size >= MAX_RETAINED && !retained.has(id)) {
+    const [oldestId, oldestEntry] = retained.entries().next().value ?? [];
+    if (oldestId === undefined) break;
+    retained.delete(oldestId);
+    if (oldestEntry) evicted.push(oldestEntry);
+  }
+  retained.set(id, { ...session, retainedAt: now });
+  return evicted;
 }
 
 export function getRetainedChild(childSessionId: SessionId): RetainedChildSession | undefined {
   return retained.get(String(childSessionId));
 }
 
+/**
+ * Atomically claim a retained child for a `continue()` turn: remove it 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 concurrently. Returns `undefined` if the id is unknown or
+ * already in flight.
+ */
+export function claimRetainedChild(childSessionId: SessionId): RetainedChildSession | undefined {
+  const id = String(childSessionId);
+  if (busy.has(id)) return undefined;
+  const entry = retained.get(id);
+  if (!entry) return undefined;
+  retained.delete(id);
+  busy.add(id);
+  return entry;
+}
+
+/** Release a claim taken by {@link claimRetainedChild} (after the turn settles). */
+export function unclaimRetainedChild(childSessionId: SessionId): void {
+  busy.delete(String(childSessionId));
+}
+
 export function releaseRetainedChild(childSessionId: SessionId): void {
-  retained.delete(String(childSessionId));
+  const id = String(childSessionId);
+  retained.delete(id);
+  busy.delete(id);
 }
 
 /**
@@ -53,6 +126,7 @@ export function releaseRetainedChild(childSessionId: SessionId): void {
 export function clearRetainedChildren(parentSessionId?: SessionId): void {
   if (parentSessionId === undefined) {
     retained.clear();
+    busy.clear();
     return;
   }
   const target = String(parentSessionId);

package/src/subagents/run-child.test.ts

@@ -1,8 +1,14 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import type { ModeContext, ModeDef, MoxxyEvent, ProviderDef } from '@moxxy/sdk';
 import { defineMode, defineProvider, definePlugin } from '@moxxy/sdk';
 import { Session } from '../session.js';
-import { runChildTurn, type SubagentRuntime } from './run-child.js';
+import {
+  continueChildTurn,
+  createSubagentSpawner,
+  runChildTurn,
+  type SubagentRuntime,
+} from './run-child.js';
+import { clearRetainedChildren } from './registry.js';
 
 // A mode that reports the model it was handed — lets tests observe the
 // child's EFFECTIVE model through the returned result text.
@@ -183,3 +189,158 @@ describe('runChildTurn model resolution', () => {
     expect(result.text).toBe('cheap-model');
   });
 });
+
+// A mode that runs instantly on its FIRST invocation but blocks on an external
+// gate on every later turn — lets a test hold a continue() turn mid-flight while
+// a second continue() races it (without hanging the initial spawn).
+function makeGatedMode(gate: Promise<void>): ModeDef {
+  let calls = 0;
+  return defineMode({
+    name: 'gated',
+    run: async function* (ctx: ModeContext): AsyncIterable<MoxxyEvent> {
+      calls += 1;
+      if (calls > 1) await gate;
+      await ctx.emit({
+        type: 'assistant_message',
+        sessionId: ctx.sessionId,
+        turnId: ctx.turnId,
+        source: 'assistant',
+        content: 'done',
+        stopReason: 'end_turn',
+      });
+    },
+  });
+}
+
+describe('spawnAll per-child degradation', () => {
+  it('isolates one child setup throw — siblings still resolve, batch never rejects', async () => {
+    const session = buildSession(['parent-model']);
+    const rt = buildRuntime(session, 'parent-model');
+    const spawner = createSubagentSpawner(rt);
+
+    // Force a PRE-`try` setup throw for exactly the SECOND child: buildChildContext
+    // calls appContext() for every child, so throw on its second invocation. With
+    // Promise.all this would reject the whole batch and orphan the first (still
+    // running) child's promise → an unhandledRejection; with allSettled it must
+    // degrade to one error-bearing result while the sibling succeeds.
+    const realAppContext = session.appContext.bind(session);
+    let appCtxCalls = 0;
+    vi.spyOn(session, 'appContext').mockImplementation(() => {
+      appCtxCalls += 1;
+      if (appCtxCalls === 2) throw new Error('boom: provider config gone');
+      return realAppContext();
+    });
+
+    const results = await spawner.spawnAll([
+      { prompt: 'echo', mode: 'echo-model', label: 'good' },
+      { prompt: 'echo', mode: 'echo-model', label: 'doomed' },
+    ]);
+
+    // The batch resolves (never rejects) with one result PER spec, in input order.
+    expect(results).toHaveLength(2);
+    expect(results.map((r) => r.label)).toEqual(['good', 'doomed']);
+    // Exactly one child degraded to an error-bearing result; the sibling succeeded.
+    const errored = results.filter((r) => r.stopReason === 'error');
+    const ok = results.filter((r) => r.stopReason === 'end_turn');
+    expect(errored).toHaveLength(1);
+    expect(ok).toHaveLength(1);
+    expect(errored[0]!.error?.message).toContain('boom');
+    expect(ok[0]!.text).toBe('parent-model');
+    vi.restoreAllMocks();
+  });
+
+  it('a rejecting child never aborts its siblings; per-child failure carries the spec label', async () => {
+    const session = buildSession(['parent-model']);
+    const rt = buildRuntime(session, 'parent-model');
+    const spawner = createSubagentSpawner(rt);
+
+    // Make the THIRD child's runChildTurn reject outright (a pre-`try` setup throw
+    // inside buildChildContext) so the promise actually rejects rather than being
+    // self-degraded. With Promise.all the first rejection short-circuits the batch
+    // and orphans the two still-running siblings; Promise.allSettled must let every
+    // sibling finish and turn the rejection into one error-bearing result.
+    const realAppContext = session.appContext.bind(session);
+    let appCtxCalls = 0;
+    vi.spyOn(session, 'appContext').mockImplementation(() => {
+      appCtxCalls += 1;
+      if (appCtxCalls === 3) throw new Error('boom: setup exploded');
+      return realAppContext();
+    });
+
+    const results = await spawner.spawnAll([
+      { prompt: 'a', mode: 'echo-model', label: 'one' },
+      { prompt: 'b', mode: 'echo-model', label: 'two' },
+      { prompt: 'c', mode: 'echo-model', label: 'three' },
+    ]);
+
+    // The batch resolves (never rejects) with one result per spec, in input order.
+    expect(results.map((r) => r.label)).toEqual(['one', 'two', 'three']);
+    // The two non-throwing siblings completed normally...
+    expect(results[0]!.stopReason).toBe('end_turn');
+    expect(results[0]!.text).toBe('parent-model');
+    expect(results[1]!.stopReason).toBe('end_turn');
+    expect(results[1]!.text).toBe('parent-model');
+    // ...and only the doomed child degraded to a per-child failure that keeps its label.
+    expect(results[2]!.stopReason).toBe('error');
+    expect(results[2]!.label).toBe('three');
+    expect(results[2]!.error?.message).toContain('boom: setup exploded');
+    vi.restoreAllMocks();
+  });
+
+  it('returns one result per spec in input order on the all-success path', async () => {
+    const session = buildSession(['parent-model']);
+    const rt = buildRuntime(session, 'parent-model');
+    const spawner = createSubagentSpawner(rt);
+
+    const results = await spawner.spawnAll([
+      { prompt: 'a', mode: 'echo-model', label: 'one' },
+      { prompt: 'b', mode: 'echo-model', label: 'two' },
+      { prompt: 'c', mode: 'echo-model', label: 'three' },
+    ]);
+
+    expect(results.map((r) => r.label)).toEqual(['one', 'two', 'three']);
+    expect(results.every((r) => r.stopReason === 'end_turn')).toBe(true);
+  });
+});
+
+describe('continueChildTurn re-entrancy', () => {
+  it('rejects a concurrent continue() for the same retained child (claim-then-run)', async () => {
+    let openGate!: () => void;
+    const gate = new Promise<void>((resolve) => {
+      openGate = resolve;
+    });
+    const session = new Session({ cwd: '/tmp', silent: true });
+    session.pluginHost.registerStatic(
+      definePlugin({
+        name: 'gated-test',
+        version: '0.0.0',
+        providers: [makeProvider(['m'])],
+        modes: [makeGatedMode(gate)],
+      }),
+    );
+    session.providers.setActive('listed');
+    session.modes.setActive('gated');
+
+    const rt = buildRuntime(session, 'm');
+    const first = await runChildTurn({
+      rt,
+      spec: { prompt: 'go', mode: 'gated', retainSession: true },
+      retainSession: true,
+    });
+    const childId = first.childSessionId;
+
+    // Start the first continue (blocks inside the gated mode), then race a
+    // second continue for the same id before the first settles.
+    const p1 = continueChildTurn({ childSessionId: childId, prompt: 'again' });
+    // The entry is claimed synchronously, so the second continue must fail fast.
+    await expect(
+      continueChildTurn({ childSessionId: childId, prompt: 'race' }),
+    ).rejects.toThrow(/no retained subagent session/);
+
+    openGate();
+    const r1 = await p1;
+    expect(r1.text).toBe('done');
+
+    clearRetainedChildren(session.id);
+  });
+});