overlord-cli 0.2606010644.0 → 0.2606011152.0

package/README.md

@@ -74,6 +74,9 @@ ovld protocol search-tickets --query "auth refactor" --status next-up,execute
 ovld protocol update --session-key <session-key> --ticket-id <ticket_id> --summary "Working on it" --phase execute
 ovld protocol heartbeat --session-key <session-key> --ticket-id <ticket_id> --phase execute --percent 50 --note "Running tests"
 ovld runner start
+ovld runner status
+ovld runner clear <objective_id>
+ovld runner clear-all
 ovld setup
 ovld setup codex
 ovld setup claude
@@ -148,12 +151,14 @@ Agents can find docs here: https://www.ovld.ai/docs/for-agents
 - `attachment-upload-file` - prepare, upload, and finalize a local objective attachment in one command
 - `get-device` / `update-device` - register the caller machine (per organization + user + fingerprint) and rename its label
 - `list-project-resources` / `add-project-resource` / `update-project-resource` - manage filesystem directories tied to a project device
-- `request-execution` / `claim-execution` / `complete-execution-launch` / `fail-execution-launch` - durable runner queue operations used by auto-advance and manual Run
+- `request-execution` / `claim-execution` / `list-execution-requests` / `clear-execution-requests` / `complete-execution-launch` / `fail-execution-launch` - durable runner queue operations used by auto-advance and manual Run
 - `list-organizations` - list every organization the authenticated user (or agent token) belongs to; the runner uses this to poll all of your organizations, not just the one stored at login
 
 Devices are keyed by **(organization, user, fingerprint)** so the same physical workstation can appear once per org session.
 
-`ovld runner start` keeps a foreground runner alive for CLI-only or remote hosts. It claims compatible execution requests for the current device and launches the assigned agent/model with `ovld launch`; `ovld runner once` claims at most one request and exits. By default a single runner drains queued requests from **every organization you belong to**, so you do not need one runner per org. Pin it to a single org with `--organization-id <id>` or `OVERLORD_ORGANIZATION_ID`.
+`ovld runner start` keeps a foreground runner alive for CLI-only or remote hosts. It claims compatible execution requests for the current device and launches the assigned agent/model with `ovld launch`; `ovld runner once` claims at most one request and exits. `ovld runner status` now prints the local device record plus the active queue visible to that runner. `ovld runner clear <objective_id>` clears one queued objective, and `ovld runner clear-all` clears every active queue row visible to the caller. By default a single runner drains queued requests from **every organization you belong to**, so you do not need one runner per org. Pin it to a single org with `--organization-id <id>` or `OVERLORD_ORGANIZATION_ID`.
+
+If you are troubleshooting "why is `ovld runner` randomly executing", the runner is usually claiming a request that was already queued by manual Run or auto-advance. Inspect the queue with `ovld runner status`, then clear the specific objective with `ovld runner clear 8974e557-bec4-4984-b12c-be46bd63207c` or `ovld protocol clear-execution-requests --objective-id 8974e557-bec4-4984-b12c-be46bd63207c`.
 
 Use `create` for future work you want to track, `prompt` for work that should start immediately, and `record-work` for work that was already completed in chat and now needs a review ticket plus feed post. Use multiple tickets when prompts represent different features or goals; use `add-objectives` or `--objectives-json '[{"objective":"Step one"},{"objective":"Step two"}]'` when prompts are sequential steps toward the same feature or goal.
 

package/bin/_cli/protocol.mjs

@@ -85,6 +85,18 @@ async function resolveProtocolMetadata(flags = {}, base = {}) {
     metadata.model = modelIdentifier;
   }
 
