fix(agents,gateway): three subagent announce delivery failures in loopback token-auth setups

claude · claude · commit 429d29ed2cf8 · 2026-07-13T16:01:35.000Z
Rebased onto current main. Three narrow fixes for subagent completion announces failing to deliver over loopback gateway-client + token auth: - Fix 1 (gateway/call.ts): add an explicit `requireDeviceIdentity` opt-in so subagent completion calls retain device identity for operator-scope checks, instead of inferring it from the presence of scopes (which also fired for ordinary direct-local shared-token calls). Narrows the guard per review. - Fix 2 (embedded-agent-runner): after the sessions-yield abort-settle soft timeout, keep waiting (bounded by a hard cap) for the session file lock to release so the next turn does not hit a stale lock — without blocking forever if the settle itself stalls. - Fix 3 (embedded-agent-runner): also strip the sessions_yield context marker during abort cleanup so a subsequent announce re-run does not re-yield and get rejected as "did not produce a visible reply". Fixes #77807. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
diff --git a/src/agents/embedded-agent-runner/run/attempt.sessions-yield.ts b/src/agents/embedded-agent-runner/run/attempt.sessions-yield.ts
@@ -11,6 +11,12 @@ const SESSIONS_YIELD_INTERRUPT_CUSTOM_TYPE = "openclaw.sessions_yield_interrupt"
 const SESSIONS_YIELD_CONTEXT_CUSTOM_TYPE = "openclaw.sessions_yield";
 
 const SESSIONS_YIELD_ABORT_SETTLE_TIMEOUT_MS = resolveEmbeddedAbortSettleTimeoutMs();
