overlord-cli 0.2605211850.1 → 0.2605221356.0

package/README.md

@@ -65,6 +65,8 @@ ovld prompt "Draft a fix for the onboarding flow"
 ovld version
 ovld update
 ovld protocol discover-project
+ovld protocol discover-project --project-id <project-id>
+ovld protocol discover-project --working-directory /path/to/repo --device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"
 ovld protocol attach --ticket-id <ticket_id>
 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

package/bin/_cli/protocol.mjs

@@ -1367,8 +1367,11 @@ async function protocolDeliver(args) {
 async function protocolAttachmentList(args) {
   const flags = parseFlags(args);
   const { sessionKey, ticketId } = resolveSessionFlags(flags);
+  const objectiveId = flags['objective-id'] ? String(flags['objective-id']) : '';
   if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
-  if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
+  if (!ticketId && !objectiveId) {
+    throw new Error('--objective-id or --ticket-id is required');
+  }
 
   const { platformUrl, bearerToken, localSecret, organizationId } =
     await resolveProtocolAuthForFlags(flags, ticketId);
@@ -1376,8 +1379,8 @@ async function protocolAttachmentList(args) {
 
   const body = {
     sessionKey,
-    ticketId,
-    ...(flags['objective-id'] ? { objectiveId: String(flags['objective-id']) } : {})
+    ...(ticketId ? { ticketId } : {}),
+    ...(objectiveId ? { objectiveId } : {})
   };
 
   const data = await apiPost(
@@ -1396,7 +1399,6 @@ async function protocolAttachmentPrepareUpload(args) {
   const flags = parseFlags(args);
   const { sessionKey, ticketId } = resolveSessionFlags(flags);
   if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
-  if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
   const objectiveId = requireFlag(flags, 'objective-id', undefined);
   const fileName = requireFlag(flags, 'file-name', undefined);
 
@@ -1406,7 +1408,7 @@ async function protocolAttachmentPrepareUpload(args) {
 
   const body = {
     sessionKey,
-    ticketId,
+    ...(ticketId ? { ticketId } : {}),
     objectiveId,
     fileName,
     ...(flags.label ? { label: String(flags.label) } : {}),
@@ -1433,7 +1435,6 @@ async function protocolAttachmentFinalizeUpload(args) {
   const flags = parseFlags(args);
   const { sessionKey, ticketId } = resolveSessionFlags(flags);
   if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
-  if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
   const objectiveId = requireFlag(flags, 'objective-id', undefined);
   const storagePath = requireFlag(flags, 'storage-path', undefined);
   const label = requireFlag(flags, 'label', undefined);
@@ -1444,7 +1445,7 @@ async function protocolAttachmentFinalizeUpload(args) {
 
   const body = {
     sessionKey,
-    ticketId,
+    ...(ticketId ? { ticketId } : {}),
     objectiveId,
     storagePath,
     label,
@@ -1471,7 +1472,6 @@ async function protocolAttachmentGetDownloadUrl(args) {
   const flags = parseFlags(args);
   const { sessionKey, ticketId } = resolveSessionFlags(flags);
   if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
-  if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
   if (!flags['attachment-id'] && !flags['storage-path']) {
     throw new Error('--attachment-id or --storage-path is required');
   }
@@ -1485,7 +1485,7 @@ async function protocolAttachmentGetDownloadUrl(args) {
 
   const body = {
     sessionKey,
-    ticketId,
+    ...(ticketId ? { ticketId } : {}),
     ...(flags['objective-id'] ? { objectiveId: String(flags['objective-id']) } : {}),
     ...(flags['attachment-id'] ? { attachmentId: String(flags['attachment-id']) } : {}),
     ...(flags['storage-path'] ? { storagePath: String(flags['storage-path']) } : {}),
@@ -1508,7 +1508,6 @@ async function protocolAttachmentUploadFile(args) {
   const flags = parseFlags(args);
   const { sessionKey, ticketId } = resolveSessionFlags(flags);
   if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
-  if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
   const objectiveId = requireFlag(flags, 'objective-id', undefined);
   const filePath = requireFlag(flags, 'file', undefined);
 
@@ -1537,7 +1536,7 @@ async function protocolAttachmentUploadFile(args) {
     '/api/protocol/attachments/prepare-upload',
     {
       sessionKey,
-      ticketId,
+      ...(ticketId ? { ticketId } : {}),
       objectiveId,
       fileName,
       label,
@@ -1564,7 +1563,7 @@ async function protocolAttachmentUploadFile(args) {
     '/api/protocol/attachments/finalize-upload',
     {
       sessionKey,
-      ticketId,
+      ...(ticketId ? { ticketId } : {}),
       objectiveId,
       storagePath,
       label,
@@ -1588,7 +1587,8 @@ async function protocolDiscoverProject(args) {
     await resolveProtocolAuthForFlags(flags);
   const timeoutMs = resolveTimeout(flags);
 
-  const workingDirectory = String(flags['working-directory'] ?? process.cwd());
+  const workingDirectory =
+    flags['working-directory'] !== undefined ? String(flags['working-directory']) : process.cwd();
 
   const data = await apiPost(
     platformUrl,
@@ -1596,7 +1596,14 @@ async function protocolDiscoverProject(args) {
     localSecret,
     organizationId,
     '/api/protocol/discover-project',
-    { workingDirectory },
+    {
+      ...(flags['project-id'] ? { projectId: String(flags['project-id']) } : { workingDirectory }),
+      ...(flags['device-fingerprint']
+        ? { deviceFingerprint: String(flags['device-fingerprint']) }
+        : {}),
+      ...(flags['device-hostname'] ? { deviceHostname: String(flags['device-hostname']) } : {}),
+      ...(flags['device-platform'] ? { devicePlatform: String(flags['device-platform']) } : {})
+    },
     timeoutMs
   );
   console.log(JSON.stringify(data, null, 2));
@@ -2493,9 +2500,10 @@ Project discovery:
   You can also discover the project explicitly:
 
     ovld protocol discover-project
+    ovld protocol discover-project --project-id <project-uuid>
     ovld protocol discover-project --working-directory /path/to/repo
 
-  Use --project-id to override automatic resolution on prompt or ticket creation.
+  Use --project-id to override automatic resolution on discover, prompt, or ticket creation.
   Use --personal to create a private ticket without assigning any project.
 
 Subcommands:
@@ -2563,7 +2571,11 @@ discover-project:
     Resolve the Overlord project that corresponds to the current (or given) working directory.
     Uses the caller's configured "Local working directory" for matching.
   Optional:
+    --project-id <uuid>       Resolve this project directly; skips working-directory matching
     --working-directory <path>  Directory to match (default: current working directory)
+    --device-fingerprint <fp>   Prefer resource directories for this registered device
+    --device-hostname <name>    Register/update device metadata when fingerprint is provided
+    --device-platform <platform>
   Returns:
     Project JSON with id, name, organizationId. Prints PROJECT_ID=<id> on stderr.
   Notes:
@@ -2860,19 +2872,20 @@ record-work:
 attachment-list:
   Required:
     --session-key <key>
-    --ticket-id <ticket_id>
+    one of: --objective-id <id> | --ticket-id <ticket_id>
   Optional:
-    --objective-id <id>       Filter to a single objective
+    --objective-id <id>       Filter to a single objective (also acts as ticket scope)
+    --ticket-id <ticket_id>   List every attachment for a ticket
   Returns:
     JSON array of { id, label, content_type, file_size, objective_id, storage_path, created_at }
 
 attachment-prepare-upload:
   Required:
     --session-key <key>
-    --ticket-id <ticket_id>
     --objective-id <id>
     --file-name <name>
   Optional:
+    --ticket-id <ticket_id>   Derived from --objective-id when omitted
     --label <text>
     --content-type <mime>
     --file-size <bytes>
@@ -2881,11 +2894,11 @@ attachment-prepare-upload:
 attachment-finalize-upload:
   Required:
     --session-key <key>
-    --ticket-id <ticket_id>
     --objective-id <id>
     --storage-path <path>
     --label <text>
   Optional:
+    --ticket-id <ticket_id>   Derived from --objective-id when omitted
     --content-type <mime>
     --file-size <bytes>
     --metadata-json <json>
@@ -2893,19 +2906,19 @@ attachment-finalize-upload:
 attachment-download-url:
   Required:
     --session-key <key>
-    --ticket-id <ticket_id>
     one of: --attachment-id <id> | --storage-path <path>
   Optional:
+    --ticket-id <ticket_id>   Derived from --attachment-id / --objective-id when omitted
     --objective-id <id>       Required when using --storage-path
     --expires-in <seconds>
 
 attachment-upload-file:
   Required:
     --session-key <key>
-    --ticket-id <ticket_id>
     --objective-id <id>
     --file <path>
   Optional:
+    --ticket-id <ticket_id>   Derived from --objective-id when omitted
     --file-name <name>        Defaults to basename of --file
     --label <text>            Defaults to file name
     --content-type <mime>     Defaults to application/octet-stream
@@ -2993,6 +3006,7 @@ fail-execution-launch:
 Examples:
   ovld protocol auth-status
   ovld protocol discover-project
+  ovld protocol discover-project --project-id <project-uuid>
   ovld protocol discover-project --working-directory /path/to/repo
   ovld protocol prompt --agent codex --objective "Implement feature X"   # auto-resolves project from cwd
   ovld protocol attach --ticket-id 1:899
@@ -3015,10 +3029,10 @@ Examples:
   ovld protocol hook-event --hook-type UserPromptSubmit --ticket-id <ticket_id> --prompt "User follow-up" --turn-index 1
   ovld protocol read-context --session-key <key> --ticket-id <ticket_id> --query arch --limit 5
   ovld protocol write-context --session-key <key> --ticket-id <ticket_id> --key "arch" --value '"monorepo"' --tags repo,agent
-  ovld protocol attachment-list --session-key <key> --ticket-id <ticket_id>
-  ovld protocol attachment-prepare-upload --session-key <key> --ticket-id <ticket_id> --objective-id <objective-id> --file-name spec.pdf --content-type application/pdf
-  ovld protocol attachment-upload-file --session-key <key> --ticket-id <ticket_id> --objective-id <objective-id> --file ./spec.pdf
-  ovld protocol attachment-download-url --session-key <key> --ticket-id <ticket_id> --attachment-id <attachment-id>
+  ovld protocol attachment-list --session-key <key> --objective-id <objective-id>
+  ovld protocol attachment-prepare-upload --session-key <key> --objective-id <objective-id> --file-name spec.pdf --content-type application/pdf
+  ovld protocol attachment-upload-file --session-key <key> --objective-id <objective-id> --file ./spec.pdf
+  ovld protocol attachment-download-url --session-key <key> --attachment-id <attachment-id>
   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 deliver --session-key <key> --ticket-id <ticket_id> --summary "Done"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "0.2605211850.1",
+  "version": "0.2605221356.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

@@ -57,18 +57,40 @@ function execFileWithOptionalInput(file, args, options, input) {
 const tools = [
   {
     name: 'discover_project',
-    description: 'Resolve the Overlord project that matches a working directory.',
+    description:
+      'Resolve an Overlord project by explicit project_id or by matching a working directory.',
     inputSchema: {
       type: 'object',
       properties: {
+        project_id: {
+          type: 'string',
+          description: 'Project UUID to resolve directly. Skips working-directory matching.'
+        },
         working_directory: {
           type: 'string',
           description: 'Directory to match. Defaults to the current workspace.'
+        },
+        device_fingerprint: {
+          type: 'string',
+          description:
+            'Optional stable device fingerprint. When provided, matching prefers resource directories for this registered device.'
+        },
+        device_hostname: {
+          type: 'string',
+          description: 'Optional hostname to register/update with device_fingerprint.'
+        },
+        device_platform: {
+          type: 'string',
+          description: 'Optional platform string, e.g. darwin, linux, or windows.'
         }
       }
     },
     toCliFlags: args => ({
-      'working-directory': args.working_directory
+      'project-id': args.project_id,
+      'working-directory': args.working_directory,
+      'device-fingerprint': args.device_fingerprint,
+      'device-hostname': args.device_hostname,
+      'device-platform': args.device_platform
     }),
     subcommand: 'discover-project'
   },
@@ -437,7 +459,7 @@ const tools = [
         query: { type: 'string' },
         limit: { type: 'number' }
       },
-      required: ['session_key', 'ticket_id']
+      required: ['session_key']
     },
     toCliFlags: args => ({
       'session-key': args.session_key,
@@ -584,7 +606,7 @@ const tools = [
         },
         objective_id: { type: 'string' }
       },
-      required: ['session_key', 'ticket_id']
+      required: ['session_key']
     },
     toCliFlags: args => ({
       'session-key': args.session_key,
@@ -611,7 +633,7 @@ const tools = [
         file_size: { type: 'number' },
         metadata: { type: 'object' }
       },
-      required: ['session_key', 'ticket_id', 'objective_id', 'file_name']
+      required: ['session_key', 'objective_id', 'file_name']
     },
     toCliFlags: args => ({
       'session-key': args.session_key,
@@ -644,7 +666,7 @@ const tools = [
         file_size: { type: 'number' },
         metadata: { type: 'object' }
       },
-      required: ['session_key', 'ticket_id', 'objective_id', 'storage_path', 'label']
+      required: ['session_key', 'objective_id', 'storage_path', 'label']
     },
     toCliFlags: args => ({
       'session-key': args.session_key,
@@ -674,7 +696,7 @@ const tools = [
         storage_path: { type: 'string' },
         expires_in: { type: 'number' }
       },
-      required: ['session_key', 'ticket_id']
+      required: ['session_key']
     },
     toCliFlags: args => ({
       'session-key': args.session_key,
@@ -705,7 +727,7 @@ const tools = [
         content_type: { type: 'string' },
         metadata: { type: 'object' }
       },
-      required: ['session_key', 'ticket_id', 'objective_id', 'file']
+      required: ['session_key', 'objective_id', 'file']
     },
     toCliFlags: args => ({
       'session-key': args.session_key,
@@ -862,6 +884,113 @@ const tools = [
         : {})
     }),
     subcommand: 'update-project-resource'
+  },
+  {
+    name: 'request_execution',
+    description:
+      'Queue an objective for local or remote runner execution. Manual Run and auto-advance use this durable queue.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ticket_id: { type: 'string' },
+        objective_id: { type: 'string' },
+        requested_from: { type: 'string' },
+        idempotency_key: { type: 'string' },
+        agent: { type: 'string' },
+        model: { type: 'string' },
+        thinking: { type: 'string' },
+        launch_mode: { type: 'string', enum: ['run', 'ask'] },
+        working_directory: { type: 'string' },
+        ssh_command: { type: 'string' },
+        remote_working_directory: { type: 'string' },
+        server_multiplexer: { type: 'string', enum: ['none', 'tmux'] },
+        tmux_command: { type: 'string' },
+        target_kind: { type: 'string', enum: ['any', 'local', 'ssh'] },
+        target_device_id: { type: 'string' },
+        target_resource_id: { type: 'string' }
+      },
+      required: ['ticket_id']
+    },
+    toCliFlags: args => ({
+      'ticket-id': args.ticket_id,
+      'objective-id': args.objective_id,
+      'requested-from': args.requested_from,
+      'idempotency-key': args.idempotency_key,
+      agent: args.agent,
+      model: args.model,
+      thinking: args.thinking,
+      'launch-mode': args.launch_mode,
+      'working-directory': args.working_directory,
+      'ssh-command': args.ssh_command,
+      'remote-working-directory': args.remote_working_directory,
+      'server-multiplexer': args.server_multiplexer,
+      'tmux-command': args.tmux_command,
+      'target-kind': args.target_kind,
+      'target-device-id': args.target_device_id,
+      'target-resource-id': args.target_resource_id
+    }),
+    subcommand: 'request-execution'
+  },
+  {
+    name: 'claim_execution',
+    description: 'Claim one queued execution request for this device.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        device_fingerprint: { type: 'string' },
+        device_hostname: { type: 'string' },
+        device_platform: { type: 'string' },
+        lease_seconds: { type: 'number' },
+        project_id: { type: 'string' }
+      },
+      required: ['device_fingerprint']
+    },
+    toCliFlags: args => ({
+      'device-fingerprint': args.device_fingerprint,
+      'device-hostname': args.device_hostname,
+      'device-platform': args.device_platform,
+      'lease-seconds': args.lease_seconds,
+      'project-id': args.project_id
+    }),
+    subcommand: 'claim-execution'
+  },
+  {
+    name: 'complete_execution_launch',
+    description: 'Mark a claimed execution request as launched.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        request_id: { type: 'string' },
+        device_fingerprint: { type: 'string' },
+        launched_session_id: { type: 'string' }
+      },
+      required: ['request_id', 'device_fingerprint']
+    },
+    toCliFlags: args => ({
+      'request-id': args.request_id,
+      'device-fingerprint': args.device_fingerprint,
+      'launched-session-id': args.launched_session_id
+    }),
+    subcommand: 'complete-execution-launch'
+  },
+  {
+    name: 'fail_execution_launch',
+    description: 'Mark a claimed execution request failed and record the launch error.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        request_id: { type: 'string' },
+        device_fingerprint: { type: 'string' },
+        error: { type: 'string' }
+      },
+      required: ['request_id', 'device_fingerprint', 'error']
+    },
+    toCliFlags: args => ({
+      'request-id': args.request_id,
+      'device-fingerprint': args.device_fingerprint,
+      error: args.error
+    }),
+    subcommand: 'fail-execution-launch'
   }
 ];
 

package/plugins/antigravity/skills/overlord-ticket/SKILL.md

@@ -176,9 +176,11 @@ To inspect project resolution explicitly:
 
 ```bash
 ovld protocol discover-project
+ovld protocol discover-project --project-id <project_uuid>
+ovld protocol discover-project --working-directory /path/to/repo
 ```
 
-You can override with `--project-id` or `--working-directory` if needed.
+Use `--project-id` when the project id is already known. Use `--working-directory` to override cwd path matching. If the runtime has an `OVERLORD_DEVICE_FINGERPRINT`, pass `--device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"` so resource-directory matching prefers the current device.
 
 ### Resolving the project ID when you don't have one
 
@@ -192,9 +194,9 @@ When you need a project ID for a protocol command and the ticket prompt did not
 
 **Over MCP (web agents and hosted tools, where the server cannot see the agent's cwd):**
 
-1. `--project-id` / `projectId` if explicitly provided.
-2. Read `overlord.json` from the directory the user is accessing and pass its project id as `projectId`.
-3. As a last resort, try `workingDirectory` resolution.
+1. `projectId` (hosted MCP) or `project_id` (local shim) if explicitly provided or found in the ticket/context.
+2. Read `overlord.json` from the directory the user is accessing and pass its project id as `projectId` / `project_id`.
+3. As a last resort, try `workingDirectory` / `working_directory` resolution. If a device fingerprint is available, include `deviceFingerprint` / `device_fingerprint`.
 
 If `overlord.json` contains more than one project, show the user the project **names** from that file and ask which one to use before calling any protocol command — never silently pick one.
 
@@ -221,12 +223,12 @@ When in doubt, ask yourself: _can this be done entirely inside a terminal or bro
 ```bash
 ovld protocol read-context --session-key <sessionKey> --ticket-id $TICKET_ID
 ovld protocol write-context --session-key <sessionKey> --ticket-id $TICKET_ID --key "key" --value '"json-value"'
-ovld protocol attachment-list --session-key <sessionKey> --ticket-id $TICKET_ID
-ovld protocol attachment-upload-file --session-key <sessionKey> --ticket-id $TICKET_ID --objective-id <objective-id> --file ./spec.pdf --content-type application/pdf
-ovld protocol attachment-download-url --session-key <sessionKey> --ticket-id $TICKET_ID --attachment-id <attachment-id>
+ovld protocol attachment-list --session-key <sessionKey> --objective-id <objective-id>
+ovld protocol attachment-upload-file --session-key <sessionKey> --objective-id <objective-id> --file ./spec.pdf --content-type application/pdf
+ovld protocol attachment-download-url --session-key <sessionKey> --attachment-id <attachment-id>
 ```
 
-The `attach` and `load-context` responses already include `attachments` and `objectives` arrays — use those for `<attachment-id>` and `<objective-id>` values. Run `attachment-list` mid-session if new files have been uploaded since attach.
+The `attach` and `load-context` responses already include `attachments` and `objectives` arrays — use those for `<attachment-id>` and `<objective-id>` values. Run `attachment-list` mid-session if new files have been uploaded since attach. `--ticket-id` is optional for attachment calls when `--objective-id` or `--attachment-id` lets the server derive the ticket.
 
 ## Large Artifacts
 
@@ -241,9 +243,10 @@ This keeps the ticket feed readable while preserving the full document in versio
 ## Defaults And Notes
 
 - API requires `agentIdentifier` and `connectionMethod` on attach/connect/prompt. The CLI defaults them to `antigravity`/`cli`; the MCP tool defaults to `mcp`. Override with `--agent` / `--method` when calling from a different runtime.
-- Hosted Overlord MCP (`/functions/v1/mcp`) uses the same canonical tool names as the local shim that shells into `ovld protocol` (`attach`, `update`, `deliver`, `get_device`, `list_project_resources`, …). Hosted calls use 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`).
+- 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.
 - `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-*` and require `--objective-id` for upload/finalize.
+- 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.
 - Antigravity CLI does not expose `--model`, `--thinking-level`, or `--temperature` flags. Model selection is managed by the Antigravity platform; do not attempt to pass these at launch.
 - The Overlord plugin is installed by `ovld setup antigravity`. Run this once to install the bundle into `~/.gemini/antigravity-cli/plugins/` and wire the MCP server path.
@@ -261,4 +264,4 @@ This keeps the ticket feed readable while preserving the full document in versio
 - Do not add or commit changes unless the user explicitly asks you to commit.
 - Delivery is the concluding step. After delivering, stop unless the user follows up or the ticket is reopened.
 
-<!-- version: 0.1.0 -->
+<!-- version: 0.1.1 -->

package/plugins/claude/skills/overlord-ticket/SKILL.md

@@ -21,6 +21,28 @@ Use this mode when the prompt already contains a ticket ID or explicitly says th
 
 For full command syntax, flags, phase values, and event types see [reference/cli.md](reference/cli.md).
 
+## Tickets vs Objectives
+
+**Tickets** represent whole features or goals. **Objectives** are the individual steps to implement that goal — one objective equals one agent prompt.
+
+Example:
+```
+Ticket: add CLI command for editing user profile
+ - Objective 1: draft plan for this command
+ - Objective 2: implement phase 1 of plan
+ - Objective 3: implement phase 2 of plan
+ - Objective 4: update documentation
+```
+
+When to create a ticket vs an objective:
+- **Create a new ticket** when the user describes a distinct feature, bug, or goal that stands on its own.
+- **Add objectives to an existing ticket** when the work is a sequential step toward the same feature or goal already tracked in a ticket.
+
+To add further objectives to an existing ticket (Mode 2):
+```
+ovld protocol add-objectives --ticket-id <ticket_id> --objectives-json '[{"objective":"..."},{"objective":"..."}]'
+```
+
 ## Objective Submission vs Execution
 
 Discussing or otherwise opening a ticket from within a chat should cause the draft objective to be marked **submitted** — this signals the ticket is in active discussion with an agent, but not yet being executed. Only an explicit order to execute (e.g. "execute this", "do this", "start working on it") should cause you to **attach** to the ticket and trigger execution.
@@ -39,6 +61,7 @@ Use this mode when the conversation starts normally and the user asks Claude to
    - When `--session-key` and `--ticket-id` are provided, it creates a follow-up draft.
    - When session flags are omitted, it resolves the project by matching current working directory (or `--working-directory`) to Overlord `local_working_directory`, then creates a standalone draft.
    - Pass multiple items in `--objectives-json` when creating ordered steps for the same feature or goal.
+   - If the user wants to **add more objectives to an existing ticket** (not create a new ticket), use `ovld protocol add-objectives --ticket-id <ticket_id> --objectives-json '[{"objective":"..."}]'` instead.
 2. Default to `create` for new tickets. Only use `/overlord:prompt` or `ovld protocol prompt --agent claude-code --objectives-json '[{"objective":"..."}]'` when the user explicitly asks to create and execute immediately.
    `prompt` creates the ticket in `execute` status and attaches immediately.
 3. If the user already has a ticket ID and only wants to inspect it, use `/overlord:load` or run `ovld protocol load-context --ticket-id <ticket_id>`.
@@ -86,5 +109,5 @@ For the `record-change-rationales` command and full payload shape with optional
 - [reference/context.md](reference/context.md) — Shared state, attachments, and large artifact policy
 - [reference/shell-escaping.md](reference/shell-escaping.md) — Heredoc stdin piping for special characters in summaries and payloads
 
-<!-- version: 0.5.3 -->
+<!-- version: 0.5.5 -->
 

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

@@ -118,9 +118,11 @@ To inspect project resolution explicitly:
 
 ```bash
 ovld protocol discover-project
+ovld protocol discover-project --project-id <project_uuid>
+ovld protocol discover-project --working-directory /path/to/repo
 ```
 
-You can override with `--project-id` or `--working-directory` if needed.
+Use `--project-id` when the project id is already known. Use `--working-directory` to override cwd path matching. If the runtime has an `OVERLORD_DEVICE_FINGERPRINT`, pass `--device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"` so resource-directory matching prefers the current device.
 
 ### Resolving the project ID when you don't have one
 
@@ -134,9 +136,9 @@ When you need a project ID for a protocol command and the ticket prompt did not
 
 **Over MCP (web agents and hosted tools, where the server cannot see the agent's cwd):**
 
-1. `--project-id` / `projectId` if explicitly provided.
-2. Read `overlord.json` from the directory the user is accessing and pass its project id as `projectId`.
-3. As a last resort, try `workingDirectory` resolution.
+1. `projectId` (hosted MCP) or `project_id` (local shim) if explicitly provided or found in the ticket/context.
+2. Read `overlord.json` from the directory the user is accessing and pass its project id as `projectId` / `project_id`.
+3. As a last resort, try `workingDirectory` / `working_directory` resolution. If a device fingerprint is available, include `deviceFingerprint` / `device_fingerprint`.
 
 If `overlord.json` contains more than one project, show the user the project **names** from that file and ask which one to use before calling any protocol command — never silently pick one.
 

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

@@ -3,12 +3,12 @@
 ```bash
 ovld protocol read-context --session-key <sessionKey> --ticket-id $TICKET_ID
 ovld protocol write-context --session-key <sessionKey> --ticket-id $TICKET_ID --key "key" --value '"json-value"'
-ovld protocol attachment-list --session-key <sessionKey> --ticket-id $TICKET_ID
-ovld protocol attachment-upload-file --session-key <sessionKey> --ticket-id $TICKET_ID --objective-id <objective-id> --file ./spec.pdf --content-type application/pdf
-ovld protocol attachment-download-url --session-key <sessionKey> --ticket-id $TICKET_ID --attachment-id <attachment-id>
+ovld protocol attachment-list --session-key <sessionKey> --objective-id <objective-id>
+ovld protocol attachment-upload-file --session-key <sessionKey> --objective-id <objective-id> --file ./spec.pdf --content-type application/pdf
+ovld protocol attachment-download-url --session-key <sessionKey> --attachment-id <attachment-id>
 ```
 
-The `attach` and `load-context` responses already include `attachments` and `objectives` arrays — use those for `<attachment-id>` and `<objective-id>` values. Run `attachment-list` mid-session if new files have been uploaded since attach.
+The `attach` and `load-context` responses already include `attachments` and `objectives` arrays — use those for `<attachment-id>` and `<objective-id>` values. Run `attachment-list` mid-session if new files have been uploaded since attach. `--ticket-id` is optional for attachment calls when `--objective-id` or `--attachment-id` lets the server derive the ticket.
 
 ## Large Artifacts
 

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

@@ -1,10 +1,11 @@
 # MCP And API Defaults
 
 - API requires `agentIdentifier` and `connectionMethod` on attach/connect/prompt. The CLI defaults them to `claude-code`/`cli`; the MCP tool defaults to `mcp`. Override with `--agent` / `--method` when calling from a different runtime.
-- Hosted Overlord MCP (`/functions/v1/mcp`) uses the same canonical tool names as the local shim that shells into `ovld protocol` (`attach`, `update`, `deliver`, `get_device`, `list_project_resources`, …). Hosted calls use 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`).
+- 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.
 - `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-*` and require `--objective-id` for upload/finalize.
+- 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/SKILL.md

@@ -21,6 +21,28 @@ Use this mode when the prompt already contains a ticket ID or explicitly says th
 
 For full command syntax, flags, phase values, and event types see [reference/cli.md](reference/cli.md).
 
+## Tickets vs Objectives
+
+**Tickets** represent whole features or goals. **Objectives** are the individual steps to implement that goal — one objective equals one agent prompt.
+
+Example:
+```
+Ticket: add CLI command for editing user profile
+ - Objective 1: draft plan for this command
+ - Objective 2: implement phase 1 of plan
+ - Objective 3: implement phase 2 of plan
+ - Objective 4: update documentation
+```
+
+When to create a ticket vs an objective:
+- **Create a new ticket** when the user describes a distinct feature, bug, or goal that stands on its own.
+- **Add objectives to an existing ticket** when the work is a sequential step toward the same feature or goal already tracked in a ticket.
+
+To add further objectives to an existing ticket (Mode 2):
+```
+ovld protocol add-objectives --ticket-id <ticket_id> --objectives-json '[{"objective":"..."},{"objective":"..."}]'
+```
+
 ## Objective Submission vs Execution
 
 Discussing or otherwise opening a ticket from within a chat should cause the draft objective to be marked **submitted** — this signals the ticket is in active discussion with an agent, but not yet being executed. Only an explicit order to execute (e.g. "execute this", "do this", "start working on it") should cause you to **attach** to the ticket and trigger execution.
@@ -39,6 +61,7 @@ Use this mode when the conversation starts normally and the user asks Cursor to
    - When `--session-key` and `--ticket-id` are provided, it creates a follow-up draft.
    - When session flags are omitted, it resolves the project by matching current working directory (or `--working-directory`) to Overlord `local_working_directory`, then creates a standalone draft.
    - Pass multiple items in `--objectives-json` when creating ordered steps for the same feature or goal.
+   - If the user wants to **add more objectives to an existing ticket** (not create a new ticket), use `ovld protocol add-objectives --ticket-id <ticket_id> --objectives-json '[{"objective":"..."}]'` instead.
 2. Default to `create` for new tickets. Only use `/prompt` or `ovld protocol prompt --agent cursor --objectives-json '[{"objective":"..."}]'` when the user explicitly asks to create and execute immediately.
    `prompt` creates the ticket in `execute` status and attaches immediately.
 3. If the user already has a ticket ID and only wants to inspect it, use `/load` or run `ovld protocol load-context --ticket-id <ticket_id>`.
@@ -86,5 +109,5 @@ For the `record-change-rationales` command and full payload shape with optional
 - [reference/context.md](reference/context.md) — Shared state, attachments, and large artifact policy
 - [reference/shell-escaping.md](reference/shell-escaping.md) — Heredoc stdin piping for special characters in summaries and payloads
 
-<!-- version: 0.5.3 -->
+<!-- version: 0.5.5 -->
 

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

@@ -118,9 +118,11 @@ To inspect project resolution explicitly:
 
 ```bash
 ovld protocol discover-project
+ovld protocol discover-project --project-id <project_uuid>
+ovld protocol discover-project --working-directory /path/to/repo
 ```
 
-You can override with `--project-id` or `--working-directory` if needed.
+Use `--project-id` when the project id is already known. Use `--working-directory` to override cwd path matching. If the runtime has an `OVERLORD_DEVICE_FINGERPRINT`, pass `--device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"` so resource-directory matching prefers the current device.
 
 ### Resolving the project ID when you don't have one
 
@@ -134,9 +136,9 @@ When you need a project ID for a protocol command and the ticket prompt did not
 
 **Over MCP (web agents and hosted tools, where the server cannot see the agent's cwd):**
 
-1. `--project-id` / `projectId` if explicitly provided.
-2. Read `overlord.json` from the directory the user is accessing and pass its project id as `projectId`.
-3. As a last resort, try `workingDirectory` resolution.
+1. `projectId` (hosted MCP) or `project_id` (local shim) if explicitly provided or found in the ticket/context.
+2. Read `overlord.json` from the directory the user is accessing and pass its project id as `projectId` / `project_id`.
+3. As a last resort, try `workingDirectory` / `working_directory` resolution. If a device fingerprint is available, include `deviceFingerprint` / `device_fingerprint`.
 
 If `overlord.json` contains more than one project, show the user the project **names** from that file and ask which one to use before calling any protocol command — never silently pick one.
 

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

@@ -3,12 +3,12 @@
 ```bash
 ovld protocol read-context --session-key <sessionKey> --ticket-id $TICKET_ID
 ovld protocol write-context --session-key <sessionKey> --ticket-id $TICKET_ID --key "key" --value '"json-value"'
-ovld protocol attachment-list --session-key <sessionKey> --ticket-id $TICKET_ID
-ovld protocol attachment-upload-file --session-key <sessionKey> --ticket-id $TICKET_ID --objective-id <objective-id> --file ./spec.pdf --content-type application/pdf
-ovld protocol attachment-download-url --session-key <sessionKey> --ticket-id $TICKET_ID --attachment-id <attachment-id>
+ovld protocol attachment-list --session-key <sessionKey> --objective-id <objective-id>
+ovld protocol attachment-upload-file --session-key <sessionKey> --objective-id <objective-id> --file ./spec.pdf --content-type application/pdf
+ovld protocol attachment-download-url --session-key <sessionKey> --attachment-id <attachment-id>
 ```
 
-The `attach` and `load-context` responses already include `attachments` and `objectives` arrays — use those for `<attachment-id>` and `<objective-id>` values. Run `attachment-list` mid-session if new files have been uploaded since attach.
+The `attach` and `load-context` responses already include `attachments` and `objectives` arrays — use those for `<attachment-id>` and `<objective-id>` values. Run `attachment-list` mid-session if new files have been uploaded since attach. `--ticket-id` is optional for attachment calls when `--objective-id` or `--attachment-id` lets the server derive the ticket.
 
 ## Large Artifacts
 

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

@@ -1,10 +1,11 @@
 # MCP And API Defaults
 
 - API requires `agentIdentifier` and `connectionMethod` on attach/connect/prompt. The CLI defaults them to `cursor`/`cli`; the MCP tool defaults to `mcp`. Override with `--agent` / `--method` when calling from a different runtime.
-- Hosted Overlord MCP (`/functions/v1/mcp`) uses the same canonical tool names as the local shim that shells into `ovld protocol` (`attach`, `update`, `deliver`, `get_device`, `list_project_resources`, …). Hosted calls use 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`).
+- 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.
 - `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-*` and require `--objective-id` for upload/finalize.
+- 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/README.md

@@ -40,6 +40,7 @@ Tool names match the hosted Overlord MCP server (`supabase/functions/mcp/tools.t
 - Progress and review flow: `update`, `record_change_rationales`, `ask`, `deliver`
 - Shared context: `read_context`, `write_context`
 - Objective attachments: `list_attachments`, `prepare_attachment_upload`, `finalize_attachment_upload`, `get_attachment_download_url`, `upload_attachment_file`
+- Local runner queue: `request_execution`, `claim_execution`, `complete_execution_launch`, `fail_execution_launch`
 
 The MCP server shells into the installed `ovld` binary so the plugin stays aligned with the shipped CLI behavior instead of depending on this repository checkout.
 

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

@@ -57,18 +57,40 @@ function execFileWithOptionalInput(file, args, options, input) {
 const tools = [
   {
     name: 'discover_project',
-    description: 'Resolve the Overlord project that matches a working directory.',
+    description:
+      'Resolve an Overlord project by explicit project_id or by matching a working directory.',
     inputSchema: {
       type: 'object',
       properties: {
+        project_id: {
+          type: 'string',
+          description: 'Project UUID to resolve directly. Skips working-directory matching.'
+        },
         working_directory: {
           type: 'string',
           description: 'Directory to match. Defaults to the current workspace.'
+        },
+        device_fingerprint: {
+          type: 'string',
+          description:
+            'Optional stable device fingerprint. When provided, matching prefers resource directories for this registered device.'
+        },
+        device_hostname: {
+          type: 'string',
+          description: 'Optional hostname to register/update with device_fingerprint.'
+        },
+        device_platform: {
+          type: 'string',
+          description: 'Optional platform string, e.g. darwin, linux, or windows.'
         }
       }
     },
     toCliFlags: args => ({
-      'working-directory': args.working_directory
+      'project-id': args.project_id,
+      'working-directory': args.working_directory,
+      'device-fingerprint': args.device_fingerprint,
+      'device-hostname': args.device_hostname,
+      'device-platform': args.device_platform
     }),
     subcommand: 'discover-project'
   },
@@ -437,7 +459,7 @@ const tools = [
         query: { type: 'string' },
         limit: { type: 'number' }
       },
-      required: ['session_key', 'ticket_id']
+      required: ['session_key']
     },
     toCliFlags: args => ({
       'session-key': args.session_key,
@@ -583,7 +605,7 @@ const tools = [
         },
         objective_id: { type: 'string' }
       },
-      required: ['session_key', 'ticket_id']
+      required: ['session_key']
     },
     toCliFlags: args => ({
       'session-key': args.session_key,
@@ -610,7 +632,7 @@ const tools = [
         file_size: { type: 'number' },
         metadata: { type: 'object' }
       },
-      required: ['session_key', 'ticket_id', 'objective_id', 'file_name']
+      required: ['session_key', 'objective_id', 'file_name']
     },
     toCliFlags: args => ({
       'session-key': args.session_key,
@@ -643,7 +665,7 @@ const tools = [
         file_size: { type: 'number' },
         metadata: { type: 'object' }
       },
-      required: ['session_key', 'ticket_id', 'objective_id', 'storage_path', 'label']
+      required: ['session_key', 'objective_id', 'storage_path', 'label']
     },
     toCliFlags: args => ({
       'session-key': args.session_key,
@@ -673,7 +695,7 @@ const tools = [
         storage_path: { type: 'string' },
         expires_in: { type: 'number' }
       },
-      required: ['session_key', 'ticket_id']
+      required: ['session_key']
     },
     toCliFlags: args => ({
       'session-key': args.session_key,
@@ -704,7 +726,7 @@ const tools = [
         content_type: { type: 'string' },
         metadata: { type: 'object' }
       },
-      required: ['session_key', 'ticket_id', 'objective_id', 'file']
+      required: ['session_key', 'objective_id', 'file']
     },
     toCliFlags: args => ({
       'session-key': args.session_key,
@@ -861,6 +883,113 @@ const tools = [
         : {})
     }),
     subcommand: 'update-project-resource'
+  },
+  {
+    name: 'request_execution',
+    description:
+      'Queue an objective for local or remote runner execution. Manual Run and auto-advance use this durable queue.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ticket_id: { type: 'string' },
+        objective_id: { type: 'string' },
+        requested_from: { type: 'string' },
+        idempotency_key: { type: 'string' },
+        agent: { type: 'string' },
+        model: { type: 'string' },
+        thinking: { type: 'string' },
+        launch_mode: { type: 'string', enum: ['run', 'ask'] },
+        working_directory: { type: 'string' },
+        ssh_command: { type: 'string' },
+        remote_working_directory: { type: 'string' },
+        server_multiplexer: { type: 'string', enum: ['none', 'tmux'] },
+        tmux_command: { type: 'string' },
+        target_kind: { type: 'string', enum: ['any', 'local', 'ssh'] },
+        target_device_id: { type: 'string' },
+        target_resource_id: { type: 'string' }
+      },
+      required: ['ticket_id']
+    },
+    toCliFlags: args => ({
+      'ticket-id': args.ticket_id,
+      'objective-id': args.objective_id,
+      'requested-from': args.requested_from,
+      'idempotency-key': args.idempotency_key,
+      agent: args.agent,
+      model: args.model,
+      thinking: args.thinking,
+      'launch-mode': args.launch_mode,
+      'working-directory': args.working_directory,
+      'ssh-command': args.ssh_command,
+      'remote-working-directory': args.remote_working_directory,
+      'server-multiplexer': args.server_multiplexer,
+      'tmux-command': args.tmux_command,
+      'target-kind': args.target_kind,
+      'target-device-id': args.target_device_id,
+      'target-resource-id': args.target_resource_id
+    }),
+    subcommand: 'request-execution'
+  },
+  {
+    name: 'claim_execution',
+    description: 'Claim one queued execution request for this device.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        device_fingerprint: { type: 'string' },
+        device_hostname: { type: 'string' },
+        device_platform: { type: 'string' },
+        lease_seconds: { type: 'number' },
+        project_id: { type: 'string' }
+      },
+      required: ['device_fingerprint']
+    },
+    toCliFlags: args => ({
+      'device-fingerprint': args.device_fingerprint,
+      'device-hostname': args.device_hostname,
+      'device-platform': args.device_platform,
+      'lease-seconds': args.lease_seconds,
+      'project-id': args.project_id
+    }),
+    subcommand: 'claim-execution'
+  },
+  {
+    name: 'complete_execution_launch',
+    description: 'Mark a claimed execution request as launched.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        request_id: { type: 'string' },
+        device_fingerprint: { type: 'string' },
+        launched_session_id: { type: 'string' }
+      },
+      required: ['request_id', 'device_fingerprint']
+    },
+    toCliFlags: args => ({
+      'request-id': args.request_id,
+      'device-fingerprint': args.device_fingerprint,
+      'launched-session-id': args.launched_session_id
+    }),
+    subcommand: 'complete-execution-launch'
+  },
+  {
+    name: 'fail_execution_launch',
+    description: 'Mark a claimed execution request failed and record the launch error.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        request_id: { type: 'string' },
+        device_fingerprint: { type: 'string' },
+        error: { type: 'string' }
+      },
+      required: ['request_id', 'device_fingerprint', 'error']
+    },
+    toCliFlags: args => ({
+      'request-id': args.request_id,
+      'device-fingerprint': args.device_fingerprint,
+      error: args.error
+    }),
+    subcommand: 'fail-execution-launch'
   }
 ];
 const searchTicketsTool = {

package/plugins/overlord/skills/overlord-ticket/SKILL.md

@@ -21,6 +21,28 @@ Use this mode when the prompt already contains a ticket ID or explicitly says th
 
 For full command syntax, flags, phase values, and event types see [reference/cli.md](reference/cli.md).
 
+## Tickets vs Objectives
+
+**Tickets** represent whole features or goals. **Objectives** are the individual steps to implement that goal — one objective equals one agent prompt.
+
+Example:
+```
+Ticket: add CLI command for editing user profile
+ - Objective 1: draft plan for this command
+ - Objective 2: implement phase 1 of plan
+ - Objective 3: implement phase 2 of plan
+ - Objective 4: update documentation
+```
+
+When to create a ticket vs an objective:
+- **Create a new ticket** when the user describes a distinct feature, bug, or goal that stands on its own.
+- **Add objectives to an existing ticket** when the work is a sequential step toward the same feature or goal already tracked in a ticket.
+
+To add further objectives to an existing ticket (Mode 2):
+```
+ovld protocol add-objectives --ticket-id <ticket_id> --objectives-json '[{"objective":"..."},{"objective":"..."}]'
+```
+
 ## Objective Submission vs Execution
 
 Discussing or otherwise opening a ticket from within a chat should cause the draft objective to be marked **submitted** — this signals the ticket is in active discussion with an agent, but not yet being executed. Only an explicit order to execute (e.g. "execute this", "do this", "start working on it") should cause you to **attach** to the ticket and trigger execution.
@@ -39,6 +61,7 @@ Use this mode when the conversation starts normally and the user asks Codex to c
    - When `--session-key` and `--ticket-id` are provided, it creates a follow-up draft.
    - When session flags are omitted, it resolves the project by matching current working directory (or `--working-directory`) to Overlord `local_working_directory`, then creates a standalone draft.
    - Pass multiple items in `--objectives-json` when creating ordered steps for the same feature or goal.
+   - If the user wants to **add more objectives to an existing ticket** (not create a new ticket), use `ovld protocol add-objectives --ticket-id <ticket_id> --objectives-json '[{"objective":"..."}]'` instead.
 2. Default to `create` for new tickets. Only use `ovld protocol prompt --agent codex --objectives-json '[{"objective":"..."}]'` when the user explicitly asks to create and execute immediately.
    `prompt` creates the ticket in `execute` status and attaches immediately.
 3. If the user already has a ticket ID and only wants to inspect it, run `ovld protocol load-context --ticket-id <ticket_id>`.
@@ -87,5 +110,5 @@ For the `record-change-rationales` command and full payload shape with optional
 - [reference/context.md](reference/context.md) — Shared state, attachments, and large artifact policy
 - [reference/shell-escaping.md](reference/shell-escaping.md) — Heredoc stdin piping for special characters in summaries and payloads
 
-<!-- version: 0.5.3 -->
+<!-- version: 0.5.5 -->
 

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

@@ -118,9 +118,11 @@ To inspect project resolution explicitly:
 
 ```bash
 ovld protocol discover-project
+ovld protocol discover-project --project-id <project_uuid>
+ovld protocol discover-project --working-directory /path/to/repo
 ```
 
-You can override with `--project-id` or `--working-directory` if needed.
+Use `--project-id` when the project id is already known. Use `--working-directory` to override cwd path matching. If the runtime has an `OVERLORD_DEVICE_FINGERPRINT`, pass `--device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"` so resource-directory matching prefers the current device.
 
 ### Resolving the project ID when you don't have one
 
@@ -134,9 +136,9 @@ When you need a project ID for a protocol command and the ticket prompt did not
 
 **Over MCP (web agents and hosted tools, where the server cannot see the agent's cwd):**
 
-1. `--project-id` / `projectId` if explicitly provided.
-2. Read `overlord.json` from the directory the user is accessing and pass its project id as `projectId`.
-3. As a last resort, try `workingDirectory` resolution.
+1. `projectId` (hosted MCP) or `project_id` (local shim) if explicitly provided or found in the ticket/context.
+2. Read `overlord.json` from the directory the user is accessing and pass its project id as `projectId` / `project_id`.
+3. As a last resort, try `workingDirectory` / `working_directory` resolution. If a device fingerprint is available, include `deviceFingerprint` / `device_fingerprint`.
 
 If `overlord.json` contains more than one project, show the user the project **names** from that file and ask which one to use before calling any protocol command — never silently pick one.
 

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

@@ -3,12 +3,12 @@
 ```bash
 ovld protocol read-context --session-key <sessionKey> --ticket-id $TICKET_ID
 ovld protocol write-context --session-key <sessionKey> --ticket-id $TICKET_ID --key "key" --value '"json-value"'
-ovld protocol attachment-list --session-key <sessionKey> --ticket-id $TICKET_ID
-ovld protocol attachment-upload-file --session-key <sessionKey> --ticket-id $TICKET_ID --objective-id <objective-id> --file ./spec.pdf --content-type application/pdf
-ovld protocol attachment-download-url --session-key <sessionKey> --ticket-id $TICKET_ID --attachment-id <attachment-id>
+ovld protocol attachment-list --session-key <sessionKey> --objective-id <objective-id>
+ovld protocol attachment-upload-file --session-key <sessionKey> --objective-id <objective-id> --file ./spec.pdf --content-type application/pdf
+ovld protocol attachment-download-url --session-key <sessionKey> --attachment-id <attachment-id>
 ```
 
-The `attach` and `load-context` responses already include `attachments` and `objectives` arrays — use those for `<attachment-id>` and `<objective-id>` values. Run `attachment-list` mid-session if new files have been uploaded since attach.
+The `attach` and `load-context` responses already include `attachments` and `objectives` arrays — use those for `<attachment-id>` and `<objective-id>` values. Run `attachment-list` mid-session if new files have been uploaded since attach. `--ticket-id` is optional for attachment calls when `--objective-id` or `--attachment-id` lets the server derive the ticket.
 
 ## Large Artifacts
 

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

@@ -1,10 +1,11 @@
 # MCP And API Defaults
 
 - API requires `agentIdentifier` and `connectionMethod` on attach/connect/prompt. The CLI defaults them to `codex`/`cli`; the MCP tool defaults to `mcp`. Override with `--agent` / `--method` when calling from a different runtime.
-- Hosted Overlord MCP (`/functions/v1/mcp`) uses the same canonical tool names as the local shim that shells into `ovld protocol` (`attach`, `update`, `deliver`, `get_device`, `list_project_resources`, …). Hosted calls use 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`).
+- 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.
 - `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-*` and require `--objective-id` for upload/finalize.
+- 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.