fix(connect): warn when Shields auto-relocks (#9508)

## Summary

OpenClaw sessions opened through `nemoclaw <sandbox> connect` now
surface a warning when Shields auto-relock while the terminal connection
is active. Connect now uses the existing asynchronous child supervisor,
so the parent event loop can poll without a worker thread; audit-read
failures remain advisory and never interrupt the session.

## Related Issue

Fixes #9453

## Changes

- Run `openshell sandbox connect` through the existing async child
supervisor with inherited stdio and signal cleanup.
- Start a parent-event-loop watcher only for connect-managed OpenClaw
sessions while the child owns the terminal.
- Poll the bounded Shields audit reader and emit one direct stderr
warning for each new auto-relock event after the session begins.
- Include a shell-quoted, validated `shields down --timeout` recovery
command and a safe timeout fallback.
- Clear the watcher in the child lifecycle's `finally` path before
connect exit handling and preserve terminal-runtime behavior.
- Share recovery-command formatting with the existing one-shot agent
warning and add unit/flow coverage.

## Type of Change

- [x] Code change (feature, bug fix, or refactor)
- [ ] Code change with doc updates
- [ ] Doc only (prose changes, no code sample modifications)
- [ ] Doc only (includes code sample changes)

## Quality Gates

- [x] Tests added or updated for changed behavior
- [ ] Existing tests cover changed behavior — justification:
- [ ] Tests not applicable — justification:
- [x] Sensitive paths changed (security, policy, credentials, preflight,
onboarding, inference, runner, sandbox, or messaging)
- [ ] Sensitive-path review completed or maintainer-approved waiver
recorded — reviewer/approval link/justification:
- [ ] Non-success, skipped, or missing CI check accepted by maintainer —
check name, approval link, and follow-up issue:

## DGX Station Hardware Evidence

- [ ] Tested on DGX Station
- Tested commit:
- Station profile/scenario:
- Result:
- Supporting evidence:

## Verification

- [x] PR description includes a `Signed-off-by:` line and every commit
appears as `Verified` in GitHub
- [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or
`npm run validate:pr` passed after refreshing `origin/main` when hooks
were skipped or unavailable
- [x] Targeted behavior tests pass for the current change set, or tests
are marked not applicable above — at
`25a7536900c9db5ece8a143e4a800b04f1e13b4d`, 107/107 watcher,
connect-flow, terminal-skin, and shared child-supervisor tests passed
locally; the earlier DGX Spark Ubuntu aarch64 behavior smoke at
`437fe871b13e48c8b009afe48a25148208a67e75` emitted the expected warning
and shell-quoted recovery command
- [x] Applicable broad gate passed — `npm test` for broad
runtime/test-harness changes; `npm run check` for repo-wide
validation/coverage changes — command/result: the owning connect-prefix
suite passed 177/177; source-architecture, TypeScript, commit hooks, and
pre-push hooks passed
- [ ] Quality Gates section completed with required justifications or
waivers
- [x] No secrets, API keys, or credentials committed
- [ ] `npm run docs` builds without warnings (doc changes only)
- [ ] Doc pages follow the [style
guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md)
(doc changes only)
- [ ] New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Prekshi Vyas <prekshiv@nvidia.com>


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added recovery notices when Shields automatically relocks during an
active sandbox connection.
* Notices include actionable recovery guidance and avoid repeating stale
or duplicate alerts.
* Connected sessions now monitor relock events and cleanly stop
monitoring when the session ends.
* Improved sandbox command execution with support for working-directory
and environment settings.

* **Bug Fixes**
* Relock monitoring gracefully handles unavailable audit information
without interrupting sessions.
  * Restricted recovery warnings to supported host agent workflows.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Prekshi Vyas <prekshiv@nvidia.com>

Author: prekshivyas

ci/source-architecture-budget.json

@@ -37,7 +37,7 @@
     "defaultMax": 20,
     "maxByFile": {
       "src/lib/actions/inference-set.ts": 32,
-      "src/lib/actions/sandbox/connect.ts": 41,
+      "src/lib/actions/sandbox/connect.ts": 42,
       "src/lib/actions/sandbox/destroy.ts": 29,
       "src/lib/actions/sandbox/doctor.ts": 30,
       "src/lib/actions/sandbox/status-snapshot.ts": 21,

src/lib/actions/sandbox/agent/connect-shields-relock-notice.test.ts

@@ -0,0 +1,100 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, it, vi } from "vitest";
+import type { ShieldsAutoRestoreReadResult } from "../../../shields/audit";
+import {
+  type ConnectShieldsRelockNoticeState,
+  pollConnectShieldsRelockNotice,
+  startConnectShieldsRelockWatcher,
+} from "./connect-shields-relock-notice";
+
+function state(startedAtMs: number): ConnectShieldsRelockNoticeState {
+  return {
+    lastNotifiedRestoreMs: startedAtMs - 1,
+    sandboxName: "alpha beta",
+    startedAtMs,
+  };
+}
+
+describe("connected-session Shields auto-relock notice", () => {
+  it("prints one actionable warning for a new auto-relock event (#9453)", () => {
+    const startedAtMs = Date.parse("2026-08-18T17:00:00.000Z");
+    const readRecent = vi.fn(() => ({
+      kind: "event" as const,
+      event: { timestamp: "2026-08-18T17:00:20.000Z", timeoutSeconds: 20 },
+    }));
+    const writeNotice = vi.fn();
+
+    const afterFirstPoll = pollConnectShieldsRelockNotice(
+      state(startedAtMs),
+      readRecent,
+      writeNotice,
+    );
+    const afterSecondPoll = pollConnectShieldsRelockNotice(afterFirstPoll, readRecent, writeNotice);
+
+    expect(afterSecondPoll.lastNotifiedRestoreMs).toBe(Date.parse("2026-08-18T17:00:20.000Z"));
+    expect(writeNotice).toHaveBeenCalledOnce();
+    expect(writeNotice.mock.calls[0]?.[0]).toContain("Shields auto-relocked after 20s");
+    expect(writeNotice.mock.calls[0]?.[0]).toContain("restricted operations may now fail");
+    expect(writeNotice.mock.calls[0]?.[0]).toContain(
+      "nemoclaw 'alpha beta' shields down --timeout 20s",
+    );
+  });
+
+  it("ignores relock history from before this connected session (#9453)", () => {
+    const startedAtMs = Date.parse("2026-08-18T17:00:00.000Z");
+    const writeNotice = vi.fn();
+
+    const result = pollConnectShieldsRelockNotice(
+      state(startedAtMs),
+      () => ({
+        kind: "event",
+        event: { timestamp: "2026-08-18T16:59:59.999Z", timeoutSeconds: 20 },
+      }),
+      writeNotice,
+    );
+
+    expect(result).toEqual(state(startedAtMs));
+    expect(writeNotice).not.toHaveBeenCalled();
+  });
+
+  it("keeps the connected session available when audit visibility is degraded (#9453)", () => {
+    const startedAtMs = Date.parse("2026-08-18T17:00:00.000Z");
+    const writeNotice = vi.fn();
+
+    expect(
+      pollConnectShieldsRelockNotice(
+        state(startedAtMs),
+        () => ({ kind: "unreadable" }),
+        writeNotice,
+      ),
+    ).toEqual(state(startedAtMs));
+    expect(writeNotice).not.toHaveBeenCalled();
+  });
+
+  it("polls on the parent event loop and stops cleanly (#9453)", () => {
+    vi.useFakeTimers();
+    const startedAtMs = Date.parse("2026-08-18T17:00:00.000Z");
+    vi.setSystemTime(startedAtMs);
+    const readRecent = vi
+      .fn<(sandboxName: string) => ShieldsAutoRestoreReadResult>()
+      .mockReturnValueOnce({ kind: "none" })
+      .mockReturnValue({
+        kind: "event",
+        event: { timestamp: "2026-08-18T17:00:00.500Z", timeoutSeconds: 20 },
+      });
+    const writeNotice = vi.fn();
+
+    const watcher = startConnectShieldsRelockWatcher("alpha", readRecent, writeNotice);
+    expect(readRecent).toHaveBeenCalledOnce();
+
+    vi.advanceTimersByTime(1_000);
+    expect(writeNotice).toHaveBeenCalledOnce();
+
+    watcher?.stop();
+    vi.advanceTimersByTime(2_000);
+    expect(readRecent).toHaveBeenCalledTimes(2);
+    vi.useRealTimers();
+  });
+});

src/lib/actions/sandbox/agent/connect-shields-relock-notice.ts

@@ -0,0 +1,112 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+  readRecentShieldsAutoRestore,
+  type ShieldsAutoRestoreReadResult,
+} from "../../../shields/audit";
+import { runSandboxExecChild, type SandboxExecChildOptions, type SpawnLikeResult } from "../exec";
+import {
+  formatShieldsDownRecoveryCommand,
+  normalizeShieldsRelockTimeoutSeconds,
+} from "./passthrough-shields-warning";
+
+const CONNECT_SHIELDS_RELOCK_LOOKBACK_MS = 10 * 60 * 1000;
+const CONNECT_SHIELDS_RELOCK_POLL_MS = 1000;
+
+type ConnectShieldsRelockNoticeReader = (sandboxName: string) => ShieldsAutoRestoreReadResult;
+
+export interface ConnectShieldsRelockNoticeState {
+  readonly lastNotifiedRestoreMs: number;
+  readonly sandboxName: string;
+  readonly startedAtMs: number;
+}
+
+export interface ConnectShieldsRelockWatcher {
+  stop(): void;
+}
+
+function formatConnectShieldsRelockNotice(
+  sandboxName: string,
+  timeoutSeconds: number | null,
+): string {
+  const safeTimeout = normalizeShieldsRelockTimeoutSeconds(timeoutSeconds);
+  const afterPart = safeTimeout === null ? "" : ` after ${String(safeTimeout)}s`;
+  return (
+    `\n  ⚠ Shields auto-relocked${afterPart}. This connected session remains open, but restricted operations may now fail.\n` +
+    `  Run \`${formatShieldsDownRecoveryCommand(sandboxName, safeTimeout)}\` on the host to lower Shields again.\n`
+  );
+}
+
+export function pollConnectShieldsRelockNotice(
+  state: ConnectShieldsRelockNoticeState,
+  readRecent: ConnectShieldsRelockNoticeReader = (sandboxName) =>
+    readRecentShieldsAutoRestore(sandboxName, CONNECT_SHIELDS_RELOCK_LOOKBACK_MS),
+  writeNotice: (value: string) => void = (value) => {
+    process.stderr.write(value);
+  },
+): ConnectShieldsRelockNoticeState {
+  const result = readRecent(state.sandboxName);
+  if (result.kind !== "event") return state;
+  const restoreMs = new Date(result.event.timestamp).getTime();
+  if (
+    !Number.isFinite(restoreMs) ||
+    restoreMs < state.startedAtMs ||
+    restoreMs <= state.lastNotifiedRestoreMs
+  ) {
+    return state;
+  }
+  writeNotice(formatConnectShieldsRelockNotice(state.sandboxName, result.event.timeoutSeconds));
+  return { ...state, lastNotifiedRestoreMs: restoreMs };
+}
+
+export function startConnectShieldsRelockWatcher(
+  sandboxName: string,
+  readRecent: ConnectShieldsRelockNoticeReader = (name) =>
+    readRecentShieldsAutoRestore(name, CONNECT_SHIELDS_RELOCK_LOOKBACK_MS),
+  writeNotice: (value: string) => void = (value) => {
+    process.stderr.write(value);
+  },
+): ConnectShieldsRelockWatcher | null {
+  try {
+    const startedAtMs = Date.now();
+    let state: ConnectShieldsRelockNoticeState = {
+      lastNotifiedRestoreMs: startedAtMs - 1,
+      sandboxName,
+      startedAtMs,
+    };
+    const poll = () => {
+      try {
+        state = pollConnectShieldsRelockNotice(state, readRecent, writeNotice);
+      } catch {
+        // Audit visibility is advisory. Keep the connected session available.
+      }
+    };
+    poll();
+    const timer = setInterval(poll, CONNECT_SHIELDS_RELOCK_POLL_MS);
+    timer.unref();
+    return {
+      stop(): void {
+        clearInterval(timer);
+      },
+    };
+  } catch {
+    // Advisory visibility must never prevent or terminate a connect session.
+    return null;
+  }
+}
+
+export async function runConnectChildWithShieldsRelockNotice(
+  binary: string,
+  args: readonly string[],
+  options: SandboxExecChildOptions,
+  sandboxName: string,
+  watchShields: boolean,
+): Promise<SpawnLikeResult> {
+  const watcher = watchShields ? startConnectShieldsRelockWatcher(sandboxName) : null;
+  try {
+    return await runSandboxExecChild(binary, args, options);
+  } finally {
+    watcher?.stop();
+  }
+}

src/lib/actions/sandbox/agent/passthrough-shields-warning.ts

@@ -22,10 +22,10 @@ import {
 // - Presentation boundary: sandbox names are user-controlled command text and
 //   must remain shell-quoted. Direct stderr output is deliberate so the warning
 //   is visible in a one-shot CLI while machine-readable stdout stays clean.
-// - Source-fix constraint: an already-running in-sandbox TUI has no host CLI
-//   interception point. That surface needs an upstream structured relock error
-//   or a separate extend-on-activity design; this helper covers only host
-//   `nemoclaw <name> agent` dispatches.
+// - Source-fix constraint: this helper covers only host `nemoclaw <name> agent`
+//   dispatches. Connect-managed OpenClaw sessions use a separate bounded audit
+//   watcher. Sessions entered outside NemoClaw still need an upstream structured
+//   relock error or a separate extend-on-activity design.
 // - Regression tests cover validated/fallback timeouts, shell metacharacters
 //   and embedded quotes, real-file JSON stdout separation, unreadable/absent
 //   history, newer-down suppression, and terminal-runtime exclusion.
@@ -44,25 +44,34 @@ type ShieldsWarningProcess = {
 
 type RecentShieldsAutoRestoreReader = (sandboxName: string) => ShieldsAutoRestoreReadResult;
 
+export function normalizeShieldsRelockTimeoutSeconds(timeoutSeconds: number | null): number | null {
+  return timeoutSeconds !== null &&
+    Number.isInteger(timeoutSeconds) &&
+    timeoutSeconds >= 1 &&
+    timeoutSeconds <= 1800
+    ? timeoutSeconds
+    : null;
+}
+
+export function formatShieldsDownRecoveryCommand(
+  sandboxName: string,
+  timeoutSeconds: number | null,
+): string {
+  const safeTimeout = normalizeShieldsRelockTimeoutSeconds(timeoutSeconds);
+  return `${CLI_NAME} ${shellQuote(sandboxName)} shields down --timeout ${String(safeTimeout ?? 60)}s`;
+}
+
 function emitShieldsRelockWarning(
   proc: ShieldsWarningProcess,
   relock: ShieldsAutoRestoreEvent,
   sandboxName: string,
 ): void {
   // Defend the user-facing command suggestion even when tests or future
   // callers inject an event without going through the audit reader.
-  const timeoutSeconds =
-    relock.timeoutSeconds !== null &&
-    Number.isInteger(relock.timeoutSeconds) &&
-    relock.timeoutSeconds >= 1 &&
-    relock.timeoutSeconds <= 1800
-      ? relock.timeoutSeconds
-      : null;
+  const timeoutSeconds = normalizeShieldsRelockTimeoutSeconds(relock.timeoutSeconds);
   const afterPart = timeoutSeconds !== null ? ` after ${String(timeoutSeconds)}s` : "";
-  const timeoutSuggestion =
-    timeoutSeconds !== null ? `--timeout ${String(timeoutSeconds)}s` : "--timeout 60s";
   proc.stderr.write(
-    `  ⚠ Shields auto-relocked${afterPart} — run \`${CLI_NAME} ${shellQuote(sandboxName)} shields down ${timeoutSuggestion}\` to extend.\n`,
+    `  ⚠ Shields auto-relocked${afterPart} — run \`${formatShieldsDownRecoveryCommand(sandboxName, timeoutSeconds)}\` to extend.\n`,
   );
 }