+// Hard cap for the post-timeout settle wait. After the soft timeout we keep
+// waiting for the session file lock to release so the next turn does not hit a
+// stale lock, but must never block the next turn forever if the settle itself
+// stalls (e.g. a hung fs operation). Derived from the soft timeout so the
+// test-fast override applies to both.
+const SESSIONS_YIELD_ABORT_SETTLE_HARD_TIMEOUT_MS = SESSIONS_YIELD_ABORT_SETTLE_TIMEOUT_MS * 5;
 
 // Persist a hidden context reminder so the next turn knows why the runner stopped.
 function buildSessionsYieldContextMessage(message: string): string {
@@ -47,6 +53,25 @@ export async function waitForSessionsYieldAbortSettle(params: {
     log.warn(
       `sessions_yield abort settle timed out: runId=${params.runId} sessionId=${params.sessionId} timeoutMs=${SESSIONS_YIELD_ABORT_SETTLE_TIMEOUT_MS}`,
     );
+    // Continue waiting (bounded) for the settle to complete so the session file
+    // lock is released before the next turn starts. Without this the lock stays
+    // held and the next turn fails with "file lock stale", causing model
+    // fallback and visible error messages in the delivery channel.
+    let hardTimeout: NodeJS.Timeout | undefined;
+    const settled = await Promise.race([
+      params.settlePromise.then(() => true).catch(() => true),
+      new Promise<boolean>((resolve) => {
+        hardTimeout = setTimeout(() => resolve(false), SESSIONS_YIELD_ABORT_SETTLE_HARD_TIMEOUT_MS);
+      }),
+    ]);
+    if (hardTimeout) {
+      clearTimeout(hardTimeout);
+    }
+    if (!settled) {
+      log.warn(
+        `sessions_yield abort settle hard-timeout: runId=${params.runId} sessionId=${params.sessionId} hardTimeoutMs=${SESSIONS_YIELD_ABORT_SETTLE_HARD_TIMEOUT_MS} — proceeding without confirmed lock release`,
+      );
+    }
   }
 }
 
@@ -193,6 +218,19 @@ export function stripSessionsYieldArtifacts(activeSession: {
       strippedMessages.pop();
       continue;
     }
+    // Also strip the sessions_yield context marker. When a new incoming message
+    // aborts an active sessions_yield, this marker remains in the session. If a
+    // subagent completion announce then re-runs the agent to deliver the result,
+    // the agent sees the context message, responds via sessions_yield again, and
+    // the announce system rejects it as "did not produce a visible reply".
+    if (
+      last?.role === "custom" &&
+      "customType" in last &&
+      last.customType === SESSIONS_YIELD_CONTEXT_CUSTOM_TYPE
+    ) {
+      strippedMessages.pop();
+      continue;
+    }
     break;
   }
   if (strippedMessages.length !== activeSession.messages.length) {
@@ -238,7 +276,9 @@ export function stripSessionsYieldArtifacts(activeSession: {
       const isYieldInterruptMessage =
         entry.type === "custom_message" &&
         entry.customType === SESSIONS_YIELD_INTERRUPT_CUSTOM_TYPE;
-      return isYieldAbortAssistant || isYieldInterruptMessage;
+      const isYieldContextMessage =
+        entry.type === "custom_message" && entry.customType === SESSIONS_YIELD_CONTEXT_CUSTOM_TYPE;
+      return isYieldAbortAssistant || isYieldInterruptMessage || isYieldContextMessage;
     },
     {
       preserveTrailing: (entry) =>
diff --git a/src/agents/subagent-spawn.ts b/src/agents/subagent-spawn.ts
@@ -227,6 +227,11 @@ async function callSubagentGateway(
     params.scopes ?? (leastPrivilegeScopes.includes(ADMIN_SCOPE) ? [ADMIN_SCOPE] : undefined);
   const request = {
     ...params,
+    // Subagent calls negotiate explicit operator scopes against the paired
+    // device token, so the gateway needs the device identity attached even on
+    // loopback backend connections. Without this the completion announce fails
+    // with "missing scope: operator.write" (#77807).
+    requireDeviceIdentity: true,
     ...(scopes != null ? { scopes } : {}),
   };
   if (
diff --git a/src/gateway/call.test.ts b/src/gateway/call.test.ts
@@ -1023,6 +1023,22 @@ describe("callGateway url resolution", () => {
     expect(lastClientOptions?.deviceIdentity).toBeNull();
   });
 
+  it("keeps device identity for loopback backend scoped calls that opt in via requireDeviceIdentity", async () => {
+    setLocalLoopbackGatewayConfig();
+
+    await callGateway({
+      method: "agent",
+      scopes: ["operator.write"],
+      token: "explicit-token",
+      requireDeviceIdentity: true,
+    });
+
+    expect(lastClientOptions?.clientName).toBe(GATEWAY_CLIENT_NAMES.GATEWAY_CLIENT);
+    expect(lastClientOptions?.mode).toBe(GATEWAY_CLIENT_MODES.BACKEND);
+    expect(lastClientOptions?.scopes).toEqual(["operator.write"]);
+    expect(lastClientOptions?.deviceIdentity).toEqual(deviceIdentityState.value);
+  });
+
   it("labels default backend calls with the requested method", async () => {
     setLocalLoopbackGatewayConfig();
 
diff --git a/src/gateway/call.ts b/src/gateway/call.ts
@@ -91,6 +91,16 @@ type CallGatewayBaseOptions = {
   requiredStoredDeviceAuthScopes?: OperatorScope[];
   requireLocalBackendSharedAuth?: boolean;
   deviceIdentity?: DeviceIdentity | null;
+  /**
+   * Forces device identity to be attached even for BACKEND + GATEWAY_CLIENT
+   * loopback shared-token calls (which normally omit it). Set by internal
+   * callers that negotiate explicit operator scopes against the paired device
+   * token — e.g. subagent lifecycle/announce calls — so the gateway can verify
+   * those scopes. Without it, such calls fail with "missing scope: ...".
+   * See #77807. Does not affect direct-local shared-token calls that don't
+   * opt in.
+   */
+  requireDeviceIdentity?: boolean;
   instanceId?: string;
   minProtocol?: number;
   maxProtocol?: number;
@@ -493,6 +503,16 @@ function shouldOmitDeviceIdentityForGatewayCall(params: {
 }): boolean {
   const mode = params.opts.mode ?? GATEWAY_CLIENT_MODES.CLI;
   const clientName = params.opts.clientName ?? GATEWAY_CLIENT_NAMES.CLI;
+  // Callers that must verify explicit operator scopes against the paired
+  // device token (e.g. subagent completion announce) opt in via
+  // `requireDeviceIdentity`. Without device identity, those loopback backend
+  // calls fail with "missing scope: operator.write" even when the device has
+  // full scopes. Fixes #77807. This is intentionally narrow: it does not fire
+  // for ordinary scoped backend calls (which keep the direct-local
+  // shared-token contract of omitting device identity).
+  if (params.opts.requireDeviceIdentity === true) {
+    return false;
+  }
   // Inactive ambient credentials must not turn an auth-none CLI call device-less.
   // Omit identity only when the Gateway will actually authenticate the supplied secret.
   const hasSharedSecretAuth =
