fix(shields): preserve mutable-default rollback

scripts/openclaw-config-guard.py

@@ -3461,6 +3461,13 @@ def _transition(
                 raise GuardError(exc.code, exc.path, detail) from exc
             raise GuardError("transition-failed", opened.config_path, detail) from exc
 
+    if _is_mutable_dir_posture(opened, identity):
+        # Fresh and rebuilt sandboxes begin in this exact posture. Treating
+        # unlock as a locked-only transition makes the first shields-down fail
+        # and its rollback change the posture before a retry can succeed.
+        _preflight_restart(opened, identity)
+        return
+
     pair = _snapshot_pair(opened)
     _verify_locked_posture(opened, pair, identity, allow_blocking_flags=True)
     snapshots: list[FileSnapshot] = []

src/lib/shields/flow.test.ts

@@ -28,6 +28,7 @@ setInterval(() => {}, 60000);
 type ShieldsHarness = {
   auditSpy: MockInstance;
   errorSpy: MockInstance;
+  getOpenClawPosture: () => "locked" | "mutable";
   logSpy: MockInstance;
   runSpy: MockInstance;
   shieldsDown: typeof import("./index.js").shieldsDown;
@@ -214,6 +215,7 @@ function createHarness(options: HarnessOptions = {}): ShieldsHarness {
   return {
     auditSpy,
     errorSpy,
+    getOpenClawPosture: () => openClawPosture,
     logSpy,
     runSpy,
     shieldsDown: shields.shieldsDown,
@@ -283,6 +285,121 @@ describe("shields command flow", () => {
     );
   });
 
+  it("restores fresh mutable-default state when the timer handoff fails", () => {
+    const stateDir = path.join(tmpDir, ".nemoclaw", "state");
+    const harness = createHarness({
+      fork: () => ({
+        pid: 4242,
+        disconnect: vi.fn(),
+        unref: vi.fn(),
+        send: vi.fn(() => {
+          const transitionName = fs
+            .readdirSync(stateDir)
+            .find((entry) => entry.startsWith("shields-transition-openclaw-"));
+          const transitionPath = path.join(stateDir, transitionName!);
+          const transition = JSON.parse(fs.readFileSync(transitionPath, "utf-8"));
+          fs.writeFileSync(transitionPath, JSON.stringify({ ...transition, phase: "active" }));
+          return true;
+        }),
+        kill: vi.fn(() => true),
+      }),
+    });
+
+    expect(() =>
+      harness.shieldsDown("openclaw", {
+        timeout: "5m",
+        reason: "rollback coverage",
+        throwOnError: true,
+      }),
+    ).toThrow("Shields-down recovery ownership changed during the transition");
+
+    expect(fs.existsSync(path.join(stateDir, "shields-openclaw.json"))).toBe(false);
+    const output = harness.errorSpy.mock.calls.flat().map(String).join("\n");
+    expect(output).toContain("Original mutable-default posture restored");
+    expect(output).not.toContain("Lockdown restored");
+  });
+
+  it("restores corrupt mutable-default state bytes when the timer handoff fails", () => {
+    const stateDir = path.join(tmpDir, ".nemoclaw", "state");
+    const statePath = path.join(stateDir, "shields-openclaw.json");
+    const corruptState = "{not-json\n";
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.writeFileSync(statePath, corruptState);
+    const harness = createHarness({
+      fork: () => ({
+        pid: 4242,
+        disconnect: vi.fn(),
+        unref: vi.fn(),
+        send: vi.fn(() => {
+          const transitionName = fs
+            .readdirSync(stateDir)
+            .find((entry) => entry.startsWith("shields-transition-openclaw-"));
+          const transitionPath = path.join(stateDir, transitionName!);
+          const transition = JSON.parse(fs.readFileSync(transitionPath, "utf-8"));
+          fs.writeFileSync(transitionPath, JSON.stringify({ ...transition, phase: "active" }));
+          return true;
+        }),
+        kill: vi.fn(() => true),
+      }),
+    });
+
+    expect(() =>
+      harness.shieldsDown("openclaw", {
+        timeout: "5m",
+        reason: "corrupt rollback coverage",
+        throwOnError: true,
+      }),
+    ).toThrow("Shields-down recovery ownership changed during the transition");
+
+    expect(fs.readFileSync(statePath, "utf-8")).toBe(corruptState);
+    expect(harness.errorSpy.mock.calls.flat().map(String).join("\n")).toContain(
+      "Original mutable-default posture restored",
+    );
+  });
+
+  it("reports fail-closed lockdown when mutable-default rollback cannot be verified", () => {
+    const harness = createHarness({
+      failOpenClawGuardActions: ["unlock"],
+      dockerExecFileSync: (argv: unknown) => {
+        const args = Array.isArray(argv) ? argv.map(String) : [];
+        switch (true) {
+          case args.includes("sha256sum"):
+            return `${"a".repeat(64)}  ${String(args.at(-1))}\n`;
+          case args.includes("lsattr"):
+            return `----i---------e----- ${String(args.at(-1))}\n`;
+          case args.includes("stat"):
+            return args.at(-1) === "/sandbox"
+              ? "1775 root:sandbox\n"
+              : args.at(-1) === "/sandbox/.openclaw"
+                ? "755 root:root\n"
+                : "444 root:root\n";
+          default:
+            return "";
+        }
+      },
+    });
+
+    expect(() =>
+      harness.shieldsDown("openclaw", {
+        timeout: "5m",
+        reason: "containment coverage",
+        skipTimer: true,
+        throwOnError: true,
+      }),
+    ).toThrow(/startup-not-ready/);
+
+    const statePath = path.join(tmpDir, ".nemoclaw", "state", "shields-openclaw.json");
+    expect(JSON.parse(fs.readFileSync(statePath, "utf-8"))).toMatchObject({
+      shieldsDown: false,
+    });
+    expect(harness.getOpenClawPosture()).toBe("locked");
+    const output = harness.errorSpy.mock.calls.flat().map(String).join("\n");
+    expect(output).toContain("applying fail-closed lockdown");
+    expect(output).toContain(
+      "Fail-closed lockdown applied; the original mutable-default posture was not restored",
+    );
+  });
+
   it("binds manual shields-up to the active auto-restore timer generation", () => {
     const stateDir = path.join(tmpDir, ".nemoclaw", "state");
     const sandboxName = "openclaw";

src/lib/shields/index.ts

@@ -735,6 +735,7 @@ type LoadedShieldsState = ShieldsState & {
   _hasStateFile: boolean;
   _isCorrupt?: boolean;
   _corruptError?: string;
+  _rawFileContents?: string;
 };
 
 interface ShieldsPosture {
@@ -837,13 +838,17 @@ function describeShieldsMode(mode: ShieldsPostureMode): Omit<ShieldsPosture, "st
 function loadShieldsState(sandboxName: string): LoadedShieldsState {
   const filePath = stateFilePath(sandboxName);
   if (!fs.existsSync(filePath)) return { _hasStateFile: false };
+  let rawFileContents: string | undefined;
   try {
-    const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    const contents = fs.readFileSync(filePath, "utf-8");
+    rawFileContents = contents;
+    const parsed = JSON.parse(contents);
     if (!isShieldsState(parsed)) {
       return {
         _hasStateFile: true,
         _isCorrupt: true,
         _corruptError: "invalid shields state shape",
+        _rawFileContents: rawFileContents,
       };
     }
     const state: ShieldsState = parsed;
@@ -854,6 +859,7 @@ function loadShieldsState(sandboxName: string): LoadedShieldsState {
       _hasStateFile: true,
       _isCorrupt: true,
       _corruptError: message,
+      ...(rawFileContents === undefined ? {} : { _rawFileContents: rawFileContents }),
     };
   }
 }
@@ -901,6 +907,7 @@ function saveShieldsState(sandboxName: string, patch: ShieldsState): ShieldsStat
     _hasStateFile: _hasStateFile,
     _isCorrupt: _isCorrupt,
     _corruptError: _corruptError,
+    _rawFileContents: _rawFileContents,
     ...currentClean
   } = current;
   const updated: ShieldsState = {
@@ -913,6 +920,30 @@ function saveShieldsState(sandboxName: string, patch: ShieldsState): ShieldsStat
   return updated;
 }
 
+function restoreShieldsStateSnapshot(sandboxName: string, state: LoadedShieldsState): void {
+  const {
+    _hasStateFile: hasStateFile,
+    _isCorrupt: isCorrupt,
+    _corruptError: _corruptError,
+    _rawFileContents: rawFileContents,
+    ...persisted
+  } = state;
+  const filePath = stateFilePath(sandboxName);
+  if (!hasStateFile) {
+    fs.rmSync(filePath, { force: true });
+    return;
+  }
+  fs.mkdirSync(STATE_DIR, { recursive: true, mode: 0o700 });
+  if (isCorrupt) {
+    if (rawFileContents === undefined) {
+      throw new Error("Cannot restore corrupt shields state without its original bytes");
+    }
+    fs.writeFileSync(filePath, rawFileContents, { mode: 0o600 });
+    return;
+  }
+  fs.writeFileSync(filePath, JSON.stringify(persisted, null, 2), { mode: 0o600 });
+}
+
 function isOptionalBoolean(value: unknown): value is boolean | undefined {
   return value === undefined || typeof value === "boolean";
 }
@@ -2331,6 +2362,8 @@ function rollbackShieldsDown(
   sandboxName: string,
   target: AgentConfigTarget,
   snapshotPath: string,
+  initialMode: ShieldsMode,
+  initialState: LoadedShieldsState,
   allowLegacyHermesProtocol = false,
   cachedProtocol?: HermesShieldsProtocol,
 ): void {
@@ -2341,6 +2374,20 @@ function rollbackShieldsDown(
   let rollbackChattrApplied: boolean | null = null;
   let rollbackFileHashes: { [path: string]: string } | null = null;
   if (rollbackResult.status === 0) {
+    if (initialMode === "mutable_default" && target.agentName === "openclaw") {
+      try {
+        unlockAgentConfig(sandboxName, target, false, allowLegacyHermesProtocol, cachedProtocol);
+        killTimer(sandboxName);
+        restoreShieldsStateSnapshot(sandboxName, initialState);
+        console.error("  Original mutable-default posture restored.");
+        return;
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        console.error(
+          `  Warning: Could not verify the original mutable-default posture; applying fail-closed lockdown. ${detail}`,
+        );
+      }
+    }
     // Re-confirm after the settle window so a reconciler revert cannot leave
     // the rolled-back config DRIFTED — same fail-closed treatment as the
     // auto-restore path. Leaves the hashes null (→ "manual intervention"
@@ -2353,7 +2400,7 @@ function rollbackShieldsDown(
       rollbackFileHashes = relock.lastResult.fileHashes;
     } else {
       console.error(
-        "  Warning: Rollback re-lock could not be re-confirmed. Check config manually.",
+        `  Warning: Rollback re-lock could not be re-confirmed. Check config manually. ${relock.error ?? ""}`.trimEnd(),
       );
     }
   } else {
@@ -2369,7 +2416,11 @@ function rollbackShieldsDown(
       chattrApplied: rollbackChattrApplied,
       fileHashes: rollbackFileHashes,
     });
-    console.error("  Lockdown restored. Config was never left unguarded.");
+    console.error(
+      initialMode === "mutable_default"
+        ? "  Fail-closed lockdown applied; the original mutable-default posture was not restored."
+        : "  Lockdown restored. Config was never left unguarded.",
+    );
   } else {
     console.error("  Config remains unlocked — manual intervention required.");
     printManualRelockRecoveryHint(sandboxName);
@@ -2590,6 +2641,13 @@ function shieldsDownWithoutHostLock(sandboxName: string, opts: ShieldsDownOpts =
   validateName(sandboxName, "sandbox name");
 
   const state = loadShieldsState(sandboxName);
+  if (state._isCorrupt && state._rawFileContents === undefined) {
+    return failShieldsCommand(
+      `Cannot snapshot corrupt shields state for ${sandboxName}`,
+      opts.throwOnError,
+    );
+  }
+  const initialMode = deriveShieldsMode(state, state._hasStateFile);
   if (state.shieldsDown) {
     console.error(
       `  Config is already unlocked for ${sandboxName} (since ${state.shieldsDownAt}).`,
@@ -2792,7 +2850,7 @@ function shieldsDownWithoutHostLock(sandboxName: string, opts: ShieldsDownOpts =
     unlockAgentConfig(
       sandboxName,
       target,
-      deriveShieldsMode(state, state._hasStateFile) === "locked",
+      initialMode === "locked",
       opts.allowLegacyHermesProtocol === true,
       protocol,
     );
@@ -2802,6 +2860,8 @@ function shieldsDownWithoutHostLock(sandboxName: string, opts: ShieldsDownOpts =
       sandboxName,
       target,
       snapshotPath,
+      initialMode,
+      state,
       opts.allowLegacyHermesProtocol === true,
       protocol,
     );
@@ -2826,6 +2886,8 @@ function shieldsDownWithoutHostLock(sandboxName: string, opts: ShieldsDownOpts =
         sandboxName,
         target,
         snapshotPath,
+        initialMode,
+        state,
         opts.allowLegacyHermesProtocol === true,
         protocol,
       );

test/openclaw-config-guard.test.ts

@@ -392,7 +392,16 @@ afterEach(() => {
 });
 
 describe("openclaw-config-guard", () => {
-  it("keeps an exact locked parent and pair unchanged across idempotent relock", () => {
+  it("keeps exact mutable and locked postures unchanged across idempotent transitions", () => {
+    const mutable = fixture();
+    const files = [mutable.configPath, mutable.hashPath];
+    const before = files.map((file) => [fs.statSync(file).ino, fs.readFileSync(file)]);
+    expect(runGuard("unlock", mutable.configDir).status).toBe(0);
+    expect([mode(mutable.root), mode(mutable.configDir)]).toEqual([0o755, 0o2770]);
+    for (const [index, file] of files.entries()) {
+      expect([fs.statSync(file).ino, fs.readFileSync(file)]).toEqual(before[index]);
+    }
+
     const { root, configDir, configPath, hashPath } = fixture();
     const first = runGuard("lock", configDir);
     expect(first.status, JSON.stringify(first.lines)).toBe(0);