fix(onboard): explain a gateway database with a modified migration

sqlx reports a gateway database written by a newer OpenShell with one of
two texts. Gateway start explains "is missing in the resolved
migrations" but passed "migration N was previously applied but has been
modified" through verbatim, with no database path, cause, or remedy.
Classify both texts as an incompatible gateway database, print the same
named-database recovery, and name both texts in the troubleshooting
page.

Refs: #9293
Signed-off-by: Udaya Tejas <udayatejas2004@gmail.com>

Author: udsy19

docs/reference/troubleshooting.mdx

@@ -602,16 +602,23 @@ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
 
 The next installer run must continue past the OpenShell installation step without reporting a version mismatch.
 
-### Docker Driver Gateway Reports a Missing Migration
+### Docker Driver Gateway Reports an Incompatible Migration
 
-Onboarding can stop when the Docker driver gateway log contains both parts of this error:
+Onboarding can stop when the Docker driver gateway log contains both parts of either error:
 
 ```text
 migration N was previously applied
 is missing in the resolved migrations
 ```
 
-NemoClaw identifies `<selected-state-dir>/openshell.db` as incompatible with the installed OpenShell migration set.
+```text
+migration N was previously applied
+has been modified
+```
+
+The first error means the installed OpenShell migration set does not contain migration N.
+The second error means that migration set defines migration N with different contents.
+NemoClaw identifies `<selected-state-dir>/openshell.db` as incompatible with the installed OpenShell migration set for both errors.
 This failure can happen after an OpenShell downgrade.
 Installing a NemoClaw release that is older than the installed one performs that downgrade, because each release pins one OpenShell version and the installer reinstalls OpenShell at the pin.
 You reach that state in one of three ways:

src/lib/onboard/docker-driver-gateway-failure.test.ts

@@ -144,16 +144,16 @@ describe("reportDockerDriverGatewayStartFailure (#3111)", () => {
     }
   });
 
-  it("prints a shell-quoted state-directory move after confirming no gateway process remains (#8797)", () => {
+  it("prints a shell-quoted state-directory move after confirming no gateway process remains (#8797, #9293)", () => {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "gw-fail-"));
     const stateDir = path.join(dir, "gateway state;echo it's ignored");
     const log = path.join(stateDir, "openshell-gateway.log");
     fs.mkdirSync(stateDir);
     fs.writeFileSync(
       log,
       [
-        "Error: execution error: migration error: migration 6 was previously applied",
-        "  is missing in the resolved migrations",
+        "Error: execution error: migration error: migration 4 was previously applied but",
+        "  has been modified",
       ].join("\n"),
     );
     try {
@@ -166,6 +166,7 @@ describe("reportDockerDriverGatewayStartFailure (#3111)", () => {
       const joined = errSpy.mock.calls.map((c: string[]) => c.join(" ")).join("\n");
       expect(joined).toContain("cannot use the existing gateway database");
       expect(joined).toContain(`Database: ${path.join(stateDir, "openshell.db")}`);
+      expect(joined).toContain("does not include, or defines with different contents");
       expect(joined).toContain("it'\\''s ignored'");
       expect(joined).toContain("it'\\''s ignored.incompatible'");
       expect(joined).toContain("contains credentials and all registrations");

src/lib/onboard/docker-driver-gateway-failure.ts

@@ -66,7 +66,9 @@ function printIncompatibleGatewayDatabaseRecovery(
     : onboardResumeRecoveryCommand();
   printError("  The installed OpenShell version cannot use the existing gateway database.");
   printError(`  Database: ${path.join(stateDir, "openshell.db")}`);
-  printError("  The database records a migration that this OpenShell version does not include.");
+  printError(
+    "  The database records a migration that this OpenShell version does not include, or defines with different contents.",
+  );
   printError("  This can happen after an OpenShell downgrade.");
   const stopCommand = resolveGatewayStopCommand();
   if (!stopCommand && isGatewayStateInUse?.() !== false) {

src/lib/onboard/gateway-start-failure.test.ts

@@ -73,6 +73,23 @@ describe("classifyGatewayStartFailure", () => {
     });
   });
 
+  it("classifies a modified applied migration as an incompatible database (#9293)", () => {
+    const output = [
+      "Error:   × execution error: migration error: migration 4 was previously applied but",
+      "  │ has been modified",
+    ].join("\n");
+
+    expect(classifyGatewayStartFailure(output)).toEqual({
+      kind: "database_migration_incompatible",
+    });
+  });
+
+  it("does not classify an on-disk migration-file edit as incompatible database state (#9293)", () => {
+    const output = "the file containing migration 6 has been modified on disk";
+
+    expect(classifyGatewayStartFailure(output)).toEqual({ kind: "unknown" });
+  });
+
   it("does not classify an unrelated SQLite migration failure as incompatible database state (#8797)", () => {
     const output = "database is locked while applying migration 6";
 

src/lib/validation.ts

@@ -42,7 +42,10 @@ export interface GatewayStartFailure {
    *   dockerd on Linux) is not responding. Retrying the openshell health
    *   poll cannot recover from this — the user must start Docker first.
    * - `database_migration_incompatible`: the gateway database records a
-   *   migration that the installed OpenShell version does not include.
+   *   migration that the installed OpenShell version does not include, or
+   *   defines with different contents. Both sqlx signatures mean the database
+   *   was written by a newer OpenShell than the one now starting (#8797,
+   *   #9293).
    * - `unknown`: any other failure; callers should fall through to the
    *   normal retry/health-wait behavior.
    */
@@ -224,8 +227,12 @@ export function planSandboxCreateRecovery(
  */
 export function classifyGatewayStartFailure(output = ""): GatewayStartFailure {
   const text = String(output || "");
+  // Both sqlx migrate signatures for a database written by a newer OpenShell:
+  // the newer build appended a migration this build does not resolve
+  // ("is missing in the resolved migrations"), or it rewrote an applied
+  // migration so the checksum no longer matches ("has been modified").
   if (
-    /migration\s+\d+\s+was previously applied[\s\S]{0,512}\bis missing in the resolved migrations\b/i.test(
+    /migration\s+\d+\s+was previously applied[\s\S]{0,512}\b(?:is missing in the resolved migrations|has been modified)\b/i.test(
       text,
     )
   ) {