overlord-cli 0.2605210944.0 → 0.2605211800.0

package/README.md

@@ -68,6 +68,7 @@ ovld protocol discover-project
 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
+ovld runner start
 ovld setup
 ovld setup codex
 ovld setup claude
@@ -100,6 +101,7 @@ Top-level commands (see `ovld help`):
 - `tickets` - `create` or `list` (optional `--status`)
 - `ticket` - `context <ticketId>` to print context for one ticket
 - `launch`, `restart` - launch or resume an agent session
+- `runner` - claim queued execution requests and launch assigned agents with `ovld launch`
 - `connect`, `run`, `resume` - legacy aliases for `launch` and `restart`
 - `setup` - install the Overlord connector for an agent; `ovld setup [agent|all]` (interactive with no args). `ovld setup claude` also performs the one-time v3.25.0 to v4 Claude plugin migration
 - `update` - install the latest CLI release from npm
@@ -137,9 +139,12 @@ Agents can find docs here: https://www.ovld.ai/docs/for-agents
 - `attachment-upload-file` - prepare, upload, and finalize a local objective attachment in one command
 - `get-device` / `update-device` - register the caller machine (per organization + user + fingerprint) and rename its label
 - `list-project-resources` / `add-project-resource` / `update-project-resource` - manage filesystem directories tied to a project device
+- `request-execution` / `claim-execution` / `complete-execution-launch` / `fail-execution-launch` - durable runner queue operations used by auto-advance and manual Run
 
 Devices are keyed by **(organization, user, fingerprint)** so the same physical workstation can appear once per org session.
 
+`ovld runner start` keeps a foreground runner alive for CLI-only or remote hosts. It claims compatible execution requests for the current device and launches the assigned agent/model with `ovld launch`; `ovld runner once` claims at most one request and exits.
+
 Use `create` for future work you want to track, `prompt` for work that should start immediately, and `record-work` for work that was already completed in chat and now needs a review ticket plus feed post. Use multiple tickets when prompts represent different features or goals; use `add-objectives` or `--objectives-json '[{"objective":"Step one"},{"objective":"Step two"}]'` when prompts are sequential steps toward the same feature or goal.
 
 `ovld protocol deliver` accepts either discrete flags like `--summary` / `--artifacts-json`, an inline full payload with `--payload-json '{"summary":"...","artifacts":[...],"changeRationales":[...]}'`, or a file/stdin payload with `--payload-file <path|->`.

package/bin/_cli/index.mjs

@@ -5,6 +5,7 @@ import { runAuthCommand } from './auth.mjs';
 import { checkForCliUpdate, printCliUpdateNotice, runCliUpdateCommand } from './cli-update.mjs';
 import { runLauncherCommand } from './launcher.mjs';
 import { runProtocolCommand } from './protocol.mjs';
+import { runRunnerCommand } from './runner.mjs';
 import { runDoctorCommand, runSetupCommand } from './setup.mjs';
 import { runTicketCommand } from './ticket.mjs';
 import { runTicketsCommand } from './tickets.mjs';
@@ -35,6 +36,7 @@ Usage:
   ${primaryCommand} tickets <subcommand>       Create or list tickets
   ${primaryCommand} ticket <subcommand>        Work with a single ticket
   ${primaryCommand} protocol <subcommand>      Agent workflow commands
+  ${primaryCommand} runner <subcommand>        Claim and launch queued execution requests
   ${primaryCommand} launch <agent>             Launch an agent on a ticket
   ${primaryCommand} connect <agent>            Launch an agent on a ticket (legacy alias)
   ${primaryCommand} restart <agent>            Resume an agent session
@@ -127,6 +129,11 @@ export async function runCli({ primaryCommand }) {
     return;
   }
 
