overlord-cli 0.2605211850.0 → 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/bin/_cli/runner.mjs

@@ -9,6 +9,12 @@ import path from 'node:path';
 const OVLD_ENTRY = process.argv[1];
 const DEVICE_FILE = path.join(os.homedir(), '.ovld', 'device.json');
 
+/** @internal Test-only overrides for protocol/launch subprocess calls. */
+export const runnerTestHooks = {
+  execFileSync: null,
+  spawn: null
+};
+
 function printRunnerHelp(primaryCommand = 'ovld') {
   console.log(`Usage:
   ${primaryCommand} runner once [options]
@@ -45,7 +51,7 @@ function parseFlags(args) {
   return flags;
 }
 
-function readOrCreateDeviceFingerprint(flags) {
+export function readOrCreateDeviceFingerprint(flags) {
   const explicit =
     typeof flags['device-fingerprint'] === 'string'
       ? flags['device-fingerprint'].trim()
@@ -69,7 +75,8 @@ function readOrCreateDeviceFingerprint(flags) {
 }
 
 function runOvld(args, env = {}) {
-  return execFileSync(process.execPath, [OVLD_ENTRY, ...args], {
+  const exec = runnerTestHooks.execFileSync ?? execFileSync;
+  return exec(process.execPath, [OVLD_ENTRY, ...args], {
     encoding: 'utf8',
     env: { ...process.env, ...env }
   });
@@ -111,7 +118,7 @@ function failLaunch(requestId, deviceFingerprint, error) {
   );
 }
 
-function buildLaunchArgs(launch) {
+export function buildLaunchArgs(launch) {
   const args = ['launch', launch.agent, '--ticket-id', launch.ticketId];
   if (launch.workingDirectory) args.push('--working-directory', launch.workingDirectory);
   if (launch.launchMode === 'ask') args.push('--launch-mode', 'ask');
@@ -127,7 +134,7 @@ function buildLaunchArgs(launch) {
   return args;
 }
 
-async function launchClaimedRequest(claim, deviceFingerprint) {
+export async function launchClaimedRequest(claim, deviceFingerprint) {
   const requestId = claim.request?.id;
   if (!requestId || !claim.launch?.agent || !claim.launch?.ticketId) return false;
 
@@ -137,7 +144,8 @@ async function launchClaimedRequest(claim, deviceFingerprint) {
   );
 
   await new Promise((resolve, reject) => {
-    const child = spawn(process.execPath, [OVLD_ENTRY, ...args], {
+    const spawnImpl = runnerTestHooks.spawn ?? spawn;
+    const child = spawnImpl(process.execPath, [OVLD_ENTRY, ...args], {
       stdio: 'inherit',
       env: { ...process.env, OVERLORD_DEVICE_FINGERPRINT: deviceFingerprint }
     });
@@ -170,7 +178,7 @@ async function launchClaimedRequest(claim, deviceFingerprint) {
   return true;
 }
 
-async function runOnce(flags, deviceFingerprint) {
+export async function runOnce(flags, deviceFingerprint) {
   const claim = claimExecution(flags, deviceFingerprint);
   if (!claim.request) {
     process.stderr.write('[runner] no queued execution requests\n');

package/bin/_cli/setup.mjs

@@ -14,10 +14,86 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { checkForCliUpdate, getCurrentCliVersion, printCliUpdateNotice } from './cli-update.mjs';
-import {
-  geminiLegacyCommandFiles,
-  removeLegacyGeminiConnector as removeLegacyGeminiConnectorFiles
-} from '../../../../lib/overlord/legacy-gemini-connector.cjs';
+
+// ---------------------------------------------------------------------------
+// Legacy Gemini connector (inlined — the lib/ directory is not published with
+// the npm package, so the old relative import broke on global installs)
+// ---------------------------------------------------------------------------
+
+const GEMINI_LEGACY_COMMANDS_DIR = path.join(os.homedir(), '.gemini', 'commands');
+
+function geminiLegacyCommandFiles() {
+  const base = GEMINI_LEGACY_COMMANDS_DIR;
+  return [
+    {
+      path: path.join(base, 'connect.toml'),
+      content: `description = "Connect this session to another Overlord ticket (requires: ticket-id)."\nprompt = """\nConnect this session to another Overlord ticket.\n\nTreat \`{{args}}\` as the target ticket ID.\nIf no ticket ID was provided, ask the user for one and stop.\n\nRun:\n\`ovld protocol connect --ticket-id <ticket_id>\`\n\nRules:\n- Use \`connect\`, not \`attach\`.\n- Do not load extra ticket context unless the user explicitly asks for it.\n- After the command succeeds, report the returned \`SESSION_KEY\` and confirm that future updates should use that ticket.\n"""`
+    },
+    {
+      path: path.join(base, 'load.toml'),
+      content: `description = "Load Overlord ticket context (requires: ticket-id)."\nprompt = """\nLoad Overlord ticket context without attaching to the ticket.\n\nTreat \`{{args}}\` as the target ticket ID.\nIf no ticket ID was provided, ask the user for one and stop.\n\nRun:\n\`ovld protocol load-context --ticket-id <ticket_id>\`\n\nRules:\n- Use \`load-context\`, not \`attach\`.\n- Do not create or switch sessions.\n- Summarize the returned ticket details, history, artifacts, and shared context for the user.\n"""`
+    },
+    {
+      path: path.join(base, 'attach.toml'),
+      content: `description = "Attach this session to an Overlord ticket (requires: ticket-id)."\nprompt = """\nAttach this session to an Overlord ticket.\n\nTreat \`{{args}}\` as the target ticket ID.\nIf no ticket ID was provided, ask the user for one and stop.\n\nRun:\n\`ovld protocol attach --ticket-id <ticket_id>\`\n\nRules:\n- Use \`attach\` to establish a persistent session with a ticket.\n- After the command succeeds, report the returned \`SESSION_KEY\` and confirm that future updates should use that ticket.\n"""`
+    },
+    {
+      path: path.join(base, 'discuss-objective.toml'),
+      content: `description = "Mark a ticket's draft objective as submitted (in discussion)."\nprompt = """\nMark a draft objective as "submitted", indicating the ticket is in active discussion with an agent.\n\nTreat \`{{args}}\` as the target ticket ID.\nIf no ticket ID was provided, ask the user for one and stop.\n\nRun:\n\`ovld protocol discuss-objective --ticket-id <ticket_id>\`\n\nRules:\n- This does NOT start execution. Use \`attach\` for that.\n- After the command succeeds, confirm the objective was submitted.\n"""`
+    },
+    {
+      path: path.join(base, 'add-objectives.toml'),
+      content: `description = "Append ordered objectives to an existing Overlord ticket."\nprompt = """\nAppend ordered objectives to an existing ticket.\n\nUse this when prompts are sequential steps toward the same feature or goal. Create separate tickets when prompts represent different features or goals.\n\nRun:\n\`ovld protocol add-objectives --ticket-id <ticket_id> --objectives-json '[{"objective":"Step one"},{"objective":"Step two"}]'\`\n\nIndex 0 is the first newly added objective to execute; later indexes queue after it.\n"""`
+    },
+    {
+      path: path.join(base, 'create.toml'),
+      content: `description = "Create a draft Overlord ticket from the current conversation."\nprompt = """\nCreate a draft Overlord ticket from the user's request.\n\nUse \`{{args}}\` as the input.\nIf it already contains flags such as \`--title\`, \`--priority\`, \`--project-id\`, or \`--execution-target\`, pass those flags through after \`ovld protocol create --agent gemini\`.\nOtherwise, treat \`{{args}}\` as the objective text and run:\n\`ovld protocol create --agent gemini --objective "<objective>"\`\n\nIf no objective was provided, ask the user for one and stop.\n\nAfter the command succeeds, report the new \`TICKET_ID\`.\n"""`
+    },
+    {
+      path: path.join(base, 'prompt.toml'),
+      content: `description = "Create a new Overlord ticket from the current conversation."\nprompt = """\nCreate a new Overlord ticket from the user's request.\n\nUse \`{{args}}\` as the input.\nIf it already contains flags such as \`--title\`, \`--priority\`, \`--project-id\`, or \`--execution-target\`, pass those flags through after \`ovld protocol prompt --agent gemini\`.\nOtherwise, treat \`{{args}}\` as the objective text and run:\n\`ovld protocol prompt --agent gemini --objective "<objective>"\`\n\nIf no objective was provided, ask the user for one and stop.\n\nAfter the command succeeds, report the new \`TICKET_ID\` and \`SESSION_KEY\`.\n"""`
+    },
+    {
+      path: path.join(base, 'record-work.toml'),
+      content: `description = "Record completed-from-chat work as a ticket in review + feed post (no attach)."\nprompt = """\nImmediately record the work you just completed in this chat as a new Overlord ticket via \`ovld protocol record-work\`. No agent session is opened — the work is already done.\n\nSynthesize from the current conversation:\n- \`objective\`: what was asked / what was done.\n- \`summary\`: reviewer-friendly narrative for the feed.\n- \`changeRationales\`: one entry per meaningful git-tracked file change (\`label\`, \`file_path\`, \`summary\`, \`why\`, \`impact\`, optional \`hunks\`). Use \`git status\` and \`git diff\` to enumerate changed files.\n- \`artifacts\` (optional): \`next_steps\`, \`test_results\`, \`decision\`, \`note\`, \`url\`.\n\nIf \`{{args}}\` is non-empty, treat it as additional context to weave into the summary.\n\nRun \`ovld protocol record-work --payload-file -\` and stream a JSON object \`{ "objective": "...", "summary": "...", "artifacts": [...], "changeRationales": [...] }\` on stdin via a single-quoted heredoc.\n\nAfter the command succeeds, report the new \`TICKET_ID\`.\n\nRules:\n- Do NOT use this for in-progress work. Use \`/prompt\` for that.\n- The CLI validates that every changed git-tracked file is represented in \`changeRationales\` unless \`--skip-file-change-check\` is passed.\n- If project resolution fails, re-run with \`--project-id <id>\` or \`--personal\`.\n"""`
+    }
+  ];
+}
+
+function isRemovableLegacyGeminiCommandFile({ filePath, content, manifestFiles }) {
+  if (manifestFiles.has(filePath)) return true;
+  const managed = geminiLegacyCommandFiles().find(file => file.path === filePath);
+  if (!managed) return false;
+  return content.trim() === managed.content.trim();
+}
+
+function removeLegacyGeminiConnectorFiles({ readManifest, writeManifest, readTextFile, existsSync = fs.existsSync.bind(fs), rmSync = fs.rmSync.bind(fs) }) {
+  const removed = [];
+  const manifest = readManifest();
+  const manifestFiles = new Set(manifest.gemini?.files ?? []);
+
+  for (const file of geminiLegacyCommandFiles()) {
+    if (!existsSync(file.path)) continue;
+    const existing = readTextFile(file.path);
+    if (!isRemovableLegacyGeminiCommandFile({ filePath: file.path, content: existing, manifestFiles })) continue;
+    rmSync(file.path, { force: true });
+    removed.push(file.path);
+  }
+
+  for (const filePath of manifestFiles) {
+    if (removed.includes(filePath) || !existsSync(filePath)) continue;
+    if (!filePath.includes('.gemini/commands') || !filePath.endsWith('.toml')) continue;
+    rmSync(filePath, { force: true });
+    removed.push(filePath);
+  }
+
+  if (manifest.gemini) {
+    delete manifest.gemini;
+    writeManifest(manifest);
+  }
+
+  return removed;
+}
 
 const BUNDLE_VERSION = '1.12.0';
 const MD_MARKER_START = '<!-- overlord:managed:start -->';

package/package.json

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