V48 Gate 3 (implementation-only): a schema-valid final stitch is a success, and debug stops actually stop

Two Generation-primitive corrections surfaced by the SynthesizeAssetPacks
sanity sweep:

- StitchUntilComplete validated only at the top of each loop iteration, so
  the attempt that reached maxStitches was generated, paid for, and then
  discarded by the unconditional exceeded throw even when schema-valid.
  The exceeded guard now re-validates the final attempt first.
- The BITCODE_DEBUG_STOP_AFTER_FIRST_{REASON,STRUCTURED_OUTPUT} stops were
  double-dead: the intentional stop throw was swallowed by its own guard
  try/catch, and the structured-output predicate required a 'gen-2' path
  segment that no longer exists post-thricified (the structured substep
  runs under gen-0/seq-2). The throw now escapes and the predicate matches
  the real gen-0 pathing.

Regression-pinned in stitch-final-attempt-and-debug-stop.test.ts (5 tests).
agent-generics 9 suites / 21 tests green; tsc clean; asset-pack 45/227 green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: geraldarthurdavis

packages/agent-generics/src/__tests__/stitch-final-attempt-and-debug-stop.test.ts

@@ -0,0 +1,96 @@
+// @ts-nocheck
+import { z } from 'zod';
+import { Execution } from '@bitcode/execution-generics';
+import { factoryStitchUntilComplete, factoryReason, factoryStructuredOutput } from '../substeps/factories';
+
+const schema = z.object({ value: z.string() });
+
+describe('StitchUntilComplete final attempt', () => {
+  it('returns a schema-valid final stitch instead of discarding it as exceeded', async () => {
+    let calls = 0;
+    const gen = async () => {
+      calls++;
+      return calls >= 5 ? { value: 'complete' } : { partial: true };
+    };
+    const stitch = factoryStitchUntilComplete([gen], schema);
+    const result = await stitch({ partial: true }, new Execution('root'));
+
+    expect(calls).toBe(5);
+    expect(result.finalOutput).toEqual({ value: 'complete' });
+  });
+
+  it('still fails closed when every stitch attempt stays invalid', async () => {
+    let calls = 0;
+    const gen = async () => {
+      calls++;
+      return { partial: true };
+    };
+    const stitch = factoryStitchUntilComplete([gen], schema);
+
+    await expect(stitch({ partial: true }, new Execution('root'))).rejects.toThrow(
+      /exceeded maximum stitch attempts/
+    );
+    expect(calls).toBe(5);
+  });
+
+  it('returns valid input without any stitch generation', async () => {
+    let calls = 0;
+    const gen = async () => {
+      calls++;
+      return { value: 'stitched' };
+    };
+    const stitch = factoryStitchUntilComplete([gen], schema);
+    const result = await stitch({ value: 'already complete' }, new Execution('root'));
+
+    expect(calls).toBe(0);
+    expect(result.finalOutput).toEqual({ value: 'already complete' });
+  });
+});
+
+describe('debug stop escapes the substep', () => {
+  const llms = (content: any) => ({
+    getDefaultLLM: () => async () => ({
+      content: typeof content === 'string' ? content : JSON.stringify(content),
+      usage: { totalTokens: 5 },
+      metadata: { provider: 'test', model: 'test-model' },
+    }),
+  });
+
+  const nestedDebugPathExecution = () => {
+    const root = new Execution('agent-root');
+    const nested = root.child('plan').child('failsafe:prepare_concise_context').child('gen-0');
+    (nested as any).llms = llms({
+      analysis: 'a',
+      steps: ['s'],
+      conclusion: 'c',
+      confidence: 0.9,
+    });
+    return nested;
+  };
+
+  afterEach(() => {
+    delete process.env.BITCODE_DEBUG_STOP_AFTER_FIRST_REASON;
+    delete process.env.BITCODE_DEBUG_STOP_AFTER_FIRST_STRUCTURED_OUTPUT;
+  });
+
+  it('BITCODE_DEBUG_STOP_AFTER_FIRST_REASON stops after the first reason generation', async () => {
+    process.env.BITCODE_DEBUG_STOP_AFTER_FIRST_REASON = '1';
+    const reason = factoryReason();
+
+    await expect(reason({ read: 'anything' }, nestedDebugPathExecution())).rejects.toThrow(
+      '__BITCODE_DEBUG_STOP_AFTER_FIRST_REASON__'
+    );
+  });
+
+  it('BITCODE_DEBUG_STOP_AFTER_FIRST_STRUCTURED_OUTPUT stops on the first structured output (gen-0 pathing)', async () => {
+    process.env.BITCODE_DEBUG_STOP_AFTER_FIRST_STRUCTURED_OUTPUT = '1';
+    const root = new Execution('agent-root');
+    const nested = root.child('plan').child('failsafe:prepare_concise_context').child('gen-0');
+    (nested as any).llms = llms({ value: 'ok' });
+    const structured = factoryStructuredOutput(schema);
+
+    await expect(structured({ context: 'anything' }, nested)).rejects.toThrow(
+      '__BITCODE_DEBUG_STOP_AFTER_FIRST_STRUCTURED_OUTPUT__'
+    );
+  });
+});