+  if (command === 'runner') {
+    await runRunnerCommand(rest[0], rest.slice(1), primaryCommand);
+    return;
+  }
+
   if (command === 'setup') {
     await runSetupCommand(rest);
     return;

package/bin/_cli/protocol.mjs

@@ -230,6 +230,23 @@ function resolveTimeout(flags) {
   return DEFAULT_TIMEOUT_MS;
 }
 
+function parseRepeatedCliFlags(args, name) {
+  const result = [];
+  const prefix = `--${name}=`;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === `--${name}` && i + 1 < args.length) {
+      result.push(args[i + 1]);
+      i++;
+      continue;
+    }
+    if (arg.startsWith(prefix)) {
+      result.push(arg.slice(prefix.length));
+    }
+  }
+  return result;
+}
+
 function requireFlag(flags, name, envAlias) {
   const value = flags[name] ?? (envAlias ? process.env[envAlias] : undefined);
   if (!value) {
@@ -1821,6 +1838,155 @@ async function protocolUpdateProjectResource(args) {
   console.log(JSON.stringify(data, null, 2));
 }
 
+// ---------------------------------------------------------------------------
+// execution requests (durable runner queue)
+// ---------------------------------------------------------------------------
+
+async function protocolRequestExecution(args) {
+  const flags = parseFlags(args);
+  const ticketId = requireFlag(flags, 'ticket-id', 'TICKET_ID');
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
+  const timeoutMs = resolveTimeout(flags);
+
+  const body = {
+    ticketId,
+    ...(typeof flags['objective-id'] === 'string' ? { objectiveId: flags['objective-id'] } : {}),
+    requestedFrom: String(flags['requested-from'] ?? 'api'),
+    ...(typeof flags['idempotency-key'] === 'string'
+      ? { idempotencyKey: flags['idempotency-key'] }
+      : {}),
+    ...(typeof flags.agent === 'string' ? { agentIdentifier: flags.agent } : {}),
+    ...(typeof flags.model === 'string' ? { modelIdentifier: flags.model } : {}),
+    ...(typeof flags.thinking === 'string' ? { thinkingLevel: flags.thinking } : {}),
+    launchMode: flags['launch-mode'] === 'ask' ? 'ask' : 'run',
+    flags: parseRepeatedCliFlags(args, 'flag'),
+    ...(typeof flags['working-directory'] === 'string'
+      ? { workingDirectory: flags['working-directory'] }
+      : {}),
+    ...(typeof flags['ssh-command'] === 'string' ? { sshCommand: flags['ssh-command'] } : {}),
+    ...(typeof flags['remote-working-directory'] === 'string'
+      ? { remoteWorkingDirectory: flags['remote-working-directory'] }
+      : {}),
+    ...(flags['server-multiplexer'] === 'tmux' ? { serverMultiplexer: 'tmux' } : {}),
+    ...(typeof flags['tmux-command'] === 'string' ? { tmuxCommand: flags['tmux-command'] } : {}),
+    ...(typeof flags['target-kind'] === 'string' ? { targetKind: flags['target-kind'] } : {}),
+    ...(typeof flags['target-device-id'] === 'string'
+      ? { targetDeviceId: flags['target-device-id'] }
+      : {}),
+    ...(typeof flags['target-resource-id'] === 'string'
+      ? { targetResourceId: flags['target-resource-id'] }
+      : {})
+  };
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/request-execution',
+    body,
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+
+  if (data.request?.id) {
+    process.stderr.write(`\nEXECUTION_REQUEST_ID=${data.request.id}\n`);
+  }
+}
+
+async function protocolClaimExecution(args) {
+  const flags = parseFlags(args);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags);
+  const timeoutMs = resolveTimeout(flags);
+  const deviceFingerprint = String(
+    flags['device-fingerprint'] ?? process.env.OVERLORD_DEVICE_FINGERPRINT ?? ''
+  );
+  if (!deviceFingerprint) {
+    console.error('Error: --device-fingerprint is required (or set OVERLORD_DEVICE_FINGERPRINT)');
+    process.exit(1);
+  }
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/claim-execution',
+    {
+      deviceFingerprint,
+      ...(flags['device-hostname'] ? { deviceHostname: String(flags['device-hostname']) } : {}),
+      ...(flags['device-platform'] ? { devicePlatform: String(flags['device-platform']) } : {}),
+      ...(typeof flags['lease-seconds'] === 'string'
+        ? { leaseSeconds: Number.parseInt(flags['lease-seconds'], 10) }
+        : {}),
+      ...(typeof flags['project-id'] === 'string' ? { projectId: flags['project-id'] } : {})
+    },
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function protocolCompleteExecutionLaunch(args) {
+  const flags = parseFlags(args);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags);
+  const timeoutMs = resolveTimeout(flags);
+  const requestId = requireFlag(flags, 'request-id', 'EXECUTION_REQUEST_ID');
+  const deviceFingerprint = String(
+    flags['device-fingerprint'] ?? process.env.OVERLORD_DEVICE_FINGERPRINT ?? ''
+  );
+  if (!deviceFingerprint) {
+    console.error('Error: --device-fingerprint is required (or set OVERLORD_DEVICE_FINGERPRINT)');
+    process.exit(1);
+  }
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/complete-execution-launch',
+    {
+      requestId,
+      deviceFingerprint,
+      ...(typeof flags['launched-session-id'] === 'string'
+        ? { launchedSessionId: flags['launched-session-id'] }
+        : {})
+    },
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function protocolFailExecutionLaunch(args) {
+  const flags = parseFlags(args);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags);
+  const timeoutMs = resolveTimeout(flags);
+  const requestId = requireFlag(flags, 'request-id', 'EXECUTION_REQUEST_ID');
+  const deviceFingerprint = String(
+    flags['device-fingerprint'] ?? process.env.OVERLORD_DEVICE_FINGERPRINT ?? ''
+  );
+  if (!deviceFingerprint) {
+    console.error('Error: --device-fingerprint is required (or set OVERLORD_DEVICE_FINGERPRINT)');
+    process.exit(1);
+  }
+  const error = requireFlag(flags, 'error');
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/fail-execution-launch',
+    { requestId, deviceFingerprint, error },
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+}
+
 // ---------------------------------------------------------------------------
 // connect (lightweight session, no context returned)
 // ---------------------------------------------------------------------------
@@ -2349,6 +2515,10 @@ Subcommands:
   record-change-rationales  Persist structured change rationales without a progress update
   ask                       Post a blocking question and move the ticket to review
   request-approval-gate     Flip auto_advance=false on the next queued future objective
+  request-execution         Queue an objective for local/remote runner execution
+  claim-execution           Claim one queued execution request for this device
+  complete-execution-launch Mark a claimed execution request launched
+  fail-execution-launch     Mark a claimed execution request failed
   permission-request        Notify Overlord that the agent is requesting tool permission
   hook-event                Record a lifecycle hook event without a session key
   read-context              Read shared persistent context for this ticket
@@ -2779,6 +2949,47 @@ update-project-resource:
     --label <text>             New label (pass 'null' to clear)
     --is-primary <true|false>
 
+request-execution:
+  Required:
+    --ticket-id <ticket_id>
+  Optional:
+    --objective-id <uuid>
+    --requested-from <source>  manual_run | auto_advance | api | ssh
+    --idempotency-key <key>
+    --agent <agent>
+    --model <model>
+    --thinking <level>
+    --flag <value>             Extra agent flag (repeatable)
+    --working-directory <path>
+    --ssh-command <command>
+    --remote-working-directory <path>
+    --server-multiplexer <none|tmux>
+    --target-kind <any|local|ssh>
+    --target-device-id <uuid>
+    --target-resource-id <uuid>
+
+claim-execution:
+  Required:
+    --device-fingerprint <fp>  (or OVERLORD_DEVICE_FINGERPRINT env var)
+  Optional:
+    --device-hostname <name>
+    --device-platform <platform>
+    --lease-seconds <n>
+    --project-id <uuid>
+
+complete-execution-launch:
+  Required:
+    --request-id <uuid>        (or EXECUTION_REQUEST_ID env var)
+    --device-fingerprint <fp>  (or OVERLORD_DEVICE_FINGERPRINT env var)
+  Optional:
+    --launched-session-id <uuid>
+
+fail-execution-launch:
+  Required:
+    --request-id <uuid>        (or EXECUTION_REQUEST_ID env var)
+    --device-fingerprint <fp>  (or OVERLORD_DEVICE_FINGERPRINT env var)
+    --error <message>
+
 Examples:
   ovld protocol auth-status
   ovld protocol discover-project
@@ -2808,6 +3019,8 @@ Examples:
   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 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"
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --summary "Done" --artifacts-file ./artifacts.json
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --payload-json '{"summary":"Done","artifacts":[{"type":"note","label":"Delivery","content":"..."}]}'
@@ -2915,6 +3128,22 @@ EOF
     await protocolRequestApprovalGate(args);
     return;
   }
