@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.84c56d87

package/src/resources/extensions/gsd/tests/pre-execution-checks.test.ts

@@ -21,6 +21,7 @@ import { join } from "node:path";
 import {
   extractPackageReferences,
   checkFilePathConsistency,
+  checkPlanningArtifactReferences,
   checkTaskOrdering,
   checkInterfaceContracts,
   checkVerificationCommands,
@@ -973,7 +974,12 @@ describe("runPreExecutionChecks", () => {
     }
   });
 
-  test("resolves .gsd metadata inputs from canonical project root in worktree mode (#5492)", async () => {
+  // Supersedes #5492: .gsd metadata inputs used to be accepted in worktree mode
+  // by resolving from the canonical project root. Task inputs are source files
+  // only (CONTEXT.md "Task Input") — planning artifacts are now blocked with a
+  // removal message regardless of where they resolve. The canonical-root
+  // resolution itself remains for merged-but-unsynced source files.
+  test("blocks .gsd metadata inputs even when resolvable from canonical project root in worktree mode", async () => {
     const projectRoot = join(tmpdir(), `pre-exec-project-root-${Date.now()}`);
     const worktreeRoot = join(tmpdir(), `pre-exec-worktree-root-${Date.now()}`);
     mkdirSync(join(projectRoot, ".gsd"), { recursive: true });
@@ -990,6 +996,35 @@ describe("runPreExecutionChecks", () => {
         }),
       ];
 
+      const result = await runPreExecutionChecks(tasks, worktreeRoot, {
+        canonicalProjectRoot: projectRoot,
+      });
+      assert.equal(result.status, "fail");
+      assert.equal(result.checks.length, 1);
+      assert.ok(result.checks[0].message.includes("preloaded as context"));
+    } finally {
+      rmSync(projectRoot, { recursive: true, force: true });
+      rmSync(worktreeRoot, { recursive: true, force: true });
+    }
+  });
+
+  test("resolves source-file inputs from canonical project root in worktree mode (#5492)", async () => {
+    const projectRoot = join(tmpdir(), `pre-exec-project-root-src-${Date.now()}`);
+    const worktreeRoot = join(tmpdir(), `pre-exec-worktree-root-src-${Date.now()}`);
+    mkdirSync(join(projectRoot, "src"), { recursive: true });
+    mkdirSync(worktreeRoot, { recursive: true });
+    writeFileSync(join(projectRoot, "src", "merged.ts"), "// merged upstream");
+
+    try {
+      const tasks = [
+        createTask({
+          id: "T01",
+          files: [],
+          inputs: ["src/merged.ts"],
+          expected_output: [],
+        }),
+      ];
+
       const result = await runPreExecutionChecks(tasks, worktreeRoot, {
         canonicalProjectRoot: projectRoot,
       });
@@ -2263,3 +2298,160 @@ describe("checkFilePathConsistency quote-wrapped annotation (#3747)", () => {
     );
   });
 });