packages/agent-generics/src/diagnostics/instrumentation.ts

@@ -303,7 +303,9 @@ export function shouldDebugStopAfterFirstStructuredOutput(substepExec: Execution
     const pathArr = (substepExec as any).getPath?.() || [];
     const isPlanStep = pathArr.includes('plan');
     const inPrepareFailsafe = pathArr.some((p: string) => String(p).includes('prepare_concise_context'));
-    const isFirstStructured = pathArr.includes('gen-2');
+    // The structured_output substep runs inside the first thricified
+    // generation node (gen-0); the sequence gate above already pins the kind.
+    const isFirstStructured = pathArr.includes('gen-0');
     const ctx = getCtx(substepExec);
     const agentFilter = process?.env?.BITCODE_DEBUG_STOP_AGENT_FILTER;
     const agentMatches = agentFilter ? String(ctx.agentName || '').includes(String(agentFilter)) : true;

packages/agent-generics/src/substeps/factories.ts

@@ -290,20 +290,21 @@ function factoryLLMSubStep<TInput, TOutput>(
       try { substep.store('llm', 'provider', (output as any)?.metadata?.provider); } catch { }
       try { substep.store('llm', 'model', (output as any)?.metadata?.model); } catch { }
 
-      // Optional debug stop (centralized)
-      try {
-        if (shouldDebugStopAfterFirstReason(substep, String(sequence))) {
-          substep.store('debug', 'stop_after_first_reason', true);
-          throw new Error('__BITCODE_DEBUG_STOP_AFTER_FIRST_REASON__');
-        }
-      } catch { }
+      // Optional debug stop (centralized). Only the predicate is guarded —
+      // the stop throw itself must escape this substep.
+      let debugStopAfterFirstReason = false;
+      try { debugStopAfterFirstReason = shouldDebugStopAfterFirstReason(substep, String(sequence)); } catch { }
+      if (debugStopAfterFirstReason) {
+        try { substep.store('debug', 'stop_after_first_reason', true); } catch { }
+        throw new Error('__BITCODE_DEBUG_STOP_AFTER_FIRST_REASON__');
+      }
 
-      try {
-        if (shouldDebugStopAfterFirstStructuredOutput(substep, String(sequence))) {
-          substep.store('debug', 'stop_after_first_structured_output', true);
-          throw new Error('__BITCODE_DEBUG_STOP_AFTER_FIRST_STRUCTURED_OUTPUT__');
-        }
-      } catch { }
+      let debugStopAfterFirstStructuredOutput = false;
+      try { debugStopAfterFirstStructuredOutput = shouldDebugStopAfterFirstStructuredOutput(substep, String(sequence)); } catch { }
+      if (debugStopAfterFirstStructuredOutput) {
+        try { substep.store('debug', 'stop_after_first_structured_output', true); } catch { }
+        throw new Error('__BITCODE_DEBUG_STOP_AFTER_FIRST_STRUCTURED_OUTPUT__');
+      }
 
       // 9. Parse output if parser provided
       if (config.parseOutput) {
@@ -628,11 +629,24 @@ export function factoryStitchUntilComplete<T>(
       }
     }
 
+    // The iteration that reaches maxStitches exits the loop before the
+    // top-of-loop validation can inspect its result, so re-validate here —
+    // a schema-valid final stitch is a success, not an exceeded failure.
+    const finalStitchValid = (() => {
+      if (!outputSchema || stitchCount < maxStitches) return false;
+      const candidate = (currentResult && (currentResult as any).output !== undefined)
+        ? (currentResult as any).output
+        : currentResult;
+      try { outputSchema.parse(candidate); return true; } catch { }
+      try { outputSchema.parse(currentResult); return true; } catch { }
+      return false;
+    })();
+
     failsafeExec.store('stitching', 'count', stitchCount);
-    try { logFailsafeEvent(execution, 'stitch-until-complete', { complete: true, stitchCount, exceeded: stitchCount >= maxStitches }); } catch { }
+    try { logFailsafeEvent(execution, 'stitch-until-complete', { complete: true, stitchCount, exceeded: stitchCount >= maxStitches && !finalStitchValid }); } catch { }
 
-    // Check if we exceeded max stitches
-    if (stitchCount >= maxStitches) {
+    // Check if we exceeded max stitches without ending on a valid output
+    if (stitchCount >= maxStitches && !finalStitchValid) {
       const error = new Error(
         `StitchUntilComplete exceeded maximum stitch attempts (${maxStitches}). ` +
         `Output may be incomplete or truncated. Consider increasing maxTokens or ` +