+  if (subcommand === 'request-execution') {
+    await protocolRequestExecution(args);
+    return;
+  }
+  if (subcommand === 'claim-execution') {
+    await protocolClaimExecution(args);
+    return;
+  }
+  if (subcommand === 'complete-execution-launch') {
+    await protocolCompleteExecutionLaunch(args);
+    return;
+  }
+  if (subcommand === 'fail-execution-launch') {
+    await protocolFailExecutionLaunch(args);
+    return;
+  }
   if (subcommand === 'permission-request') {
     await protocolPermissionRequest(args);
     return;

package/bin/_cli/runner.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+
+import { execFileSync, spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const OVLD_ENTRY = process.argv[1];
+const DEVICE_FILE = path.join(os.homedir(), '.ovld', 'device.json');
+
+function printRunnerHelp(primaryCommand = 'ovld') {
+  console.log(`Usage:
+  ${primaryCommand} runner once [options]
+  ${primaryCommand} runner start [options]
+  ${primaryCommand} runner status [options]
+
+Options:
+  --device-fingerprint <fp>  Override runner device identity
+  --poll-interval-ms <ms>    Poll interval for start mode (default 3000)
+  --project-id <uuid>        Only claim requests for one project
+
+The runner claims durable execution requests and launches them with \`${primaryCommand} launch\`.
+`);
+}
+
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) continue;
+    const eqIdx = arg.indexOf('=');
+    if (eqIdx !== -1) {
+      flags[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1);
+      continue;
+    }
+    const key = arg.slice(2);
+    if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+      flags[key] = args[i + 1];
+      i++;
+    } else {
+      flags[key] = true;
+    }
+  }
+  return flags;
+}
+
+function readOrCreateDeviceFingerprint(flags) {
+  const explicit =
+    typeof flags['device-fingerprint'] === 'string'
+      ? flags['device-fingerprint'].trim()
+      : process.env.OVERLORD_DEVICE_FINGERPRINT?.trim();
+  if (explicit) return explicit;
+
+  try {
+    const raw = fs.readFileSync(DEVICE_FILE, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.deviceFingerprint === 'string' && parsed.deviceFingerprint.trim()) {
+      return parsed.deviceFingerprint.trim();
+    }
+  } catch {
+    // Create below.
+  }
+
+  const deviceFingerprint = crypto.randomUUID();
+  fs.mkdirSync(path.dirname(DEVICE_FILE), { recursive: true });
+  fs.writeFileSync(DEVICE_FILE, `${JSON.stringify({ deviceFingerprint }, null, 2)}\n`, 'utf8');
+  return deviceFingerprint;
+}
+
+function runOvld(args, env = {}) {
+  return execFileSync(process.execPath, [OVLD_ENTRY, ...args], {
+    encoding: 'utf8',
+    env: { ...process.env, ...env }
+  });
+}
+
+function protocolJson(subcommand, args, env) {
+  const stdout = runOvld(['protocol', subcommand, ...args], env);
+  return stdout.trim() ? JSON.parse(stdout) : {};
+}
+
+function claimExecution(flags, deviceFingerprint) {
+  const args = [
+    '--device-fingerprint',
+    deviceFingerprint,
+    '--device-hostname',
+    os.hostname(),
+    '--device-platform',
+    process.platform
+  ];
+  if (typeof flags['project-id'] === 'string') {
+    args.push('--project-id', flags['project-id']);
+  }
+  return protocolJson('claim-execution', args, { OVERLORD_DEVICE_FINGERPRINT: deviceFingerprint });
+}
+
+function completeLaunch(requestId, deviceFingerprint) {
+  protocolJson(
+    'complete-execution-launch',
+    ['--request-id', requestId, '--device-fingerprint', deviceFingerprint],
+    { OVERLORD_DEVICE_FINGERPRINT: deviceFingerprint }
+  );
+}
+
+function failLaunch(requestId, deviceFingerprint, error) {
+  protocolJson(
+    'fail-execution-launch',
+    ['--request-id', requestId, '--device-fingerprint', deviceFingerprint, '--error', error],
+    { OVERLORD_DEVICE_FINGERPRINT: deviceFingerprint }
+  );
+}
+
+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');
+  if (launch.model) args.push('--model', launch.model);
+  if (launch.thinking) args.push('--thinking', launch.thinking);
+  for (const flag of launch.flags ?? []) args.push('--flag', flag);
+  if (launch.sshCommand) args.push('--ssh-command', launch.sshCommand);
+  if (launch.remoteWorkingDirectory) {
+    args.push('--remote-working-directory', launch.remoteWorkingDirectory);
+  }
+  if (launch.serverMultiplexer === 'tmux') args.push('--server-multiplexer', 'tmux');
+  if (launch.tmuxCommand) args.push('--tmux-command', launch.tmuxCommand);
+  return args;
+}
+
+async function launchClaimedRequest(claim, deviceFingerprint) {
+  const requestId = claim.request?.id;
+  if (!requestId || !claim.launch?.agent || !claim.launch?.ticketId) return false;
+
+  const args = buildLaunchArgs(claim.launch);
+  process.stderr.write(
+    `[runner] launching ${claim.launch.agent} for ${claim.launch.ticketId} (${requestId})\n`
+  );
+
+  await new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [OVLD_ENTRY, ...args], {
+      stdio: 'inherit',
+      env: { ...process.env, OVERLORD_DEVICE_FINGERPRINT: deviceFingerprint }
+    });
+
+    child.once('spawn', () => {
+      try {
+        completeLaunch(requestId, deviceFingerprint);
+      } catch (error) {
+        process.stderr.write(`[runner] failed to mark request launched: ${error}\n`);
+      }
+    });
+
+    child.once('error', error => {
+      try {
+        failLaunch(requestId, deviceFingerprint, error.message);
+      } catch {
+        // Preserve the original launch error.
+      }
+      reject(error);
+    });
+
+    child.once('close', code => {
+      if (code && code !== 0) {
+        process.stderr.write(`[runner] launch process exited with code ${code}\n`);
+      }
+      resolve();
+    });
+  });
+
+  return true;
+}
+
+async function runOnce(flags, deviceFingerprint) {
+  const claim = claimExecution(flags, deviceFingerprint);
+  if (!claim.request) {
+    process.stderr.write('[runner] no queued execution requests\n');
+    return false;
+  }
+  await launchClaimedRequest(claim, deviceFingerprint);
+  return true;
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export async function runRunnerCommand(subcommand, args, primaryCommand = 'ovld') {
+  if (!subcommand || subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
+    printRunnerHelp(primaryCommand);
+    return;
+  }
+
+  const flags = parseFlags(args);
+  const deviceFingerprint = readOrCreateDeviceFingerprint(flags);
+
+  if (subcommand === 'status') {
+    const data = protocolJson(
+      'get-device',
+      [
+        '--device-fingerprint',
+        deviceFingerprint,
+        '--device-hostname',
+        os.hostname(),
+        '--device-platform',
+        process.platform
+      ],
+      { OVERLORD_DEVICE_FINGERPRINT: deviceFingerprint }
+    );
+    console.log(JSON.stringify({ ok: true, device: data.device }, null, 2));
+    return;
+  }
+
+  if (subcommand === 'once') {
+    await runOnce(flags, deviceFingerprint);
+    return;
+  }
+
+  if (subcommand === 'start') {
+    const pollIntervalMs =
+      typeof flags['poll-interval-ms'] === 'string'
+        ? Math.max(1000, Number.parseInt(flags['poll-interval-ms'], 10) || 3000)
+        : 3000;
+    process.stderr.write(`[runner] started with device ${deviceFingerprint}\n`);
+    for (;;) {
+      try {
+        const launched = await runOnce(flags, deviceFingerprint);
+        if (!launched) await sleep(pollIntervalMs);
+      } catch (error) {
+        process.stderr.write(`[runner] ${error instanceof Error ? error.message : error}\n`);
+        await sleep(pollIntervalMs);
+      }
+    }
+  }
+
+  console.error(`Unknown runner command: ${subcommand}\n`);
+  printRunnerHelp(primaryCommand);
+  process.exit(1);
+}

package/package.json

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

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

@@ -7,6 +7,8 @@ ovld protocol get-device --device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"
 ovld protocol list-project-resources --project-id <project_uuid> --device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"
 ```
 
+`ovld runner start` uses the same device identity and project resource directories to claim queued execution requests from manual Run and auto-advance. `ovld runner once` claims at most one request and exits.
+
 ## Choosing `--execution-target`
 
 Pass `--execution-target agent` or `--execution-target human` (default: `human`) when creating tickets.

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

@@ -3,6 +3,7 @@
 - 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`).
 - `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.
 - "Artifacts" in `deliver` are the structured records an agent submits at delivery time (next_steps, test_results, migration, decision, note, url) — not user-uploaded files. Files attached by users live on objectives via the attachment tools above.

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

@@ -7,6 +7,8 @@ ovld protocol get-device --device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"
 ovld protocol list-project-resources --project-id <project_uuid> --device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"
 ```
 
+`ovld runner start` uses the same device identity and project resource directories to claim queued execution requests from manual Run and auto-advance. `ovld runner once` claims at most one request and exits.
+
 ## Choosing `--execution-target`
 
 Pass `--execution-target agent` or `--execution-target human` (default: `human`) when creating tickets.

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

@@ -3,6 +3,7 @@
 - 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`).
 - `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.
 - "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/skills/overlord-ticket/reference/devices.md

@@ -7,6 +7,8 @@ ovld protocol get-device --device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"
 ovld protocol list-project-resources --project-id <project_uuid> --device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"
 ```
 
+`ovld runner start` uses the same device identity and project resource directories to claim queued execution requests from manual Run and auto-advance. `ovld runner once` claims at most one request and exits.
+
 ## Choosing `--execution-target`
 
 Pass `--execution-target agent` or `--execution-target human` (default: `human`) when creating tickets.

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

@@ -3,6 +3,7 @@
 - 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`).
 - `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.
 - "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.