+  // Thread the originating execution request id (set by the runner via
+  // OVERLORD_EXECUTION_REQUEST_ID, or an explicit flag) into attach metadata so
+  // the server marks that exact request `launched` instead of falling back to
+  // matching by objective.
+  const executionRequestId =
+    (typeof flags['execution-request-id'] === 'string'
+      ? flags['execution-request-id'].trim()
+      : '') || process.env.OVERLORD_EXECUTION_REQUEST_ID?.trim();
+  if (executionRequestId) {
+    metadata.executionRequestId = executionRequestId;
+  }
+
   const snapshot = await resolveSnapshotContext(flags);
   if (snapshot) {
     metadata.snapshot = snapshot;
@@ -2067,6 +2079,58 @@ async function protocolListOrganizations(args) {
   console.log(JSON.stringify(data, null, 2));
 }
 
+async function protocolListExecutionRequests(args) {
+  const flags = parseFlags(args);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags);
+  const timeoutMs = resolveTimeout(flags);
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/list-execution-requests',
+    {
+      ...(typeof flags['device-fingerprint'] === 'string'
+        ? { deviceFingerprint: flags['device-fingerprint'] }
+        : {}),
+      ...(typeof flags['project-id'] === 'string' ? { projectId: flags['project-id'] } : {})
+    },
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function protocolClearExecutionRequests(args) {
+  const flags = parseFlags(args);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags);
+  const timeoutMs = resolveTimeout(flags);
+
+  const clearAll = flags['clear-all'] === true || flags['clear-all'] === 'true';
+  const objectiveId = typeof flags['objective-id'] === 'string' ? flags['objective-id'].trim() : '';
+  if (!clearAll && !objectiveId) {
+    console.error('Error: --objective-id is required unless --clear-all is set');
+    process.exit(1);
+  }
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/clear-execution-requests',
+    {
+      ...(objectiveId ? { objectiveId } : {}),
+      ...(clearAll ? { clearAll: true } : {}),
+      ...(typeof flags['project-id'] === 'string' ? { projectId: flags['project-id'] } : {})
+    },
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+}
+
 async function protocolCompleteExecutionLaunch(args) {
   const flags = parseFlags(args);
   const { platformUrl, bearerToken, localSecret, organizationId } =
@@ -2663,6 +2727,8 @@ Subcommands:
   request-execution         Queue an objective for local/remote runner execution
   claim-execution           Claim one queued execution request for this device
   list-organizations        List organizations the authenticated user belongs to
+  list-execution-requests   List active execution requests in the runner queue
+  clear-execution-requests  Clear active execution requests by objective or wholesale
   complete-execution-launch Mark a claimed execution request launched
   fail-execution-launch     Mark a claimed execution request failed
   permission-request        Notify Overlord that the agent is requesting tool permission
@@ -3164,6 +3230,25 @@ list-organizations:
     The runner uses this to poll all of your organizations, not just the one
     stored at login. Takes no required flags.
 
+list-execution-requests:
+  Purpose:
+    List active execution requests ('queued', 'claimed', 'launching') visible to
+    the caller. When --device-fingerprint is provided, queued rows are filtered
+    to work this execution target could claim and in-flight rows are limited to
+    rows already claimed by this target.
+  Optional:
+    --device-fingerprint <fp>  Filter queue visibility to one execution target
+    --project-id <uuid>        Restrict to one project
+
+clear-execution-requests:
+  Purpose:
+    Clear active execution requests from the runner queue by marking them failed.
+  Required:
+    --objective-id <uuid>      Clear one objective's active request
+    or: --clear-all            Clear every active request visible to the caller
+  Optional:
+    --project-id <uuid>        Restrict clear-all to one project
+
 complete-execution-launch:
   Required:
     --request-id <uuid>        (or EXECUTION_REQUEST_ID env var)
@@ -3210,6 +3295,9 @@ Examples:
   ovld protocol request-execution --ticket-id 1:899 --agent codex --requested-from manual_run
   ovld protocol claim-execution --device-fingerprint $OVERLORD_DEVICE_FINGERPRINT
   ovld protocol list-organizations
+  ovld protocol list-execution-requests --device-fingerprint $OVERLORD_DEVICE_FINGERPRINT
+  ovld protocol clear-execution-requests --objective-id <objective-uuid>
+  ovld protocol clear-execution-requests --clear-all
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --summary "Done"
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --summary "Done" --artifacts-file ./artifacts.json
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --payload-json '{"summary":"Done","artifacts":[{"type":"note","label":"Delivery","content":"..."}]}'
@@ -3333,6 +3421,14 @@ EOF
     await protocolListOrganizations(args);
     return;
   }