+
+// ─── Planning Artifact Reference Tests ───────────────────────────────────────
+
+describe("checkPlanningArtifactReferences", () => {
+  function withTempDir(run: (tempDir: string) => void): void {
+    const tempDir = join(tmpdir(), `pre-exec-artifact-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(tempDir, { recursive: true });
+    try {
+      run(tempDir);
+    } finally {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  }
+
+  test("blocks .gsd/ paths in inputs even when the file exists", () => {
+    withTempDir((tempDir) => {
+      const artifactDir = join(tempDir, ".gsd", "milestones", "M001");
+      mkdirSync(artifactDir, { recursive: true });
+      writeFileSync(join(artifactDir, "M001-CONTEXT.md"), "# context");
+
+      const tasks = [
+        createTask({ id: "T01", inputs: [".gsd/milestones/M001/M001-CONTEXT.md"] }),
+      ];
+
+      const results = checkPlanningArtifactReferences(tasks, tempDir);
+      assert.equal(results.length, 1);
+      assert.equal(results[0].blocking, true);
+      assert.ok(results[0].message.includes("preloaded as context"));
+    });
+  });
+
+  test("blocks bare artifact names that do not resolve to a real file, with the truthful message", () => {
+    withTempDir((tempDir) => {
+      const tasks = [createTask({ id: "T01", inputs: ["M001-CONTEXT.md"] })];
+
+      const results = checkPlanningArtifactReferences(tasks, tempDir);
+      assert.equal(results.length, 1);
+      assert.ok(results[0].message.includes("preloaded as context"));
+      assert.ok(!results[0].message.includes("doesn't exist"));
+
+      // The consistency check must not double-report the same entry with the
+      // misleading "doesn't exist" message.
+      const consistency = checkFilePathConsistency(tasks, tempDir);
+      assert.deepEqual(consistency, []);
+    });
+  });
+
+  test("allows a bare artifact-style name that exists as a real source file", () => {
+    withTempDir((tempDir) => {
+      writeFileSync(join(tempDir, "M001-CONTEXT.md"), "# tracked source file");
+
+      const tasks = [createTask({ id: "T01", inputs: ["M001-CONTEXT.md"] })];
+      assert.deepEqual(checkPlanningArtifactReferences(tasks, tempDir), []);
+    });
+  });
+
+  test("leaves artifact-style names with directory components to the existence checks", () => {
+    withTempDir((tempDir) => {
+      const tasks = [createTask({ id: "T01", inputs: ["tests/fixtures/M001-CONTEXT.md"] })];
+
+      assert.deepEqual(checkPlanningArtifactReferences(tasks, tempDir), []);
+      const consistency = checkFilePathConsistency(tasks, tempDir);
+      assert.equal(consistency.length, 1);
+      assert.ok(consistency[0].message.includes("doesn't exist"));
+    });
+  });
+
+  test("blocks .planning/ and .audits/ paths in files", () => {
+    withTempDir((tempDir) => {
+      const tasks = [
+        createTask({ id: "T01", files: [".planning/codebase/STACK.md", ".audits/security.md"] }),
+      ];
+
+      const results = checkPlanningArtifactReferences(tasks, tempDir);
+      assert.equal(results.length, 2);
+      assert.ok(results.every((r) => r.blocking && r.message.includes("never task files")));
+    });
+  });
+
+  test("blocks .gsd/ paths in expectedOutput with the workflow-tools message and no ordering duplicate", () => {
+    withTempDir((tempDir) => {
+      const tasks = [
+        createTask({
+          id: "T01",
+          sequence: 0,
+          expected_output: [".gsd/milestones/M001/M001-SUMMARY.md"],
+        }),
+        createTask({
+          id: "T02",
+          sequence: 1,
+          inputs: [".gsd/milestones/M001/M001-SUMMARY.md"],
+        }),
+      ];
+
+      const results = checkPlanningArtifactReferences(tasks, tempDir);
+      assert.equal(results.length, 2);
+      const outputFinding = results.find((r) => r.message.includes("expectedOutput"));
+      assert.ok(outputFinding);
+      assert.ok(outputFinding.message.includes("written by workflow tools"));
+
+      assert.deepEqual(checkTaskOrdering(tasks, tempDir), []);
+    });
+  });
+
+  test("skips prose, sentinels, and runtime-only entries", () => {
+    withTempDir((tempDir) => {
+      const tasks = [
+        createTask({
+          id: "T01",
+          inputs: ["none", "Current enum shape", "server logs (runtime)"],
+        }),
+      ];
+
+      assert.deepEqual(checkPlanningArtifactReferences(tasks, tempDir), []);
+    });
+  });
+
+  test("runPreExecutionChecks surfaces artifact findings as blocking failures", async () => {
+    const tempDir = join(tmpdir(), `pre-exec-artifact-run-${Date.now()}`);
+    mkdirSync(tempDir, { recursive: true });
+    try {
+      const tasks = [createTask({ id: "T01", inputs: ["M001-CONTEXT.md"] })];
+      const result: PreExecutionResult = await runPreExecutionChecks(tasks, tempDir);
+      assert.equal(result.status, "fail");
+      assert.ok(
+        result.checks.some((c) => !c.passed && c.blocking && c.message.includes("preloaded as context")),
+      );
+    } finally {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  test("allows a bare artifact-style name that exists only at canonicalProjectRoot (not at worktree basePath)", () => {
+    withTempDir((canonicalRoot) => {
+      withTempDir((worktreeRoot) => {
+        writeFileSync(join(canonicalRoot, "M001-CONTEXT.md"), "# tracked source file");
+        const tasks = [createTask({ id: "T01", inputs: ["M001-CONTEXT.md"] })];
+        assert.deepEqual(
+          checkPlanningArtifactReferences(tasks, worktreeRoot, { canonicalProjectRoot: canonicalRoot }),
+          [],
+        );
+      });
+    });
+  });
+
+  test("blocks .GSD/ paths with mixed casing (case-insensitive metadata dir match)", () => {
+    withTempDir((tempDir) => {
+      const tasks = [
+        createTask({ id: "T01", inputs: [".GSD/milestones/M001/M001-CONTEXT.md"] }),
+      ];
+      const results = checkPlanningArtifactReferences(tasks, tempDir);
+      assert.equal(results.length, 1);
+      assert.equal(results[0].blocking, true);
+      assert.ok(results[0].message.includes("preloaded as context"));
+    });
+  });
+});

package/src/resources/extensions/gsd/tests/preferences-diagnostics.test.ts

@@ -0,0 +1,67 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  _resetPreferenceDiagnosticNotificationsForTests,
+  notifyPreferenceDiagnostics,
+} from "../preferences-diagnostics.ts";
+import { _resetParseWarningFlag } from "../preferences.ts";
+
+test("notifyPreferenceDiagnostics dedupes within a surface but re-surfaces across surfaces", (t) => {
+  const originalCwd = process.cwd();
+  const originalGsdHome = process.env.GSD_HOME;
+  const tempProject = mkdtempSync(join(tmpdir(), "gsd-prefs-notify-project-"));
+  const tempGsdHome = mkdtempSync(join(tmpdir(), "gsd-prefs-notify-home-"));
+  t.after(() => {
+    process.chdir(originalCwd);
+    if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = originalGsdHome;
+    rmSync(tempProject, { recursive: true, force: true });
+    rmSync(tempGsdHome, { recursive: true, force: true });
+    _resetPreferenceDiagnosticNotificationsForTests();
+    _resetParseWarningFlag();
+  });
+
+  mkdirSync(join(tempProject, ".gsd"), { recursive: true });
+  process.env.GSD_HOME = tempGsdHome;
+  process.chdir(tempProject);
+  _resetPreferenceDiagnosticNotificationsForTests();
+  _resetParseWarningFlag();
+
+  writeFileSync(
+    join(tempProject, ".gsd", "PREFERENCES.md"),
+    "---\nversion: 3\n---\n",
+    "utf-8",
+  );
+
+  const notifications: Array<{ message: string; type?: string }> = [];
+  const ctx = {
+    ui: {
+      notify(message: string, type?: "info" | "warning" | "error" | "success") {
+        notifications.push({ message, type });
+      },
+    },
+  };
+
+  assert.equal(
+    notifyPreferenceDiagnostics(ctx, tempProject, { surface: "session-start" }),
+    1,
+  );
+  assert.equal(
+    notifyPreferenceDiagnostics(ctx, tempProject, { surface: "session-start" }),
+    0,
+  );
+  assert.equal(
+    notifyPreferenceDiagnostics(ctx, tempProject, { surface: "auto-preflight" }),
+    1,
+  );
+  assert.equal(notifications.length, 2);
+  assert.equal(notifications[0]!.type, "error");
+  assert.match(notifications[0]!.message, /GSD project preferences error/);
+  assert.match(notifications[0]!.message, /unsupported version 3/);
+  assert.match(notifications[0]!.message, /Run \/gsd doctor for details/);
+  assert.equal(notifications[1]!.message, notifications[0]!.message);
+});

package/src/resources/extensions/gsd/tests/preferences.test.ts

@@ -26,6 +26,7 @@ import {
   renderPreferencesForSystemPrompt,
   _resetParseWarningFlag,
 } from "../preferences.ts";
+import { collectPreferenceDiagnostics, formatPreferenceDiagnostic } from "../preferences-diagnostics.ts";
 import { formatConfiguredModel, toPersistedModelId } from "../commands-prefs-wizard.ts";
 import { _resetLogs, peekLogs } from "../workflow-logger.ts";
 import type { GSDPreferences, GSDModelConfigV2, GSDPhaseModelConfig } from "../preferences.ts";
@@ -819,6 +820,188 @@ bad: [
   _resetLogs();
 });
 
+test("malformed global preferences load with a structured parse diagnostic", (t) => {
+  const originalGsdHome = process.env.GSD_HOME;
+  const tempGsdHome = mkdtempSync(join(tmpdir(), "gsd-prefs-diagnostic-home-"));
+  t.after(() => {
+    if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = originalGsdHome;
+    rmSync(tempGsdHome, { recursive: true, force: true });
+    _resetParseWarningFlag();
+    _resetLogs();
+  });
+
+  process.env.GSD_HOME = tempGsdHome;
+  _resetParseWarningFlag();
+  _resetLogs();
+  writeFileSync(
+    join(tempGsdHome, "PREFERENCES.md"),
+    [
+      "---",
+      "version: 1",
+      "models:",
+      "  validation:",
+      "    openrouter/deepseek/deepseek-v4-pro",
+      "    thinking: high",
+      "---",
+      "",
+    ].join("\n"),
+    "utf-8",
+  );
+
+  const loaded = loadGlobalGSDPreferences();
+  assert.notEqual(loaded, null);
+  assert.deepEqual(loaded!.preferences, {});
+  const diagnostic = loaded!.diagnostics?.[0];
+  assert.equal(diagnostic?.kind, "parse");
+  assert.equal(diagnostic?.severity, "error");
+  assert.equal(diagnostic?.line, 5);
+  assert.equal(diagnostic?.column, 5);
+  assert.equal(diagnostic?.ignored, true);
+  assert.match(diagnostic?.message ?? "", /Implicit keys need/);
+
+  const formatted = formatPreferenceDiagnostic(diagnostic!);
+  assert.match(formatted, /GSD global preferences error/);
+  assert.match(formatted, /line 5, column 5/);
+  assert.match(formatted, /Preferences from this file were ignored/);
+});
+
+test("project preference validation errors load with structured diagnostics", (t) => {
+  const originalCwd = process.cwd();
+  const originalGsdHome = process.env.GSD_HOME;
+  const tempProject = mkdtempSync(join(tmpdir(), "gsd-prefs-validation-project-"));
+  const tempGsdHome = mkdtempSync(join(tmpdir(), "gsd-prefs-validation-home-"));
+  t.after(() => {
+    process.chdir(originalCwd);
+    if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = originalGsdHome;
+    rmSync(tempProject, { recursive: true, force: true });
+    rmSync(tempGsdHome, { recursive: true, force: true });
+  });
+
+  mkdirSync(join(tempProject, ".gsd"), { recursive: true });
+  process.env.GSD_HOME = tempGsdHome;
+  process.chdir(tempProject);
+  writeFileSync(
+    join(tempProject, ".gsd", "PREFERENCES.md"),
+    "---\nversion: 3\n---\n",
+    "utf-8",
+  );
+
+  const loaded = loadProjectGSDPreferences(tempProject);
+  assert.notEqual(loaded, null);
+  assert.equal(loaded!.preferences.version, undefined);
+  const diagnostic = loaded!.diagnostics?.find((item) => item.kind === "validation");
+  assert.equal(diagnostic?.scope, "project");
+  assert.equal(diagnostic?.severity, "error");
+  assert.equal(diagnostic?.sanitized, true);
+  assert.match(diagnostic?.message ?? "", /unsupported version 3/);
+
+  const collected = collectPreferenceDiagnostics(tempProject);
+  assert.ok(
+    collected.some((item) => item.path === loaded!.path && item.message.includes("unsupported version 3")),
+    "collector should include project validation diagnostics",
+  );
+});
+
+test("malformed project preferences do not override effective global wrapper", (t) => {
+  const originalCwd = process.cwd();
+  const originalGsdHome = process.env.GSD_HOME;
+  const tempProject = mkdtempSync(join(tmpdir(), "gsd-prefs-effective-project-"));
+  const tempGsdHome = mkdtempSync(join(tmpdir(), "gsd-prefs-effective-home-"));
+  t.after(() => {
+    process.chdir(originalCwd);
+    if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = originalGsdHome;
+    rmSync(tempProject, { recursive: true, force: true });
+    rmSync(tempGsdHome, { recursive: true, force: true });
+    _resetParseWarningFlag();
+    _resetLogs();
+  });
+
+  mkdirSync(join(tempProject, ".gsd"), { recursive: true });
+  process.env.GSD_HOME = tempGsdHome;
+  process.chdir(tempProject);
+  _resetParseWarningFlag();
+  _resetLogs();
+
+  const globalPath = getGlobalGSDPreferencesPath();
+  const projectPath = getProjectGSDPreferencesPath(tempProject);
+  writeFileSync(globalPath, "---\nlanguage: Spanish\n---\n", "utf-8");
+  writeFileSync(
+    projectPath,
+    [
+      "---",
+      "version: 1",
+      "models:",
+      "  validation:",
+      "    openrouter/deepseek/deepseek-v4-pro",
+      "    thinking: high",
+      "---",
+      "",
+    ].join("\n"),
+    "utf-8",
+  );
+
+  const projectPrefs = loadProjectGSDPreferences(tempProject);
+  assert.equal(projectPrefs?.ignored, true);
+
+  const loaded = loadEffectiveGSDPreferences(tempProject);
+  assert.notEqual(loaded, null);
+  assert.equal(loaded!.path, globalPath);
+  assert.equal(loaded!.scope, "global");
+  assert.equal(loaded!.preferences.language, "Spanish");
+  assert.ok(
+    loaded!.diagnostics?.some((item) => item.path === projectPath && item.kind === "parse"),
+    "effective global preferences should carry malformed project diagnostics",
+  );
+});
+
+test("malformed global preferences: loadEffectiveGSDPreferences returns null without project file", (t) => {
+  const originalCwd = process.cwd();
+  const originalGsdHome = process.env.GSD_HOME;
+  const tempProject = mkdtempSync(join(tmpdir(), "gsd-prefs-effective-malformed-global-"));
+  const tempGsdHome = mkdtempSync(join(tmpdir(), "gsd-prefs-effective-malformed-home-"));
+  t.after(() => {
+    process.chdir(originalCwd);
+    if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = originalGsdHome;
+    rmSync(tempProject, { recursive: true, force: true });
+    rmSync(tempGsdHome, { recursive: true, force: true });
+    _resetParseWarningFlag();
+    _resetLogs();
+  });
+
+  process.env.GSD_HOME = tempGsdHome;
+  process.chdir(tempProject);
+  _resetParseWarningFlag();
+  _resetLogs();
+
+  const globalPath = getGlobalGSDPreferencesPath();
+  writeFileSync(
+    globalPath,
+    [
+      "---",
+      "version: 1",
+      "models:",
+      "  validation:",
+      "    openrouter/deepseek/deepseek-v4-pro",
+      "    thinking: high",
+      "---",
+      "",
+    ].join("\n"),
+    "utf-8",
+  );
+
+  const globalPrefs = loadGlobalGSDPreferences();
+  assert.equal(globalPrefs?.ignored, true, "malformed global should be marked ignored");
+
+  // Symmetric with malformed project + no global: effective result should be null,
+  // not an effective object with ignored:true leaking through.
+  const loaded = loadEffectiveGSDPreferences(tempProject);
+  assert.equal(loaded, null, "effective preferences should be null when only global file is malformed");
+});
+
 // ── Experimental preferences ─────────────────────────────────────────────────
 
 test("experimental.rtk: true is accepted and stored", () => {

package/src/resources/extensions/gsd/tests/prompt-contracts.test.ts

@@ -4,6 +4,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import {
   RUN_UAT_BROWSER_TOOL_NAMES,
+  resolveToolPresentationPlan,
   buildRunUatResultPresentation,
   buildRunUatPresentationForType,
   RUN_UAT_READ_ONLY_TOOL_NAMES,
@@ -179,6 +180,33 @@ test("browser-executable UAT presentation uses direct browser tools", () => {
   assert.ok(!presentation.presentedTools.some((toolName) => toolName.startsWith("mcp__gsd-browser__")));
 });
 
+test("run-uat presentation plans carry typed tool-surface snapshots", () => {
+  const plan = resolveToolPresentationPlan({
+    phase: "run-uat",
+    surface: "mcp",
+    workflowMcpServerName: "gsd-workflow",
+    availableToolNames: [
+      "gsd_uat_exec",
+      "gsd_uat_result_save",
+      "read",
+    ],
+    includeBrowserTools: [],
+  });
+
+  assert.equal(plan.toolSurface.source, "presentation-plan");
+  assert.equal(plan.toolSurface.phase, "run-uat");
+  assert.deepEqual(plan.toolSurface.scopedToolNames, [
+    "gsd_uat_exec",
+    "gsd_uat_result_save",
+    "read",
+  ]);
+  assert.deepEqual(plan.toolSurface.presentedToolNames, [
+    "mcp__gsd-workflow__gsd_uat_exec",
+    "mcp__gsd-workflow__gsd_uat_result_save",
+    "read",
+  ]);
+});
+
 test("live-runtime and mixed UAT presentations also surface browser tools", () => {
   // Regression (M001/S03): the run-uat prompt tells live-runtime and mixed to
   // drive a browser, so the runner must actually receive the browser tools and
@@ -517,6 +545,24 @@ test("plan-slice prompt clarifies gsd_plan_slice handles task persistence", () =
   assert.match(prompt, /gsd_plan_slice` handles task persistence/i);
 });
 
+test("plan-slice prompt references web app UAT guidance when planning browser work", () => {
+  const prompt = readPrompt("plan-slice");
+  assert.match(prompt, /Web App UAT guidance/i);
+  assert.match(prompt, /Playwright smoke scaffolding/i);
+});
+
+test("complete-slice prompt references web app UAT mode rules", () => {
+  const prompt = readPrompt("complete-slice");
+  assert.match(prompt, /Web App UAT guidance/i);
+  assert.match(prompt, /browser-executable|runtime-executable/i);
+});
+
+test("plan-milestone prompt seeds web verification strategy", () => {
+  const prompt = readPrompt("plan-milestone");
+  assert.match(prompt, /Web apps/i);
+  assert.match(prompt, /Playwright|browser_\*/i);
+});
+
 test("replan-slice prompt uses gsd_replan_slice as canonical DB-backed tool", () => {
   const prompt = readPrompt("replan-slice");
   assert.match(prompt, /gsd_replan_slice/);

package/src/resources/extensions/gsd/tests/provider-error-guidance.test.ts

@@ -3,10 +3,10 @@ import assert from "node:assert/strict";
 
 import { classifyError, isTransient } from "../error-classifier.ts";
 import {
-  formatProviderErrorGuidance,
   resolveProviderErrorGuidance,
   unitTypeToPrefsPhaseKey,
 } from "../provider-error-guidance.ts";
+import { formatGuidance } from "../guidance.ts";
 
 test("classifyError: Cloud Code Assist 400 invalid argument is model-error", () => {
   const result = classifyError(
@@ -75,8 +75,8 @@ test("resolveProviderErrorGuidance suggests gemini-3-flash for antigravity pro-h
   assert.ok(guidance.steps.some((step) => step.includes("fallbacks")));
 });
 
-test("formatProviderErrorGuidance numbers steps", () => {
-  const text = formatProviderErrorGuidance({
+test("formatGuidance numbers steps", () => {
+  const text = formatGuidance({
     summary: "Provider error on test/model.",
     steps: ["Change model", "Run /gsd next"],
   });

package/src/resources/extensions/gsd/tests/provider-errors.test.ts

@@ -740,6 +740,15 @@ test("MAX_TRANSIENT_AUTO_RESUMES is at least 8 for sustained overload resilience
   );
 });
 
+// ── OpenAI-completions mid-stream cut (#577) ─────────────────────────────────
+
+test("classifyError: 'Stream ended without finish_reason' is transient network (#577)", () => {
+  const result = classifyError("Stream ended without finish_reason");
+  assert.ok(isTransient(result), "Stream ended without finish_reason must be transient");
+  assert.equal(result.kind, "network");
+  assert.ok("retryAfterMs" in result && result.retryAfterMs > 0);
+});
+
 // ── Stream idle timeout / partial response (#4558) ──────────────────────────
 
 test("classifyError: 'Stream idle timeout - partial response received' is transient network", () => {