fix(onboard): narrow forward readiness retry

src/lib/onboard/forward-start.test.ts

@@ -942,18 +942,25 @@ describe("runDetachedForwardStartWithRetries", () => {
       .fn()
       .mockReturnValueOnce(forwardListWith([]))
       .mockReturnValue(forwardListWith([{ sandbox: "my-sandbox", port: 18789 }]));
+    const events: string[] = [];
     const spawn = vi
       .fn()
       .mockImplementationOnce(({ stderr }: { stderr: number }) => {
+        events.push("spawn-1");
         fs.writeSync(
           stderr,
           "Error: code: 'The system is not in a state required for the operation's execution', message: \"sandbox is not ready\"\n",
         );
         return { pid: 784 };
       })
-      .mockReturnValueOnce({ pid: 785 });
+      .mockImplementationOnce(() => {
+        events.push("spawn-2");
+        return { pid: 785 };
+      });
     const beforeRetry = vi.fn();
-    const sleep = vi.fn();
+    const sleep = vi.fn((ms: number) => {
+      events.push(`sleep-${ms}`);
+    });
 
     const result = runDetachedForwardStartWithRetries(
       spawn,
@@ -969,7 +976,43 @@ describe("runDetachedForwardStartWithRetries", () => {
     expect(result.ok).toBe(true);
     expect(beforeRetry).not.toHaveBeenCalled();
     expect(spawn).toHaveBeenCalledTimes(2);
+    expect(sleep).toHaveBeenCalledOnce();
     expect(sleep).toHaveBeenCalledWith(5_000);
+    expect(events).toEqual(["spawn-1", "sleep-5000", "spawn-2"]);
+  });
+
+  it("does not retry a composite authentication diagnostic that mentions readiness", () => {
+    let now = 0;
+    vi.spyOn(Date, "now").mockImplementation(() => now);
+    const delays: number[] = [];
+    const spawn = vi.fn().mockImplementation(({ stderr }: { stderr: number }) => {
+      fs.writeSync(
+        stderr,
+        "Permission denied (publickey); previous attempt reported Error: code: 'The system is not in a state required for the operation's execution', message: \"sandbox is not ready\"\n",
+      );
+      return { pid: 784 };
+    });
+
+    const result = runDetachedForwardStartWithRetries(
+      spawn,
+      vi.fn().mockReturnValue(forwardListWith([])),
+      { port: 18789, sandboxName: "my-sandbox" },
+      vi.fn(),
+      {
+        overallTimeoutMs: 1_000,
+        pollIntervalMs: 500,
+        sleepMs: (ms) => {
+          delays.push(ms);
+          now += ms;
+        },
+        isPortListening: vi.fn().mockReturnValue(false),
+      },
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.reason).toBe("timeout");
+    expect(spawn).toHaveBeenCalledOnce();
+    expect(delays).not.toContain(5_000);
   });
 
   it("preserves a ControlMaster listener created by the current attempt (#6099)", () => {
@@ -1087,6 +1130,11 @@ describe("looksLikeForwardPortConflict", () => {
 
 describe("looksLikeForwardListenerStartFailure", () => {
   it("matches only definitive listener termination diagnostics", () => {
+    expect(
+      looksLikeForwardListenerStartFailure(
+        "Error: code: 'The system is not in a state required for the operation's execution', message: \"sandbox is not ready\"",
+      ),
+    ).toBe(true);
     expect(
       looksLikeForwardListenerStartFailure(
         "local forward listener did not open on 127.0.0.1:18789 within 10000ms",
@@ -1099,6 +1147,11 @@ describe("looksLikeForwardListenerStartFailure", () => {
     ).toBe(true);
     expect(looksLikeForwardListenerStartFailure("Permission denied (publickey)")).toBe(false);
     expect(looksLikeForwardListenerStartFailure("gateway transport unavailable")).toBe(false);
+    expect(
+      looksLikeForwardListenerStartFailure(
+        'Permission denied (publickey); previous attempt reported "sandbox is not ready"',
+      ),
+    ).toBe(false);
   });
 });
 

src/lib/onboard/forward-start.ts

@@ -106,6 +106,13 @@ export function looksLikeUntrackedForward(diagnostic: string): boolean {
   );
 }
 
+const OPENSHELL_SANDBOX_NOT_READY_DIAGNOSTIC =
+  /^Error: code: 'The system is not in a state required for the operation's execution', message: "sandbox is not ready"$/i;
+
+function looksLikeSandboxNotReadyForwardStart(diagnostic: string): boolean {
+  return OPENSHELL_SANDBOX_NOT_READY_DIAGNOSTIC.test(diagnostic);
+}
+
 /**
  * True only after openshell reports that the SSH process has definitively
  * stopped waiting for its local listener. Unlike the broader untracked-
@@ -125,7 +132,7 @@ export function looksLikeUntrackedForward(diagnostic: string): boolean {
  * the retry wrapper below gives the OpenShell gateway a bounded settle interval.
  */
 export function looksLikeForwardListenerStartFailure(diagnostic: string): boolean {
-  if (/\bsandbox is not ready\b/i.test(diagnostic)) return true;
+  if (looksLikeSandboxNotReadyForwardStart(diagnostic)) return true;
   return /ssh exited before local forward listener opened|local forward listener did not open\b/i.test(
     diagnostic,
   );
@@ -534,7 +541,7 @@ export function runDetachedForwardStartWithRetries(
       if (looksLikeForwardPortConflict(attempt.diagnostic)) {
         beforeRetryCleanup();
       }
-      if (/\bsandbox is not ready\b/i.test(attempt.diagnostic)) {
+      if (looksLikeSandboxNotReadyForwardStart(attempt.diagnostic)) {
         // Keep the existing sandbox and port ownership intact while the
         // OpenShell gateway finishes the readiness handoff.
         sleepImpl(SANDBOX_READY_RETRY_SETTLE_MS);