overlord-cli 0.2605312007.1 → 0.2606010745.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,12 @@ 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`.
 
 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

@@ -2067,6 +2067,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 +2715,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 +3218,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 +3283,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 +3409,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
@@ -466,6 +499,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 +561,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 +574,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.2605312007.1",
+  "version": "0.2606010745.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.