Expose bounded native queue and Computer Use custody metadata

Read-only, fail-closed custody inspection through the existing app-server client.

Author: interpreterwork-automation[bot]

server/routes/agent.global-custody.test.ts

@@ -9,6 +9,7 @@ import { approvalManager } from '../approvalManager';
 const app = express();
 app.use('/api/agent', agentRouter);
 const url = '/api/agent/custody/global';
+const nativeUrl = '/api/agent/custody/native-global';
 const previousToken = process.env.WORKSTATION_WAKE_TOKEN;
 afterEach(() => {
   if (previousToken === undefined) delete process.env.WORKSTATION_WAKE_TOKEN;
@@ -17,6 +18,15 @@ afterEach(() => {
 });
 
 describe('global custody inventory', () => {
+  test('native and CUA inventory requires the same local bearer and rejects foreign origins', async () => {
+    process.env.WORKSTATION_WAKE_TOKEN = 'private-test-token';
+    expect((await request(app).get(nativeUrl)).status).toBe(401);
+    expect((await request(app).get(nativeUrl).set('Authorization', 'Bearer wrong')).status).toBe(401);
+    expect((await request(app).get(nativeUrl).set('Authorization', 'Bearer private-test-token')
+      .set('Origin', 'https://elsewhere.example')).status).toBe(401);
+    delete process.env.WORKSTATION_WAKE_TOKEN;
+    expect((await request(app).get(nativeUrl).set('Authorization', 'Bearer private-test-token')).status).toBe(401);
+  });
   test('fails closed without the configured bearer or from a foreign origin', async () => {
     process.env.WORKSTATION_WAKE_TOKEN = 'private-test-token';
     expect((await request(app).get(url)).status).toBe(401);

server/routes/agent.ts

@@ -8,6 +8,7 @@ import { getCustomInstructions } from '../configStore';
 import { getServerJWT } from '../lib/jwtStore';
 import { AgentModelConfig } from '../../shared/types/model';
 import { messageQueueStore } from '../utils/messageQueueStore';
+import { readCuaProcessLockCustody } from '../utils/cuaProcessLockMetadata';
 import { cleanupACPProvider } from '../utils/acpProvider';
 import { getCurrentWorkspace, requireExistingWorkspacePath } from '../utils/workspace';
 import { setCurrentTurnMessageId } from '../utils/turnMessageIdRegistry';
@@ -153,6 +154,18 @@ router.get('/custody/global', (req: Request, res: Response) => {
   }
 });
 
+router.get('/custody/native-global', async (req: Request, res: Response) => {
+  if (!wakeMutationAllowed(req) ||
+      !wakeTokenValid(process.env.WORKSTATION_WAKE_TOKEN, req.header('authorization')?.replace(/^Bearer /i, ''))) {
+    return res.status(401).json({ error: 'Authentication required.' });
+  }
+  try {
+    return res.json({ native: await getCodexService().readGlobalNativeCustody(), cua: readCuaProcessLockCustody() });
+  } catch {
+    return res.status(503).json({ error: 'Native or Computer Use custody inspection unavailable.' });
+  }
+});
+
 // An exact opaque ID is required. The thread must match its captured owner;
 // a CLI request with no thread binding needs an explicit unbound query instead.
 router.get('/custody/approvals/:approvalId', (req: Request, res: Response) => {

server/tools/builtin-tools/cua-driver/tools.ts

@@ -18,6 +18,7 @@ import type { BuiltinToolContext, BuiltinToolDefinition } from '../../builtinToo
 import type { ToolCallResponse } from '../../toolTypes';
 import { callWindowsCuaDriverTool } from './windowsUia';
 import type { BrowserControlStatus } from '../../../../shared/types/browserControl';
+import { CUA_PROCESS_LOCK_DIR, cuaLockOwnerForNewCall } from '../../../utils/cuaProcessLockMetadata';
 import {
   resolveCuaAccessPolicyMode,
   type CuaAccessPermissionKind,
@@ -51,7 +52,7 @@ const MAC_CUA_DRIVER_DAEMON_STARTUP_TIMEOUT_MS = 20_000;
 const MAC_CUA_DRIVER_TOOL_TIMEOUT_MS = 60_000;
 const MAC_CUA_DRIVER_ACTIVITY_TIMEOUT_MS = 5_000;
 const MAC_CUA_DRIVER_ACTIVITY_MAX_BUFFER = 10 * 1024 * 1024;
-const MAC_CUA_DRIVER_CALL_LOCK_DIR = path.join(os.tmpdir(), 'interpreter-desktop-driver-call.lock');
+const MAC_CUA_DRIVER_CALL_LOCK_DIR = CUA_PROCESS_LOCK_DIR;
 const MAC_CUA_DRIVER_CALL_LOCK_STALE_MS = 3 * MAC_CUA_DRIVER_TOOL_TIMEOUT_MS;
 const MAC_SELECT_OPTION_MENU_WAIT_MS = 3_000;
 const MAC_SELECT_OPTION_MENU_POLL_MS = 120;
@@ -3032,15 +3033,12 @@ async function withMacCuaDriverSerialized<T>(fn: () => Promise<T>): Promise<T> {
   return run;
 }
 
-async function acquireMacCuaDriverProcessLock(lockDir = MAC_CUA_DRIVER_CALL_LOCK_DIR): Promise<() => void> {
+async function acquireMacCuaDriverProcessLock(lockDir = MAC_CUA_DRIVER_CALL_LOCK_DIR, action = 'unknown', threadId?: string): Promise<() => void> {
   while (true) {
     try {
       fs.mkdirSync(lockDir);
       try {
-        fs.writeFileSync(path.join(lockDir, 'owner'), JSON.stringify({
-          pid: process.pid,
-          acquiredAt: Date.now(),
-        }));
+        fs.writeFileSync(path.join(lockDir, 'owner'), JSON.stringify(cuaLockOwnerForNewCall(action, threadId)));
       } catch {
         // The directory itself is the atomic lock; owner metadata is best-effort.
       }
@@ -3114,9 +3112,11 @@ export async function withMacCuaDriverApprovalAndProcessLock<T>(
   approve: () => Promise<void>,
   invoke: () => Promise<T>,
   lockDir = MAC_CUA_DRIVER_CALL_LOCK_DIR,
+  action = 'unknown',
+  threadId?: string,
 ): Promise<T> {
   await approve();
-  const release = await acquireMacCuaDriverProcessLock(lockDir);
+  const release = await acquireMacCuaDriverProcessLock(lockDir, action, threadId);
   try {
     return await withMacCuaDriverSerialized(invoke);
   } finally {
@@ -3425,6 +3425,9 @@ async function callCuaDriverCli(
     return withMacCuaDriverApprovalAndProcessLock(
       () => requestApproval(toolName, approvalArgs ?? args, context),
       () => callMacCuaDriverCli(toolName, args, context, imageOutputPath),
+      MAC_CUA_DRIVER_CALL_LOCK_DIR,
+      toolName,
+      context?.threadId,
     );
   }
   await requestApproval(toolName, approvalArgs ?? args, context);

server/utils/cuaProcessLockMetadata.test.ts

@@ -0,0 +1,40 @@
+import { afterEach, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { cuaLockOwnerForNewCall, readCuaProcessLockCustody } from './cuaProcessLockMetadata';
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cua-custody-test-'));
+afterEach(() => { for (const file of fs.readdirSync(root)) fs.rmSync(path.join(root, file), { recursive: true, force: true }); });
+
+test('distinguishes clear from legacy held lock with unknown action and identity', () => {
+  const lock = path.join(root, 'lock');
+  expect(readCuaProcessLockCustody(lock)).toMatchObject({ held: false, ownerKnown: true });
+  fs.mkdirSync(lock);
+  fs.writeFileSync(path.join(lock, 'owner'), JSON.stringify({ pid: process.pid, acquiredAt: 123 }));
+  expect(readCuaProcessLockCustody(lock)).toMatchObject({ held: true, ownerKnown: true,
+    action: null, threadId: null, processIdentityVerified: false });
+});
+
+test('records action and thread but never arguments or process command line', () => {
+  const lock = path.join(root, 'lock');
+  const owner = cuaLockOwnerForNewCall('get_app_state', '01a0d435-bb2b-7047-afe7-0a639be8e5d4');
+  fs.mkdirSync(lock);
+  fs.writeFileSync(path.join(lock, 'owner'), JSON.stringify(owner));
+  const result = readCuaProcessLockCustody(lock);
+  expect(result).toMatchObject({ held: true, action: 'get_app_state', threadId: owner.threadId });
+  expect(JSON.stringify(result)).not.toContain('args');
+  if (process.platform === 'linux') expect(result.processIdentityVerified).toBe(true);
+});
+
+test('never follows a symlinked owner or lock directory', () => {
+  const target = path.join(root, 'target');
+  const lock = path.join(root, 'lock');
+  fs.writeFileSync(target, JSON.stringify(cuaLockOwnerForNewCall('click')));
+  fs.mkdirSync(lock);
+  fs.symlinkSync(target, path.join(lock, 'owner'));
+  expect(readCuaProcessLockCustody(lock)).toMatchObject({ held: true, ownerKnown: false });
+  fs.rmSync(lock, { recursive: true, force: true });
+  fs.symlinkSync(root, lock);
+  expect(() => readCuaProcessLockCustody(lock)).toThrow('Invalid CUA lock directory');
+});

server/utils/cuaProcessLockMetadata.ts

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const CUA_PROCESS_LOCK_DIR = path.join(os.tmpdir(), 'interpreter-desktop-driver-call.lock');
+
+function linuxStartTicks(pid: number): string | null {
+  if (process.platform !== 'linux') return null;
+  try {
+    const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+    const fields = stat.slice(stat.lastIndexOf(')') + 2).trim().split(/\s+/);
+    const ticks = fields[19]; // /proc stat field 22; first remaining field is 3.
+    return /^\d+$/.test(ticks ?? '') ? ticks : null;
+  } catch { return null; }
+}
+
+export function cuaLockOwnerForNewCall(action: string, threadId?: string) {
+  return {
+    pid: process.pid,
+    acquiredAt: Date.now(),
+    processStartTicks: linuxStartTicks(process.pid),
+    action: /^[a-z_]{1,80}$/.test(action) ? action : null,
+    threadId: threadId && /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(threadId) ? threadId : null,
+  };
+}
+
+/** Metadata only. Unknown identity is never interpreted as a clear lock. */
+export function readCuaProcessLockCustody(lockDir = CUA_PROCESS_LOCK_DIR) {
+  let stat: fs.Stats;
+  try { stat = fs.lstatSync(lockDir); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { held: false, ownerKnown: true, pid: null, action: null, threadId: null, acquiredAt: null, processIdentityVerified: null };
+    }
+    throw error;
+  }
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('Invalid CUA lock directory');
+  const unknown = { held: true, ownerKnown: false, pid: null, action: null, threadId: null, acquiredAt: null, processIdentityVerified: false };
+  try {
+    const ownerPath = path.join(lockDir, 'owner');
+    const ownerStat = fs.lstatSync(ownerPath);
+    if (!ownerStat.isFile() || ownerStat.isSymbolicLink() || ownerStat.size > 1024) return unknown;
+    const owner = JSON.parse(fs.readFileSync(ownerPath, 'utf8')) as Record<string, unknown>;
+    if (!Number.isSafeInteger(owner.pid) || (owner.pid as number) < 1) return unknown;
+    const pid = owner.pid as number;
+    let alive = false;
+    try { process.kill(pid, 0); alive = true; }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === 'EPERM') alive = true; }
+    const ticks = linuxStartTicks(pid);
+    const processIdentityVerified = alive && typeof owner.processStartTicks === 'string' && ticks !== null && owner.processStartTicks === ticks;
+    return {
+      held: true, ownerKnown: true, pid,
+      action: typeof owner.action === 'string' && /^[a-z_]{1,80}$/.test(owner.action) ? owner.action : null,
+      threadId: typeof owner.threadId === 'string' && /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(owner.threadId) ? owner.threadId : null,
+      acquiredAt: typeof owner.acquiredAt === 'number' && Number.isSafeInteger(owner.acquiredAt) ? owner.acquiredAt : null,
+      processIdentityVerified,
+    };
+  } catch { return unknown; }
+}

src/lib/codex/app-server-client.ts

@@ -2362,6 +2362,10 @@ export class CodexAppServerClient {
     return this.rpcRequest(CLIENT_METHOD.threadQueueList, params);
   }
 
+  async threadLoadedList(params: v2.ThreadLoadedListParams = {}): Promise<v2.ThreadLoadedListResponse> {
+    return this.rpcRequest(CLIENT_METHOD.threadLoadedList, params);
+  }
+
   async threadSetName(params: v2.ThreadSetNameParams): Promise<v2.ThreadSetNameResponse> {
     return this.rpcRequest(CLIENT_METHOD.threadSetName, params);
   }

src/lib/codex/protocol.ts

@@ -48,6 +48,7 @@ export const CLIENT_METHOD = {
   threadList: "thread/list",
   threadRead: "thread/read",
   threadQueueList: "thread/queue/list",
+  threadLoadedList: "thread/loaded/list",
   modelList: "model/list",
   interpreterProviderList: "interpreter/provider/list",
   interpreterProviderSet: "interpreter/provider/set",
@@ -250,6 +251,10 @@ export type RequestMap = {
     params: { threadId: string; cursor?: string | null; limit?: number | null };
     result: { data: Array<{ id: string; clientUserMessageId: string; input: unknown[] }>; nextCursor: string | null };
   };
+  [CLIENT_METHOD.threadLoadedList]: {
+    params: v2.ThreadLoadedListParams;
+    result: v2.ThreadLoadedListResponse;
+  };
   [CLIENT_METHOD.modelList]: {
     params: v2.ModelListParams;
     result: v2.ModelListResponse;

src/lib/codex/service.test.ts

@@ -29,6 +29,47 @@ function createTurn(id: string, status: v2.TurnStatus = "inProgress"): v2.Turn {
 }
 
 describe('native custody metadata', () => {
+  test('enumerates loaded and persisted native queues without input, then verifies stable IDs', async () => {
+    const id = '01a0d435-bb2b-7047-afe7-0a639be8e5d4';
+    const client = createFakeClient({}).client;
+    client.threadLoadedList = async () => ({ data: [id], nextCursor: null });
+    client.threadList = async () => ({ data: [{ id } as v2.Thread], nextCursor: null, backwardsCursor: null });
+    let calls = 0;
+    client.threadQueueList = async () => {
+      calls++;
+      return { data: [{ id: 'queue_1', clientUserMessageId: 'opaque_1', input: [{ text: 'PRIVATE' }] }], nextCursor: null };
+    };
+    const result = await new CodexService(client).readGlobalNativeCustody();
+    assert.equal(result.scope, 'all-enumerated-unarchived-native-threads');
+    assert.equal(result.atomic, false);
+    assert.equal(result.queuedSubmissionCount, 1);
+    assert.deepEqual(result.loadedThreadIds, [id]);
+    assert.equal(calls, 2);
+    assert.doesNotMatch(JSON.stringify(result), /PRIVATE/);
+  });
+
+  test('rejects a changing native queue rather than claiming safe custody', async () => {
+    const id = '01a0d435-bb2b-7047-afe7-0a639be8e5d4';
+    const client = createFakeClient({}).client;
+    client.threadLoadedList = async () => ({ data: [id], nextCursor: null });
+    client.threadList = async () => ({ data: [{ id } as v2.Thread], nextCursor: null, backwardsCursor: null });
+    let calls = 0;
+    client.threadQueueList = async () => ({ data: calls++ === 0
+      ? [] : [{ id: 'queue_2', clientUserMessageId: 'opaque_2', input: [] }], nextCursor: null });
+    await assert.rejects(new CodexService(client).readGlobalNativeCustody(), /changed/);
+  });
+
+  test('rejects a loaded native thread omitted by persisted inventory', async () => {
+    const client = createFakeClient({}).client;
+    client.threadLoadedList = async () => ({ data: ['01a0d435-bb2b-7047-afe7-0a639be8e5d4'], nextCursor: null });
+    await assert.rejects(new CodexService(client).readGlobalNativeCustody(), /missing/);
+  });
+
+  test('does not report an empty global queue when native listing is unsupported', async () => {
+    const client = createFakeClient({}).client;
+    client.threadLoadedList = async () => { throw new Error('native method unavailable'); };
+    await assert.rejects(new CodexService(client).readGlobalNativeCustody(), /unavailable/);
+  });
   test('pages native queue through the existing client without returning input', async () => {
     const fake = createFakeClient({});
     const client = fake.client;
@@ -286,6 +327,9 @@ function createFakeClient(overrides: {
       calls.threadListParams.push(params ?? {});
       return { data: [], nextCursor: null };
     },
+    async threadLoadedList() {
+      return { data: [], nextCursor: null };
+    },
     async threadRead(params) {
       calls.threadReadParams.push(params);
       if (overrides.threadRead) {