refactor(policy): complete asynchronous policy and audit adapters

src/commands/sandbox/logs.ts

@@ -44,7 +44,7 @@ export default class SandboxLogsCommand extends NemoClawCommand {
 
   public async run(): Promise<void> {
     const { args, flags } = await this.parse(SandboxLogsCommand);
-    showSandboxLogs(args.sandboxName, {
+    await showSandboxLogs(args.sandboxName, {
       follow: flags.follow === true,
       lines: String(flags.tail),
       since: flags.since ?? null,

src/commands/sandbox/oclif-command-adapters.test.ts

@@ -272,6 +272,25 @@ describe("sandbox oclif command adapters", () => {
     expect(process.exitCode).toBe(1);
   });
 
+  it("keeps policy list pending until the asynchronous action completes", async () => {
+    let finish!: () => void;
+    mocks.listSandboxPolicies.mockImplementationOnce(
+      () =>
+        new Promise<void>((resolve) => {
+          finish = resolve;
+        }),
+    );
+    let completed = false;
+    const pending = SandboxPolicyListCommand.run(["alpha"], rootDir).then(() => {
+      completed = true;
+    });
+    await vi.waitFor(() => expect(mocks.listSandboxPolicies).toHaveBeenCalledWith("alpha"));
+    expect(completed).toBe(false);
+    finish();
+    await pending;
+    expect(completed).toBe(true);
+  });
+
   it("maps inspection commands to their action helpers", async () => {
     await SandboxStatusCommand.run(["alpha"], rootDir);
     await SandboxPolicyListCommand.run(["alpha"], rootDir);

src/commands/sandbox/policy/explain.ts

@@ -36,7 +36,7 @@ export default class SandboxPolicyExplainCommand extends NemoClawCommand {
 
   public async run(): Promise<void> {
     const { args, flags } = await this.parse(SandboxPolicyExplainCommand);
-    explainSandboxPolicy(
+    await explainSandboxPolicy(
       args.sandboxName,
       { json: flags.json, writeToSandbox: flags.write },
       { logJson: (value) => this.logJson(value) },

src/commands/sandbox/policy/list.ts

@@ -20,6 +20,6 @@ export default class SandboxPolicyListCommand extends NemoClawCommand {
 
   public async run(): Promise<void> {
     const { args } = await this.parse(SandboxPolicyListCommand);
-    listSandboxPolicies(args.sandboxName);
+    await listSandboxPolicies(args.sandboxName);
   }
 }

src/commands/status.ts

@@ -20,7 +20,7 @@ export default class StatusCommand extends NemoClawCommand {
     await this.parse(StatusCommand);
     const deps = buildStatusCommandDeps(this.config.root);
     if (this.jsonEnabled()) {
-      const report = getStatusReport(deps);
+      const report = await getStatusReport(deps);
       if (report.gatewayHealth && !report.gatewayHealth.healthy) {
         process.exitCode = 1;
       }

src/lib/actions/maintenance.test.ts

@@ -656,7 +656,8 @@ describe("backupAll", () => {
         manifest,
       };
     });
-    mocks.captureRecordedSandboxBasePolicy.mockImplementation(() => {
+    mocks.captureRecordedSandboxBasePolicy.mockImplementation(async () => {
+      await Promise.resolve();
       expect(lockActive).toBe(true);
       events.push("capture-policy");
       return "version: 1\nnetwork_policies: {}\n";

src/lib/actions/maintenance.ts

@@ -87,18 +87,18 @@ interface BackupAllSandboxAttempt {
   mutationLockError?: unknown;
 }
 
-function retainStrictPreUpgradePolicy(
+async function retainStrictPreUpgradePolicy(
   sandboxName: string,
   result: sandboxState.BackupResult,
   enabled: boolean,
-): sandboxState.BackupResult {
+): Promise<sandboxState.BackupResult> {
   if (!enabled || !result.success) return result;
   if (!result.manifest) {
     throw new Error(
       `Strict pre-upgrade backup for '${sandboxName}' completed without a published manifest`,
     );
   }
-  const policyDocument = captureRecordedSandboxBasePolicy(
+  const policyDocument = await captureRecordedSandboxBasePolicy(
     sandboxName,
     "capture the live policy for pre-upgrade recovery",
   );

src/lib/actions/sandbox/channel-status.test.ts

@@ -516,7 +516,7 @@ function slackWaitHarness(
 }
 
 function waitForSlack(
-  deps: ReturnType<typeof slackWaitHarness>["deps"],
+  deps: NonNullable<Parameters<typeof showSandboxChannelStatus>[1]>["deps"],
   timeoutSeconds = 10,
   pollIntervalMs = 5_000,
 ) {
@@ -665,3 +665,19 @@ describe("showSandboxChannelStatus unsupported readiness wait", () => {
     expect(sleep).not.toHaveBeenCalled();
   });
 });
+
+it("returns the status timeout when an applied-policy read remains pending", async () => {
+  vi.useFakeTimers();
+  try {
+    const { deps } = slackWaitHarness([{ connected: false }]);
+    const getAppliedPresets = vi.fn(() => new Promise<string[]>(() => {}));
+    const pending = waitForSlack({ ...deps, nowMs: () => Date.now(), getAppliedPresets }, 1);
+    await vi.advanceTimersByTimeAsync(1_000);
+    const result = await pending;
+    expect(result).toMatchObject({ readiness: { state: "timeout" } });
+    expect(getAppliedPresets).toHaveBeenCalledWith("alpha", 1_000);
+    expect(vi.getTimerCount()).toBe(0);
+  } finally {
+    vi.useRealTimers();
+  }
+});

src/lib/actions/sandbox/channel-status.ts

@@ -57,8 +57,11 @@ type ExecRunner = (
 type StatusDeps = {
   loadAgent?: (name: string) => AgentDefinition;
   getSandbox?: typeof registry.getSandbox;
-  getAppliedPresets?: (sandboxName: string) => string[];
-  getGatewayPresets?: (sandboxName: string, timeoutMs?: number) => string[] | null;
+  getAppliedPresets?: (sandboxName: string, timeoutMs?: number) => string[] | Promise<string[]>;
+  getGatewayPresets?: (
+    sandboxName: string,
+    timeoutMs?: number,
+  ) => string[] | null | Promise<string[] | null>;
   execSandbox?: ExecRunner;
   now?: () => Date;
   nowMs?: () => number;
@@ -301,7 +304,7 @@ async function buildBasicChannelReport(
   const entry = deps.getSandbox(sandboxName);
   const enabled = registry.getConfiguredMessagingChannelsFromEntry(entry).includes(channelName);
   const disabled = registry.getDisabledMessagingChannelsFromEntry(entry).includes(channelName);
-  const appliedPresets = deps.getAppliedPresets(sandboxName);
+  const appliedPresets = await deps.getAppliedPresets(sandboxName);
   const policyPresets =
     diagnostic.policyPresets.length > 0 ? diagnostic.policyPresets : [channelName];
   const presetApplied = policyPresets.some((preset) => appliedPresets.includes(preset));
@@ -429,11 +432,11 @@ async function runChannelHealthHook(
     .includes(channelName);
   const policyPresets =
     diagnostic.policyPresets.length > 0 ? diagnostic.policyPresets : [channelName];
-  const appliedPresets = deps.getAppliedPresets(sandboxName);
+  const appliedPresets = await deps.getAppliedPresets(sandboxName);
   const presetApplied = policyPresets.some((preset) => appliedPresets.includes(preset));
   let presetOnGateway: boolean | null = null;
   try {
-    const gatewayPresets = deps.getGatewayPresets(sandboxName);
+    const gatewayPresets = await deps.getGatewayPresets(sandboxName);
     presetOnGateway =
       gatewayPresets === null
         ? null
@@ -547,9 +550,24 @@ function withStatusDeadline(deps: Required<StatusDeps>, deadlineMs: number): Req
   };
   return {
     ...deps,
-    getGatewayPresets: (sandboxName, requestedTimeoutMs) => {
+    getAppliedPresets: async (sandboxName, requestedTimeoutMs) => {
       const timeoutMs = boundedTimeoutMs(requestedTimeoutMs);
-      return timeoutMs === null ? null : deps.getGatewayPresets(sandboxName, timeoutMs);
+      if (timeoutMs === null) return [];
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        return await Promise.race([
+          deps.getAppliedPresets(sandboxName, timeoutMs),
+          new Promise<string[]>((resolve) => {
+            timer = setTimeout(() => resolve([]), timeoutMs);
+          }),
+        ]);
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+    getGatewayPresets: async (sandboxName, requestedTimeoutMs) => {
+      const timeoutMs = boundedTimeoutMs(requestedTimeoutMs);
+      return timeoutMs === null ? null : await deps.getGatewayPresets(sandboxName, timeoutMs);
     },
     execSandbox: async (sandboxName, command, requestedTimeoutMs) => {
       const timeoutMs = boundedTimeoutMs(requestedTimeoutMs);
@@ -607,7 +625,9 @@ async function waitForChannelReadiness(
     elapsedMs = Math.max(0, deps.nowMs() - startedAt);
   }
   const state: ChannelStatusWaitState =
-    lastObserved.state === "waiting" ? "timeout" : lastObserved.state;
+    lastObserved.state === "waiting" || (elapsedMs >= timeoutMs && lastObserved.state !== "ready")
+      ? "timeout"
+      : lastObserved.state;
   return {
     schemaVersion: 1,
     sandbox: sandboxName,

src/lib/actions/sandbox/exec-policy-hint-emission.ts

@@ -1,13 +1,11 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+import { cliOpenShellSandboxSettings } from "../../adapters/openshell/sandbox-settings-cli";
+
 import { captureOpenshell } from "../../adapters/openshell/runtime";
 import type { SandboxLogsOptions } from "../../domain/sandbox/log-options";
-import {
-  buildEnableSandboxAuditLogsArgs,
-  buildSandboxLogsArgs,
-  getLogsProbeTimeoutMs,
-} from "../../domain/sandbox/logs";
+import { buildSandboxLogsArgs, getLogsProbeTimeoutMs } from "../../domain/sandbox/logs";
 import { findRecentPolicyDenial, type PolicyDenialMatch } from "./exec-policy-hint-detection";
 import {
   buildPolicyDenialExecHint,
@@ -38,7 +36,10 @@ export const POLICY_HINT_MAX_RUNTIME_TIMEOUT_MS = 1_000;
 export const POLICY_HINT_DEVICE_PROBE_TIMEOUT_MS = 5_000;
 
 export type PolicyDenialLogProbe = (sandboxName: string, gatewayName?: string) => string;
-export type PolicyDenialAuditEnabler = (sandboxName: string, gatewayName?: string) => void;
+export type PolicyDenialAuditEnabler = (
+  sandboxName: string,
+  gatewayName?: string,
+) => void | Promise<void>;
 
 export type PendingDeviceProbe = (sandboxName: string, gatewayName?: string) => string;
 
@@ -65,15 +66,13 @@ function runtimeTimeoutMs(): number {
   return Math.min(getLogsProbeTimeoutMs(), POLICY_HINT_MAX_RUNTIME_TIMEOUT_MS);
 }
 
-function defaultEnableAudit(sandboxName: string, gatewayName?: string): void {
-  const result = captureOpenshell(buildEnableSandboxAuditLogsArgs(sandboxName, gatewayName), {
-    ignoreError: true,
-    includeStderr: true,
-    timeout: runtimeTimeoutMs(),
+async function defaultEnableAudit(sandboxName: string, gatewayName?: string): Promise<void> {
+  const result = await cliOpenShellSandboxSettings.enableAuditLogs({
+    target: gatewayName ? { kind: "named", gatewayName } : { kind: "selected" },
+    sandboxName,
+    timeoutMs: runtimeTimeoutMs(),
   });
-  if (result.error || result.status !== 0) {
-    throw result.error ?? new Error(`failed to enable audit logs (exit ${result.status})`);
-  }
+  if (!result.ok) throw new Error(result.error.message);
 }
 
 function defaultProbeLogs(sandboxName: string, gatewayName?: string): string {
@@ -185,7 +184,7 @@ export async function maybeEmitPolicyDenialHint(
   const retryDelayMs = deps.retryDelayMs ?? POLICY_HINT_PROBE_RETRY_MS;
 
   try {
-    enableAudit(sandboxName, gatewayName);
+    await enableAudit(sandboxName, gatewayName);
   } catch {
     // Deliberately silent: audit setup is optional and retained logs may still
     // contain the denial. Printing this diagnostic, even under a new debug

src/lib/actions/sandbox/exec-policy-hint-runtime.test.ts

@@ -3,9 +3,15 @@
 
 import { afterEach, describe, expect, it, vi } from "vitest";
 
-const { captureOpenshell } = vi.hoisted(() => ({ captureOpenshell: vi.fn() }));
+const { captureOpenshell, enableAuditLogs } = vi.hoisted(() => ({
+  captureOpenshell: vi.fn(),
+  enableAuditLogs: vi.fn(),
+}));
 
 vi.mock("../../adapters/openshell/runtime", () => ({ captureOpenshell }));
+vi.mock("../../adapters/openshell/sandbox-settings-cli", () => ({
+  cliOpenShellSandboxSettings: { enableAuditLogs },
+}));
 
 import {
   maybeEmitPolicyDenialHint,
@@ -25,9 +31,8 @@ describe("policy-denial hint runtime adapter integration (#5978)", () => {
   });
 
   it("enables audit and reads the bounded OpenShell log tail through the runtime adapter", async () => {
-    captureOpenshell
-      .mockReturnValueOnce({ output: "", status: 0 })
-      .mockReturnValueOnce({ output: DENIED_LINE, status: 0 });
+    enableAuditLogs.mockResolvedValue({ ok: true, value: undefined });
+    captureOpenshell.mockReturnValueOnce({ output: DENIED_LINE, status: 0 });
     const stderr: string[] = [];
 
     const hint = await maybeEmitPolicyDenialHint(
@@ -44,27 +49,13 @@ describe("policy-denial hint runtime adapter integration (#5978)", () => {
       "nemoclaw-8091",
     );
 
+    expect(enableAuditLogs).toHaveBeenCalledExactlyOnceWith({
+      target: { kind: "named", gatewayName: "nemoclaw-8091" },
+      sandboxName: "runtime-sandbox",
+      timeoutMs: POLICY_HINT_MAX_RUNTIME_TIMEOUT_MS,
+    });
     expect(captureOpenshell).toHaveBeenNthCalledWith(
       1,
-      [
-        "settings",
-        "set",
-        "-g",
-        "nemoclaw-8091",
-        "runtime-sandbox",
-        "--key",
-        "ocsf_json_enabled",
-        "--value",
-        "true",
-      ],
-      expect.objectContaining({
-        ignoreError: true,
-        includeStderr: true,
-        timeout: POLICY_HINT_MAX_RUNTIME_TIMEOUT_MS,
-      }),
-    );
-    expect(captureOpenshell).toHaveBeenNthCalledWith(
-      2,
       [
         "logs",
         "-g",
@@ -89,9 +80,8 @@ describe("policy-denial hint runtime adapter integration (#5978)", () => {
     const timeout = Object.assign(new Error("OpenShell log read timed out"), {
       code: "ETIMEDOUT",
     });
-    captureOpenshell
-      .mockReturnValueOnce({ output: "", status: 0 })
-      .mockReturnValueOnce({ error: timeout, output: "", status: null });
+    enableAuditLogs.mockResolvedValue({ ok: true, value: undefined });
+    captureOpenshell.mockReturnValueOnce({ error: timeout, output: "", status: null });
     const sleep = vi.fn(async () => {});
 
     const hint = await maybeEmitPolicyDenialHint(
@@ -104,7 +94,7 @@ describe("policy-denial hint runtime adapter integration (#5978)", () => {
     );
 
     expect(hint).toBeNull();
-    expect(captureOpenshell).toHaveBeenCalledTimes(2);
+    expect(captureOpenshell).toHaveBeenCalledTimes(1);
     expect(sleep).not.toHaveBeenCalled();
   });
 });

src/lib/actions/sandbox/launch-readiness.ts

@@ -5,7 +5,7 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 
 import {
-  createSyncCliOpenShellSandboxPolicyReader,
+  createCliOpenShellSandboxPolicyReader,
   namedOpenShellGateway,
   type OpenShellSandboxError,
 } from "../../adapters/openshell/sandbox-policy-cli";
@@ -655,13 +655,13 @@ function classifyReceipt(
   return read.kind === "valid" ? "config" : read.kind;
 }
 
-function validateLivePolicy(
+async function validateLivePolicy(
   sandboxName: string,
   gatewayName: string,
   deps: LaunchReadinessDeps,
-): void {
+): Promise<void> {
   const capture = deps.capture ?? captureLaunchReadiness;
-  const result = createSyncCliOpenShellSandboxPolicyReader({
+  const result = await createCliOpenShellSandboxPolicyReader({
     capture: (args, options) =>
       capture(args, {
         ...options,
@@ -783,7 +783,7 @@ async function captureLaunchIdentity(
 
   const policyStartedAt = performance.now();
   try {
-    validateLivePolicy(sandboxName, gatewayName, deps);
+    await validateLivePolicy(sandboxName, gatewayName, deps);
   } catch (error) {
     recordLaunchReadinessObservationFailure(deps, "policy-get");
     throw error;