fix(tests): Address Warden runtime feedback

Tighten snapshot harness error-state checks, keep error envelopes compatible with the error schema, and simplify the response helper cleanup Warden flagged.

Co-Authored-By: OpenAI Codex <noreply@openai.com>

Author: cameroncooke

CHANGELOG.md

@@ -4,7 +4,7 @@
 
 ### Added
 
-- Added `nextSteps` hint lines to MCP `structuredContent` and CLI `--output json` envelopes so agents can consume follow-up actions without scraping text. CLI JSON renders shell command lines; MCP structured content renders MCP tool-call hints.
+- Added `nextSteps` hint lines to MCP `structuredContent` and CLI `--output json` envelopes so agents can consume follow-up actions without scraping text. CLI JSON renders shell command lines; MCP structured content renders MCP tool-call hints. Structured result schemas that include `nextSteps` now use schema version 2; existing version 1 schema files remain available for current validators.
 
 ## [2.5.2]
 

src/snapshot-tests/__tests__/json-harness-error-state.test.ts

@@ -23,6 +23,12 @@ describe('JSON snapshot harness error state', () => {
     expect(resolveCliJsonSnapshotErrorState(1, errorEnvelope, 'tool')).toBe(true);
   });
 
+  it('rejects null CLI process status', () => {
+    expect(() => resolveCliJsonSnapshotErrorState(null, successEnvelope, 'tool')).toThrow(
+      'CLI process exit status was null for tool; the process may have timed out or been killed by a signal.',
+    );
+  });
+
   it('rejects CLI process status and envelope.didError disagreement', () => {
     expect(() => resolveCliJsonSnapshotErrorState(1, successEnvelope, 'tool')).toThrow(
       'CLI process exit status (1) disagrees with envelope.didError (false)',
@@ -44,5 +50,8 @@ describe('JSON snapshot harness error state', () => {
     expect(() => resolveMcpSnapshotErrorState(false, true, 'tool')).toThrow(
       'MCP result.isError (false) disagrees with structuredContent.didError (true)',
     );
+    expect(() => resolveMcpSnapshotErrorState(undefined, true, 'tool')).toThrow(
+      'MCP result.isError (undefined) disagrees with structuredContent.didError (true)',
+    );
   });
 });

src/snapshot-tests/harness.ts

@@ -73,14 +73,20 @@ export function resolveCliJsonSnapshotErrorState(
   envelope: NonNullable<SnapshotResult['structuredEnvelope']>,
   label: string,
 ): boolean {
+  if (status === null) {
+    throw new Error(
+      `CLI process exit status was null for ${label}; the process may have timed out or been killed by a signal.`,
+    );
+  }
+
   const processDidError = status !== 0;
   if (processDidError !== envelope.didError) {
     throw new Error(
       `${label}: CLI process exit status (${status ?? 'null'}) disagrees with envelope.didError (${envelope.didError}).`,
     );
   }
 
-  return processDidError || envelope.didError;
+  return processDidError;
 }
 
 export async function createSnapshotHarness(

src/snapshot-tests/json-normalize.ts

@@ -5,10 +5,14 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object';
 }
 
+function normalizeBaseString(value: string): string {
+  const normalized = normalizeSnapshotOutput(value.replace(/\u00A0/g, ' '));
+  return normalized.endsWith('\n') ? normalized.slice(0, -1) : normalized;
+}
+
 function normalizeString(value: string, key?: string, path: string[] = []): string {
   const parentKey = path.at(-2);
-  const normalized = normalizeSnapshotOutput(value.replace(/\u00A0/g, ' '));
-  let result = normalized.endsWith('\n') ? normalized.slice(0, -1) : normalized;
+  let result = normalizeBaseString(value);
 
   if (parentKey === 'stderr') {
     result = result.replace(/^\[\d+\/\d+\] /, '[<STEP>] ');
@@ -131,10 +135,8 @@ function normalizeBuildSettingsEntryValue(key: string, value: string): string {
     case 'TARGET_DEVICE_OS_VERSION':
     case 'ASSETCATALOG_FILTER_FOR_DEVICE_OS_VERSION':
       return '<OS_VERSION>';
-    default: {
-      const normalized = normalizeSnapshotOutput(value.replace(/\u00A0/g, ' '));
-      return normalized.endsWith('\n') ? normalized.slice(0, -1) : normalized;
-    }
+    default:
+      return normalizeBaseString(value);
   }
 }
 
@@ -252,10 +254,13 @@ export function normalizeStructuredEnvelope(
   ) as StructuredOutputEnvelope<unknown>;
 }
 
+const FRAME_OBJECT_REGEX =
+  /"frame": \{\n\s+"y": (?<y>\d+(?:\.\d+)?),\n\s+"x": (?<x>\d+(?:\.\d+)?),\n\s+"width": (?<width>\d+(?:\.\d+)?),\n\s+"height": (?<height>\d+(?:\.\d+)?)\n\s+\}/g;
+
 function compactFrameObjects(json: string): string {
   return json.replace(
-    /"frame": \{\n\s+"y": (\d+(?:\.\d+)?),\n\s+"x": (\d+(?:\.\d+)?),\n\s+"width": (\d+(?:\.\d+)?),\n\s+"height": (\d+(?:\.\d+)?)\n\s+\}/g,
-    '"frame": { "x": $2, "y": $1, "width": $3, "height": $4 }',
+    FRAME_OBJECT_REGEX,
+    '"frame": { "x": $<x>, "y": $<y>, "width": $<width>, "height": $<height> }',
   );
 }
 

src/snapshot-tests/mcp-harness.ts

@@ -94,11 +94,11 @@ export function resolveMcpSnapshotErrorState(
   const didTransportError = transportDidError ?? false;
   if (envelopeDidError !== undefined && didTransportError !== envelopeDidError) {
     throw new Error(
-      `MCP result.isError (${didTransportError}) disagrees with structuredContent.didError (${envelopeDidError}) for ${label}.`,
+      `MCP result.isError (${String(transportDidError)}) disagrees with structuredContent.didError (${envelopeDidError}) for ${label}.`,
     );
   }
 
-  return didTransportError || envelopeDidError === true;
+  return didTransportError;
 }
 
 export async function createMcpSnapshotHarness(

src/snapshot-tests/normalize.ts

@@ -54,6 +54,7 @@ const BUILD_SETTINGS_GROUP_REGEX = /^(\s*(?:ALTERNATE_GROUP|GROUP|INSTALL_GROUP)
 const BUILD_SETTINGS_GID_REGEX = /^(\s*GID = )\d+$/gm;
 const SDK_PATH_REGEX =
   /^(\s*(?:CORRESPONDING_SIMULATOR_SDK_DIR|SDKROOT|SDK_DIR(?:_[A-Za-z0-9_]+)?) = ).+$/gm;
+const SDK_DIR_PLACEHOLDER_KEY_REGEX = /^(\s*)SDK_DIR_[A-Za-z0-9_]+ = <SDK_PATH>$/gm;
 const SDK_NAME_REGEX = /^(\s*(?:CORRESPONDING_SIMULATOR_SDK_NAME|SDK_NAMES?) = ).+$/gm;
 const SDK_BUILD_VERSION_REGEX =
   /^(\s*(?:PLATFORM_PRODUCT_BUILD_VERSION|SDK_PRODUCT_BUILD_VERSION|MAC_OS_X_PRODUCT_BUILD_VERSION) = ).+$/gm;
@@ -230,7 +231,7 @@ export function normalizeSnapshotOutput(text: string): string {
   normalized = normalized.replace(BUILD_SETTINGS_GID_REGEX, '$1<GID>');
   normalized = normalized.replace(SDK_PATH_REGEX, '$1<SDK_PATH>');
   normalized = normalized.replace(
-    /^(\s*)SDK_DIR_[A-Za-z0-9_]+ = <SDK_PATH>$/gm,
+    SDK_DIR_PLACEHOLDER_KEY_REGEX,
     '$1SDK_DIR_<SDK_NAME> = <SDK_PATH>',
   );
   normalized = normalized.replace(SDK_NAME_REGEX, '$1<SDK_NAME>');

src/utils/__tests__/structured-output-envelope.test.ts

@@ -71,6 +71,33 @@ describe('toStructuredEnvelope', () => {
     ).toEqual(expectedEnvelope);
   });
 
+  it('does not serialize next steps on error envelopes because the error schema has no nextSteps field', () => {
+    const result: BuildResultDomainResult = {
+      kind: 'build-result',
+      didError: true,
+      error: 'Build failed',
+    };
+
+    expect(
+      toStructuredEnvelope(result, 'xcodebuildmcp.output.error', '1', {
+        nextSteps: [
+          {
+            label: 'Retry build',
+            cliTool: 'build',
+            workflow: 'project',
+            params: { scheme: 'CalculatorApp' },
+          },
+        ],
+      }),
+    ).toEqual({
+      schema: 'xcodebuildmcp.output.error',
+      schemaVersion: '1',
+      didError: true,
+      error: 'Build failed',
+      data: null,
+    });
+  });
+
   it('serializes next steps as rendered CLI command lines by default sorted by priority', () => {
     const result: DeviceListDomainResult = {
       kind: 'device-list',

src/utils/renderers/cli-text-renderer.ts

@@ -1,3 +1,4 @@
+import type { RuntimeKind } from '../../runtime/types.ts';
 import type { NextStep } from '../../types/common.ts';
 import type { StructuredToolOutput } from '../../rendering/types.ts';
 import type { FilePathRenderStyle } from '../runtime-config-types.ts';
@@ -86,7 +87,7 @@ export interface CliTextTranscriptInput {
   items?: readonly AnyFragment[];
   structuredOutput?: StructuredToolOutput;
   nextSteps?: readonly NextStep[];
-  nextStepsRuntime?: 'cli' | 'daemon' | 'mcp';
+  nextStepsRuntime?: RuntimeKind;
   suppressWarnings?: boolean;
   showTestTiming?: boolean;
   filePathRenderStyle?: FilePathRenderStyle;
@@ -127,7 +128,7 @@ function createCliTextProcessor(options: CliTextProcessorOptions): TranscriptRen
   let sawIncomingSummaryEvent = false;
   let sawIncomingNonSummaryEvent = false;
   let nextSteps: readonly NextStep[] = [];
-  let nextStepsRuntime: 'cli' | 'daemon' | 'mcp' | undefined;
+  let nextStepsRuntime: RuntimeKind | undefined;
   let sawProgressNextSteps = false;
   let lastRenderedTestProgressKey: string | null = null;
   let pendingStreamedSummary: SummaryTextBlock | null = null;
@@ -424,7 +425,7 @@ function createCliTextProcessor(options: CliTextProcessorOptions): TranscriptRen
       structuredOutput = output;
     },
 
-    setNextSteps(steps: readonly NextStep[], runtime: 'cli' | 'daemon' | 'mcp'): void {
+    setNextSteps(steps: readonly NextStep[], runtime: RuntimeKind): void {
       nextSteps = [...steps];
       nextStepsRuntime = runtime;
     },

src/utils/responses/__tests__/next-steps-renderer.test.ts

@@ -185,6 +185,20 @@ describe('next-steps-renderer', () => {
       expect(result).toBe('Open the Simulator app: open_sim()');
     });
 
+    it('trims label whitespace before rendering command steps', () => {
+      const step: NextStep = {
+        tool: 'boot_sim',
+        cliTool: 'boot',
+        workflow: 'simulator',
+        label: '  Boot simulator  ',
+        params: { simulatorId: 'SIM-1' },
+      };
+
+      expect(renderNextStep(step, 'cli')).toBe(
+        'Boot simulator: xcodebuildmcp simulator boot --simulator-id SIM-1',
+      );
+    });
+
     it('should render label-only step as plain text', () => {
       const step: NextStep = {
         label: 'Verify layout visually before continuing',

src/utils/responses/next-step-formatting.ts

@@ -10,7 +10,8 @@ export interface FormatNextStepOptions {
 const SHELL_SAFE_UNQUOTED_ARG = /^[A-Za-z0-9_@%+=:,./~-]+$/;
 
 function resolveLabel(step: NextStep): string {
-  if (step.label?.trim()) return step.label;
+  const label = step.label?.trim();
+  if (label) return label;
   if (step.tool) return step.tool;
   if (step.cliTool) return step.cliTool;
   return 'Next action';
@@ -76,11 +77,12 @@ export function formatNextStep(step: NextStep, options: FormatNextStepOptions):
   const formatted =
     options.runtime === 'cli' ? formatNextStepForCli(step) : formatNextStepForMcp(step);
 
-  if (!step.label || formatted === step.label) {
+  const label = resolveLabel(step);
+  if (!step.label?.trim() || formatted === label) {
     return formatted;
   }
 
-  return `${step.label}: ${formatted}`;
+  return `${label}: ${formatted}`;
 }
 
 export function serializeNextSteps(