+  if (subcommand === 'list-execution-requests') {
+    await protocolListExecutionRequests(args);
+    return;
+  }
+  if (subcommand === 'clear-execution-requests') {
+    await protocolClearExecutionRequests(args);
+    return;
+  }
   if (subcommand === 'complete-execution-launch') {
     await protocolCompleteExecutionLaunch(args);
     return;

package/bin/_cli/runner.mjs

@@ -22,6 +22,8 @@ function printRunnerHelp(primaryCommand = 'ovld') {
   ${primaryCommand} runner once [options]
   ${primaryCommand} runner start [options]
   ${primaryCommand} runner status [options]
+  ${primaryCommand} runner clear <objective_id> [options]
+  ${primaryCommand} runner clear-all [options]
 
 Options:
   --device-fingerprint <fp>  Override runner device identity
@@ -114,6 +116,37 @@ function claimExecution(flags, deviceFingerprint, organizationId) {
   return protocolJson('claim-execution', args, { OVERLORD_DEVICE_FINGERPRINT: deviceFingerprint });
 }
 
+function listExecutionRequests(flags, deviceFingerprint, organizationId) {
+  const args = ['--device-fingerprint', deviceFingerprint];
+  if (organizationId) {
+    args.push('--organization-id', String(organizationId));
+  }
+  if (typeof flags['project-id'] === 'string') {
+    args.push('--project-id', flags['project-id']);
+  }
+  return protocolJson('list-execution-requests', args, {
+    OVERLORD_DEVICE_FINGERPRINT: deviceFingerprint
+  });
+}
+
+function clearExecutionRequests(flags, deviceFingerprint, organizationId, options = {}) {
+  const args = [];
+  if (organizationId) {
+    args.push('--organization-id', String(organizationId));
+  }
+  if (typeof flags['project-id'] === 'string') {
+    args.push('--project-id', flags['project-id']);
+  }
+  if (options.clearAll) {
+    args.push('--clear-all');
+  } else if (options.objectiveId) {
+    args.push('--objective-id', options.objectiveId);
+  }
+  return protocolJson('clear-execution-requests', args, {
+    OVERLORD_DEVICE_FINGERPRINT: deviceFingerprint
+  });
+}
+
 function listOrganizationIds(deviceFingerprint) {
   const data = protocolJson('list-organizations', [], {
     OVERLORD_DEVICE_FINGERPRINT: deviceFingerprint
@@ -138,13 +171,17 @@ function resolvePinnedOrganizationId(flags) {
 const ORGANIZATION_REFRESH_MS = 60_000;
 
 /**
- * Resolves which organizations a poll pass should claim from.
+ * Resolves which organizations a fan-out pass (list / clear-all) should act on.
  *
  * - When the user pins an org (`--organization-id` flag or
- *   `OVERLORD_ORGANIZATION_ID`), only that org is polled.
- * - Otherwise the runner discovers every org the authenticated user belongs to
- *   and polls each one. If discovery fails or returns nothing, it falls back to
- *   the credential default (an empty scope id) so behavior never regresses.
+ *   `OVERLORD_ORGANIZATION_ID`), only that org is used.
+ * - Otherwise the runner discovers every org the authenticated user belongs to.
+ *   If discovery fails or returns nothing, it falls back to the credential
+ *   default (an empty scope id) so behavior never regresses.
+ *
+ * NOTE: this is for the per-org fan-out commands. The claim poll uses
+ * {@link createClaimOrganizationScope}, which is org-agnostic — the server's
+ * `claim-execution` is authoritative and spans the user's target-sharing orgs.
  */
 export function createOrganizationScope(flags, deviceFingerprint) {
   const pinned = resolvePinnedOrganizationId(flags);
@@ -178,6 +215,17 @@ export function createOrganizationScope(flags, deviceFingerprint) {
   };
 }
 
+/**
+ * Resolves the org scope for the claim poll (G3). A pinned org still scopes the
+ * poll; otherwise the runner does a single org-agnostic poll (empty scope) and
+ * lets the server claim across every org the user belongs to that shares the
+ * claiming target — no org discovery or per-org looping needed.
+ */
+export function createClaimOrganizationScope(flags) {
+  const pinned = resolvePinnedOrganizationId(flags);
+  return { pinned: Boolean(pinned), resolve: () => [pinned || ''] };
+}
+
 function completeLaunch(requestId, deviceFingerprint) {
   protocolJson(
     'complete-execution-launch',
@@ -243,11 +291,19 @@ function normalizeRunnerTerminalProfile(value) {
   };
 }
 
-function buildRunnerLaunchShellCommand(args, deviceFingerprint) {
-  return [
-    `export OVERLORD_DEVICE_FINGERPRINT=${shellQuote(deviceFingerprint)}`,
+function buildRunnerLaunchShellCommand(args, deviceFingerprint, executionRequestId) {
+  const lines = [`export OVERLORD_DEVICE_FINGERPRINT=${shellQuote(deviceFingerprint)}`];
+  // Terminal-profile launches run this generated script in a fresh shell, so the
+  // request id must be exported here too (the direct-spawn path inherits it via
+  // the child env). Without it, attach in the new terminal falls back to
+  // objective matching.
+  if (executionRequestId) {
+    lines.push(`export OVERLORD_EXECUTION_REQUEST_ID=${shellQuote(executionRequestId)}`);
+  }
+  lines.push(
     `exec ${shellQuote(process.execPath)} ${[OVLD_ENTRY, ...args].map(shellQuote).join(' ')}`
-  ].join('\n');
+  );
+  return lines.join('\n');
 }
 
 function writeRunnerLaunchScript(launchCommand) {
@@ -342,7 +398,7 @@ export function buildRunnerTerminalOpenCommand(
 
 function spawnLaunchProcess(args, claim, deviceFingerprint) {
   const spawnImpl = runnerTestHooks.spawn ?? spawn;
-  const launchCommand = buildRunnerLaunchShellCommand(args, deviceFingerprint);
+  const launchCommand = buildRunnerLaunchShellCommand(args, deviceFingerprint, claim.request?.id);
   const terminalCommand = buildRunnerTerminalOpenCommand(
     claim.launch?.runnerTerminalProfile,
     launchCommand,
@@ -433,7 +489,7 @@ export async function launchClaimedRequest(claim, deviceFingerprint) {
 }
 
 export async function runOnce(flags, deviceFingerprint, organizationScope) {
-  const scope = organizationScope ?? createOrganizationScope(flags, deviceFingerprint);
+  const scope = organizationScope ?? createClaimOrganizationScope(flags);
   const organizationIds = scope.resolve();
 
   let launchedAny = false;
@@ -466,6 +522,58 @@ function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+async function collectQueue(flags, deviceFingerprint, organizationScope) {
+  const scope = organizationScope ?? createOrganizationScope(flags, deviceFingerprint);
+  const queue = [];
+  const errors = [];
+
+  for (const organizationId of scope.resolve()) {
+    try {
+      const data = listExecutionRequests(flags, deviceFingerprint, organizationId);
+      for (const request of data.requests ?? []) {
+        queue.push({
+          organizationId: organizationId || null,
+          ...request
+        });
+      }
+    } catch (error) {
+      errors.push({
+        organizationId: organizationId || null,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+
+  return { queue, errors, pinned: scope.pinned };
+}
+
+async function clearQueue(flags, deviceFingerprint, organizationScope, options) {
+  const scope = organizationScope ?? createOrganizationScope(flags, deviceFingerprint);
+  let clearedCount = 0;
+  const cleared = [];
+  const errors = [];
+
+  for (const organizationId of scope.resolve()) {
+    try {
+      const data = clearExecutionRequests(flags, deviceFingerprint, organizationId, options);
+      clearedCount += data.clearedCount ?? 0;
+      for (const request of data.requests ?? []) {
+        cleared.push({
+          organizationId: organizationId || null,
+          ...request
+        });
+      }
+    } catch (error) {
+      errors.push({
+        organizationId: organizationId || null,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+
+  return { clearedCount, cleared, errors, pinned: scope.pinned };
+}
+
 export async function runRunnerCommand(subcommand, args, primaryCommand = 'ovld') {
   if (!subcommand || subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
     printRunnerHelp(primaryCommand);
@@ -476,6 +584,7 @@ export async function runRunnerCommand(subcommand, args, primaryCommand = 'ovld'
   const deviceFingerprint = readOrCreateDeviceFingerprint(flags);
 
   if (subcommand === 'status') {
+    const organizationScope = createOrganizationScope(flags, deviceFingerprint);
     const data = protocolJson(
       'get-device',
       [
@@ -488,7 +597,38 @@ export async function runRunnerCommand(subcommand, args, primaryCommand = 'ovld'
       ],
       { OVERLORD_DEVICE_FINGERPRINT: deviceFingerprint }
     );
-    console.log(JSON.stringify({ ok: true, device: data.device }, null, 2));
+    const queue = await collectQueue(flags, deviceFingerprint, organizationScope);
+    console.log(
+      JSON.stringify(
+        {
+          ok: true,
+          device: data.device,
+          queue: queue.queue,
+          queueErrors: queue.errors
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+
+  if (subcommand === 'clear') {
+    const objectiveId = typeof args[0] === 'string' && !args[0].startsWith('--') ? args[0] : '';
+    if (!objectiveId) {
+      console.error(`Usage: ${primaryCommand} runner clear <objective_id> [options]`);
+      process.exit(1);
+    }
+    const remainingArgs = objectiveId ? args.slice(1) : args;
+    const clearFlags = parseFlags(remainingArgs);
+    const queue = await clearQueue(clearFlags, deviceFingerprint, null, { objectiveId });
+    console.log(JSON.stringify({ ok: true, ...queue }, null, 2));
+    return;
+  }
+
+  if (subcommand === 'clear-all') {
+    const queue = await clearQueue(flags, deviceFingerprint, null, { clearAll: true });
+    console.log(JSON.stringify({ ok: true, ...queue }, null, 2));
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "0.2606010644.0",
+  "version": "0.2606011152.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "homepage": "https://www.ovld.ai/docs/",
   "type": "module",

package/plugins/antigravity/scripts/overlord-mcp.mjs

@@ -1054,6 +1054,40 @@ const tools = [
     }),
     subcommand: 'claim-execution'
   },
+  {
+    name: 'list_execution_requests',
+    description: 'List active execution requests in the local runner queue.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        device_fingerprint: { type: 'string' },
+        project_id: { type: 'string' }
+      }
+    },
+    toCliFlags: args => ({
+      'device-fingerprint': args.device_fingerprint,
+      'project-id': args.project_id
+    }),
+    subcommand: 'list-execution-requests'
+  },
+  {
+    name: 'clear_execution_requests',
+    description: 'Clear active execution requests from the local runner queue.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        objective_id: { type: 'string' },
+        clear_all: { type: 'boolean' },
+        project_id: { type: 'string' }
+      }
+    },
+    toCliFlags: args => ({
+      'objective-id': args.objective_id,
+      ...(args.clear_all ? { 'clear-all': true } : {}),
+      'project-id': args.project_id
+    }),
+    subcommand: 'clear-execution-requests'
+  },
   {
     name: 'complete_execution_launch',
     description: 'Mark a claimed execution request as launched.',

package/plugins/claude/skills/overlord-ticket/reference/mcp.md

@@ -4,7 +4,7 @@
 - Hosted Overlord MCP (`/functions/v1/mcp`) uses camelCase JSON keys (`ticketId`, `sessionKey`, `deviceFingerprint`) matching `POST /api/protocol/*` bodies. The local shim uses snake_case keys mapped to CLI flags (`ticket_id`, `session_key`, `device_fingerprint`). Some local-only operations (`connect`, `load_ticket_context`, `revert`, `prompt`, runner queue tools) intentionally remain out of hosted MCP for now.
 - `discover_project` accepts an explicit project id (`projectId` hosted, `project_id` local shim) or a working directory (`workingDirectory` hosted, `working_directory` local shim). When resolving by directory and a device fingerprint is available, include `deviceFingerprint` / `device_fingerprint` so resource-directory matching prefers the current device.
 - `permission-request` is invoked by the Claude Code permission hook installed by the bundle. Agents do not normally call it directly.
-- Execution request tools (`request_execution`, `claim_execution`, `complete_execution_launch`, `fail_execution_launch`) back the local runner queue. Agents normally work tickets with `attach`/`update`/`deliver`; runner processes use these queue tools.
+- Execution request tools (`request_execution`, `claim_execution`, `list_execution_requests`, `clear_execution_requests`, `complete_execution_launch`, `fail_execution_launch`) back the local runner queue. Agents normally work tickets with `attach`/`update`/`deliver`; runner processes use these queue tools.
 - `record_change_rationales` (MCP) and `ovld protocol record-change-rationales` (CLI) both write to the same `file_changes` table. The dedicated CLI route is `POST /api/protocol/record-change-rationales`.
 - Objective attachment tools follow the `<verb>_<noun>` MCP naming: `list_attachments`, `prepare_attachment_upload`, `finalize_attachment_upload`, `get_attachment_download_url`, `upload_attachment_file`. CLI commands use `attachment-*`. `ticket_id` / `ticketId` is optional for attachment calls when the objective or attachment id lets the server derive ticket scope.
 - "Artifacts" in `deliver` are the structured records an agent submits at delivery time (next_steps, test_results, migration, decision, note, url) — not user-uploaded files. Files attached by users live on objectives via the attachment tools above.

package/plugins/cursor/skills/overlord-ticket/reference/mcp.md

@@ -4,7 +4,7 @@
 - Hosted Overlord MCP (`/functions/v1/mcp`) uses camelCase JSON keys (`ticketId`, `sessionKey`, `deviceFingerprint`) matching `POST /api/protocol/*` bodies. The local shim uses snake_case keys mapped to CLI flags (`ticket_id`, `session_key`, `device_fingerprint`). Some local-only operations (`connect`, `load_ticket_context`, `revert`, `prompt`, runner queue tools) intentionally remain out of hosted MCP for now.
 - `discover_project` accepts an explicit project id (`projectId` hosted, `project_id` local shim) or a working directory (`workingDirectory` hosted, `working_directory` local shim). When resolving by directory and a device fingerprint is available, include `deviceFingerprint` / `device_fingerprint` so resource-directory matching prefers the current device.
 - `permission-request` is invoked by the Cursor permission hook installed by the bundle. Agents do not normally call it directly.
-- Execution request tools (`request_execution`, `claim_execution`, `complete_execution_launch`, `fail_execution_launch`) back the local runner queue. Agents normally work tickets with `attach`/`update`/`deliver`; runner processes use these queue tools.
+- Execution request tools (`request_execution`, `claim_execution`, `list_execution_requests`, `clear_execution_requests`, `complete_execution_launch`, `fail_execution_launch`) back the local runner queue. Agents normally work tickets with `attach`/`update`/`deliver`; runner processes use these queue tools.
 - `record_change_rationales` (MCP) and `ovld protocol record-change-rationales` (CLI) both write to the same `file_changes` table. The dedicated CLI route is `POST /api/protocol/record-change-rationales`.
 - Objective attachment tools follow the `<verb>_<noun>` MCP naming: `list_attachments`, `prepare_attachment_upload`, `finalize_attachment_upload`, `get_attachment_download_url`, `upload_attachment_file`. CLI commands use `attachment-*`. `ticket_id` / `ticketId` is optional for attachment calls when the objective or attachment id lets the server derive ticket scope.
 - "Artifacts" in `deliver` are the structured records an agent submits at delivery time (next_steps, test_results, migration, decision, note, url) — not user-uploaded files. Files attached by users live on objectives via the attachment tools above.

package/plugins/overlord/scripts/overlord-mcp.mjs

@@ -1009,6 +1009,40 @@ const tools = [
     }),
     subcommand: 'claim-execution'
   },
+  {
+    name: 'list_execution_requests',
+    description: 'List active execution requests in the local runner queue.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        device_fingerprint: { type: 'string' },
+        project_id: { type: 'string' }
+      }
+    },
+    toCliFlags: args => ({
+      'device-fingerprint': args.device_fingerprint,
+      'project-id': args.project_id
+    }),
+    subcommand: 'list-execution-requests'
+  },
+  {
+    name: 'clear_execution_requests',
+    description: 'Clear active execution requests from the local runner queue.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        objective_id: { type: 'string' },
+        clear_all: { type: 'boolean' },
+        project_id: { type: 'string' }
+      }
+    },
+    toCliFlags: args => ({
+      'objective-id': args.objective_id,
+      ...(args.clear_all ? { 'clear-all': true } : {}),
+      'project-id': args.project_id
+    }),
+    subcommand: 'clear-execution-requests'
+  },
   {
     name: 'complete_execution_launch',
     description: 'Mark a claimed execution request as launched.',

package/plugins/overlord/skills/overlord-ticket/reference/mcp.md

@@ -4,7 +4,7 @@
 - Hosted Overlord MCP (`/functions/v1/mcp`) uses camelCase JSON keys (`ticketId`, `sessionKey`, `deviceFingerprint`) matching `POST /api/protocol/*` bodies. The local shim uses snake_case keys mapped to CLI flags (`ticket_id`, `session_key`, `device_fingerprint`). Some local-only operations (`connect`, `load_ticket_context`, `revert`, `prompt`, runner queue tools) intentionally remain out of hosted MCP for now.
 - `discover_project` accepts an explicit project id (`projectId` hosted, `project_id` local shim) or a working directory (`workingDirectory` hosted, `working_directory` local shim). When resolving by directory and a device fingerprint is available, include `deviceFingerprint` / `device_fingerprint` so resource-directory matching prefers the current device.
 - `permission-request` is invoked by the Codex permission hook installed by the bundle. Agents do not normally call it directly.
-- Execution request tools (`request_execution`, `claim_execution`, `complete_execution_launch`, `fail_execution_launch`) back the local runner queue. Agents normally work tickets with `attach`/`update`/`deliver`; runner processes use these queue tools.
+- Execution request tools (`request_execution`, `claim_execution`, `list_execution_requests`, `clear_execution_requests`, `complete_execution_launch`, `fail_execution_launch`) back the local runner queue. Agents normally work tickets with `attach`/`update`/`deliver`; runner processes use these queue tools.
 - `record_change_rationales` (MCP) and `ovld protocol record-change-rationales` (CLI) both write to the same `file_changes` table. The dedicated CLI route is `POST /api/protocol/record-change-rationales`.
 - Objective attachment tools follow the `<verb>_<noun>` MCP naming: `list_attachments`, `prepare_attachment_upload`, `finalize_attachment_upload`, `get_attachment_download_url`, `upload_attachment_file`. CLI commands use `attachment-*`. `ticket_id` / `ticketId` is optional for attachment calls when the objective or attachment id lets the server derive ticket scope.
 - "Artifacts" in `deliver` are the structured records an agent submits at delivery time (next_steps, test_results, migration, decision, note, url) — not user-uploaded files. Files attached by users live on objectives via the attachment tools above.