overlord-cli 5.3.0 → 5.5.0

package/README.md

@@ -36,10 +36,12 @@ overlord help
 
 ### Auth
 ```bash
-# Login to Overlord
+# Repair shared credentials first when a session already exists
+ovld auth repair # mirror and chmod shared Desktop/CLI credentials when possible
+
+# Login to Overlord if repair does not restore access
 ovld auth login #opens a browser when possible and also prints a verification URL/code so login can be completed from another machine over SSH.
 ovld auth status # show current login status (use --verbose for redacted diagnostics)
-ovld auth repair # mirror and chmod shared Desktop/CLI credentials when possible
 ovld auth logout # remove stored credentials
 ```
 
@@ -89,7 +91,7 @@ Top-level commands (see `ovld help`):
 - `auth` - `login`, `status`, `repair` (shared Desktop/CLI credentials), or `logout`
 - `tickets` - `create` or `list` (optional `--status`)
 - `ticket` - `context <ticketId>` to print context for one ticket
-- `connect`, `restart`, `context` - launch or resume an agent session, or print ticket context (`context` requires `TICKET_ID`)
+- `connect`, `restart` - launch or resume an agent session
 - `run`, `resume` - legacy aliases for `connect` 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
@@ -108,7 +110,7 @@ Agents can find docs here: https://www.ovld.ai/docs/for-agents
 - `load-context` - read ticket context without creating a session
 - `search-tickets` - find tickets by keyword, status, project, creator, or update date
 - `create` - create a draft ticket without attaching (standalone or follow-up)
-- `spawn` - create a follow-up ticket and attach to it immediately
+- `prompt` - create a ticket and attach to it immediately (`spawn` is a backward-compatible alias)
 - `update` - post progress, activity events, and optional change rationales
 - `record-change-rationales` - persist structured change rationales without a normal progress update
 - `ask` - post a blocking question and move the ticket to review

package/bin/_cli/auth.mjs

@@ -583,7 +583,13 @@ export async function authLogin(args = []) {
 async function printVerboseAuthStatus() {
   const status = await getAuthStatus();
   if (!status.isLoggedIn) {
-    console.log('Not logged in. Run: ovld auth login');
+    const hasStoredAuth =
+      status.credentialsFileExists || status.legacyCredentialsFileExists || status.electronCredentialsFileExists;
+    console.log(
+      hasStoredAuth
+        ? 'Not logged in. Run: ovld auth repair, then ovld auth login if needed.'
+        : 'Not logged in. Run: ovld auth login'
+    );
   } else {
     console.log('Logged in');
   }
@@ -612,15 +618,24 @@ export async function authStatus(args = []) {
     return;
   }
 
-  const creds = loadCredentials();
-  if (!creds) {
-    console.log('Not logged in. Run: ovld auth login');
+  const status = await getAuthStatus();
+  if (!status.isLoggedIn) {
+    const hasStoredAuth =
+      status.credentialsFileExists || status.legacyCredentialsFileExists || status.electronCredentialsFileExists;
+    console.log(
+      hasStoredAuth
+        ? 'Not logged in. Run: ovld auth repair, then ovld auth login if needed.'
+        : 'Not logged in. Run: ovld auth login'
+    );
     return;
   }
   console.log('Logged in');
-  console.log(`  Platform URL: ${creds.platform_url}`);
-  if (creds.user_email) {
-    console.log(`  Email: ${creds.user_email}`);
+  const creds = loadCredentials();
+  if (creds) {
+    console.log(`  Platform URL: ${creds.platform_url}`);
+    if (creds.user_email) {
+      console.log(`  Email: ${creds.user_email}`);
+    }
   }
 }
 

package/bin/_cli/index.mjs

@@ -37,7 +37,6 @@ Usage:
   ${primaryCommand} protocol <subcommand>      Agent workflow commands
   ${primaryCommand} connect <agent>            Launch an agent on a ticket
   ${primaryCommand} restart <agent>            Resume an agent session
-  ${primaryCommand} context                    Print ticket context (requires TICKET_ID)
   ${primaryCommand} setup [agent|all]          Install Overlord agent connector (interactive if no args)
   ${primaryCommand} update                    Install the latest CLI version from npm
   ${primaryCommand} doctor                     Validate installed agent connectors and check for CLI updates
@@ -46,7 +45,7 @@ Usage:
 
 Agents:
   Use ${primaryCommand} protocol help for ticket lifecycle commands.
-  Key protocol commands: auth-status, discover-project, create, spawn, attach, connect, load-context.
+  Key protocol commands: auth-status, discover-project, create, prompt, attach, connect, load-context.
 
 Auth:
   ${primaryCommand} auth login               Authorize CLI via browser
@@ -157,8 +156,7 @@ export async function runCli({ primaryCommand }) {
     command === 'connect' ||
     command === 'restart' ||
     command === 'run' ||
-    command === 'resume' ||
-    command === 'context'
+    command === 'resume'
   ) {
     await runLauncherCommand(command, rest);
     return;

package/bin/_cli/launcher.mjs

@@ -220,27 +220,6 @@ async function runAgent(agent, mode = 'run') {
   }
 }
 
-async function printContext() {
-  const ticketId = process.env.TICKET_ID;
-  if (!ticketId) {
-    console.error('Missing required environment variable: TICKET_ID\n');
-    console.error('Usage: TICKET_ID=<id> ovld context');
-    console.error('       ovld ticket context <id>  (recommended)');
-    process.exit(1);
-  }
-
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
-  const context = await fetchContext(
-    platformUrl,
-    bearerToken,
-    localSecret,
-    organizationId,
-    ticketId,
-    'claude'
-  );
-  process.stdout.write(context);
-}
-
 export async function runLauncherCommand(command, args) {
   const normalizedCommand = command === 'connect' ? 'run' : command === 'restart' ? 'resume' : command;
   const { positionals, flags } = parseLauncherArgs(args);
@@ -265,11 +244,6 @@ export async function runLauncherCommand(command, args) {
     return;
   }
 
-  if (normalizedCommand === 'context') {
-    await printContext();
-    return;
-  }
-
   // Should not happen if called correctly
   console.error(`Unknown launcher command: ${command}`);
   process.exit(1);

package/bin/_cli/protocol.mjs

@@ -136,13 +136,17 @@ async function apiPost(
 
     let hint = 'Check your network and Overlord server settings.';
     if (causeCode === 'ECONNREFUSED') {
-      hint = 'Connection refused. Verify Overlord is running and OVERLORD_URL points to the correct port.';
+      hint =
+        'Connection refused. Verify Overlord is running and OVERLORD_URL points to the correct port. If this environment is sandboxed or network-restricted, request permission escalation before retrying.';
     } else if (causeCode === 'ENOTFOUND') {
-      hint = 'Host not found. Verify OVERLORD_URL uses a valid hostname.';
+      hint =
+        'Host not found. Verify OVERLORD_URL uses a valid hostname. If this environment is sandboxed or network-restricted, request permission escalation before retrying.';
     } else if (causeCode === 'ETIMEDOUT') {
-      hint = 'Connection timed out. Verify server availability and local firewall/VPN settings.';
+      hint =
+        'Connection timed out. Verify server availability and local firewall/VPN settings. If this environment is sandboxed or network-restricted, request permission escalation before retrying.';
     } else if (requestUrl.includes('localhost') || requestUrl.includes('127.0.0.1')) {
-      hint = 'Local server unreachable. Start Overlord (usually http://localhost:3000) or update OVERLORD_URL.';
+      hint =
+        'Local server unreachable. Start Overlord (usually http://localhost:3000) or update OVERLORD_URL. If this environment is sandboxed or network-restricted, request permission escalation before retrying.';
     }
 
     throw new Error(
@@ -159,7 +163,7 @@ async function apiPost(
     throw new Error(
       `Authentication failed (401): ${data.error ?? 'Invalid or missing token.'}\n` +
       `IMPORTANT: Stop all work immediately. Your Overlord auth session is invalid, expired, or missing required scope.\n` +
-      `The user should sign in again with Overlord Desktop or \`ovld auth login\`.\n` +
+      `The user should try \`ovld auth repair\` first, then sign in again with Overlord Desktop or \`ovld auth login\` if needed.\n` +
       `Ask the user if they would like to proceed without submitting updates to Overlord.`
     );
   }
@@ -1065,10 +1069,10 @@ async function protocolLoadContext(args) {
 }
 
 // ---------------------------------------------------------------------------
-// spawn (create ticket + connect in one call)
+// prompt (create ticket + connect in one call)
 // ---------------------------------------------------------------------------
 
-async function protocolSpawn(args) {
+async function protocolPrompt(args) {
   const flags = parseFlags(args);
   const objective = requireFlag(flags, 'objective', undefined);
   const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
@@ -1106,7 +1110,7 @@ async function protocolSpawn(args) {
     bearerToken,
     localSecret,
     organizationId,
-    '/api/protocol/spawn',
+    '/api/protocol/prompt',
     body,
     timeoutMs
   );
@@ -1283,11 +1287,11 @@ export async function runProtocolCommand(subcommand, args) {
     console.log(`ovld protocol <subcommand> [flags]
 
 Use this for ticket lifecycle work from an agent runtime: create a standalone
-draft with \`ovld protocol create\`, create-and-attach with \`ovld protocol spawn\`,
+draft with \`ovld protocol create\`, create-and-attach with \`ovld protocol prompt\`,
 or attach to an existing ticket with \`ovld protocol attach --ticket-id <id>\`.
 
 Project discovery:
-  When spawning or creating tickets, the CLI automatically resolves the correct
+  When prompting or creating tickets, the CLI automatically resolves the correct
   project by matching your current working directory against your configured
   "Local working directory" for that project (stored per user in Overlord).
   You can also discover the project explicitly:
@@ -1295,7 +1299,7 @@ Project discovery:
     ovld protocol discover-project
     ovld protocol discover-project --working-directory /path/to/repo
 
-  Use --project-id to override automatic resolution on spawn or ticket creation.
+  Use --project-id to override automatic resolution on prompt or ticket creation.
   Use --personal to create a private ticket without assigning any project.
 
 Subcommands:
@@ -1306,7 +1310,7 @@ Subcommands:
   load-context              Read ticket context without creating a session
   search-tickets            Find tickets by keyword, status, project, creator, or update date
   create                    Create a draft ticket without attaching (follow-up or standalone)
-  spawn                     Create a follow-up ticket and attach to it immediately
+  prompt                    Create a ticket and attach to it immediately
   update                    Post progress, activity events, and optional change rationales
   record-change-rationales  Persist structured change rationales without a progress update
   ask                       Post a blocking question and move the ticket to review
@@ -1328,7 +1332,7 @@ Environment fallback:
 Common flags:
   --timeout <ms>              Request timeout in milliseconds (default: ${DEFAULT_TIMEOUT_MS})
   --ticket-id <id>            Ticket id when the subcommand operates on an existing ticket
-  --session-key <key>         Session key returned by attach/connect/spawn
+  --session-key <key>         Session key returned by attach/connect/prompt
   --agent <identifier>        Agent identifier sent to Overlord (default: AGENT_IDENTIFIER or claude-code)
   --model <identifier>        Model identifier to snapshot on executing objectives
   --method <connectionMethod> Connection method sent to Overlord (default: cli)
@@ -1493,9 +1497,9 @@ deliver:
     Do not combine --payload-file with --artifacts-json/--artifacts-file or change-rationale flags.
     In a git workspace, deliver validates that changed files are represented by changeRationales unless skipped.
 
-spawn:
+prompt:
   Purpose:
-    Create a follow-up ticket and attach to it in one call.
+    Create a ticket and attach to it in one call.
     When --project-id is omitted, automatically resolves the project from the
     current working directory (matching against the caller's project_user.local_working_directory).
   Required:
@@ -1594,7 +1598,7 @@ Examples:
   ovld protocol auth-status
   ovld protocol discover-project
   ovld protocol discover-project --working-directory /path/to/repo
-  ovld protocol spawn --agent codex --objective "Implement feature X"   # auto-resolves project from cwd
+  ovld protocol prompt --agent codex --objective "Implement feature X"   # auto-resolves project from cwd
   ovld protocol attach --ticket-id abc-123
   ovld protocol attach --ticket-id abc-123 --external-session-id null
   ovld protocol connect --ticket-id abc-123
@@ -1602,7 +1606,7 @@ Examples:
   ovld protocol search-tickets --query "auth refactor" --status next-up,execute --limit 10
   ovld protocol create --agent codex --objective "Capture follow-up work from this repo"
   ovld protocol create --agent codex --session-key <key> --ticket-id <id> --objective "Capture follow-up work"
-  ovld protocol spawn --agent codex --objective "Implement user auth" --priority high
+  ovld protocol prompt --agent codex --objective "Implement user auth" --priority high
   ovld protocol update --session-key <key> --ticket-id <id> --summary "Did X" --phase execute
   ovld protocol update --session-key <key> --ticket-id <id> --summary-file ./update.txt --event-type user_follow_up
   ovld protocol record-change-rationales --session-key <key> --ticket-id <id> --change-rationales-json '[{"label":"...","file_path":"...","summary":"...","why":"...","impact":"...","hunks":[{"header":"@@ ... @@"}]}]'
@@ -1629,7 +1633,7 @@ Examples:
   if (subcommand === 'load-context') { await protocolLoadContext(args); return; }
   if (subcommand === 'search-tickets') { await protocolSearchTickets(args); return; }
   if (subcommand === 'create' || subcommand === 'create-ticket') { await protocolCreateTicket(args); return; }
-  if (subcommand === 'spawn') { await protocolSpawn(args); return; }
+  if (subcommand === 'prompt' || subcommand === 'spawn') { await protocolPrompt(args); return; }
   if (subcommand === 'artifact-prepare-upload') { await protocolArtifactPrepareUpload(args); return; }
   if (subcommand === 'artifact-finalize-upload') { await protocolArtifactFinalizeUpload(args); return; }
   if (subcommand === 'artifact-download-url') { await protocolArtifactGetDownloadUrl(args); return; }

package/bin/_cli/setup.mjs

@@ -114,7 +114,7 @@ Record only meaningful behavioral changes — skip formatting-only noise. Prefer
 
 When creating tickets from within a repository:
 - Prefer \`ovld protocol create --agent claude-code\` by default for draft ticket creation.
-- Use \`ovld protocol spawn --agent claude-code\` only when the user explicitly asks to create and execute immediately.
+- Use \`ovld protocol prompt --agent claude-code\` only when the user explicitly asks to create and execute immediately.
 - Both commands can resolve the project from the current working directory; use \`--working-directory\` to override.
 
 \`\`\`bash
@@ -122,7 +122,7 @@ ovld protocol create --agent claude-code --objective "Capture follow-up work fro
 \`\`\`
 
 \`\`\`bash
-ovld protocol spawn --agent claude-code --objective "Implement feature X" --priority medium
+ovld protocol prompt --agent claude-code --objective "Implement feature X" --priority medium
 \`\`\`
 
 ## Context & Artifacts
@@ -193,7 +193,7 @@ ovld protocol record-change-rationales --session-key <sessionKey> --ticket-id $T
 
 When creating tickets from within a repository:
 - Prefer \`ovld protocol create --agent opencode\` by default for draft ticket creation.
-- Use \`ovld protocol spawn --agent opencode\` only when the user explicitly asks to create and execute immediately.
+- Use \`ovld protocol prompt --agent opencode\` only when the user explicitly asks to create and execute immediately.
 - Both commands can resolve the project from the current working directory; use \`--working-directory\` to override.
 
 \`\`\`bash
@@ -201,7 +201,7 @@ ovld protocol create --agent opencode --objective "Capture follow-up work from t
 \`\`\`
 
 \`\`\`bash
-ovld protocol spawn --agent opencode --objective "Implement feature X" --priority medium
+ovld protocol prompt --agent opencode --objective "Implement feature X" --priority medium
 \`\`\`
 
 ## Context & Artifacts
@@ -266,7 +266,7 @@ For larger delivery JSON, prefer \`--payload-file -\` with stdin so no scratch f
 Rules:
 - Always attach first and deliver last.
 - Use \`ovld protocol\` commands instead of ad hoc repo scripts for ticket lifecycle work.
-- Prefer \`ovld protocol create --agent cursor\` for draft ticket creation; use \`spawn --agent cursor\` only for create-and-execute requests.
+- Prefer \`ovld protocol create --agent cursor\` for draft ticket creation; use \`prompt --agent cursor\` only for create-and-execute requests.
 - If the user sends a new message during an active ticket session, publish a \`user_follow_up\` event before doing anything else.
 `;
 
@@ -399,14 +399,14 @@ disable-model-invocation: true
 Run \`ovld protocol create --agent claude-code\` with \`$ARGUMENTS\`. If no flags are present, treat the arguments as the objective and call \`ovld protocol create --agent claude-code --objective "<objective>"\`.`
       },
       {
-        path: path.join(base, 'spawn.md'),
+        path: path.join(base, 'prompt.md'),
         content: `---
 description: Create a new Overlord ticket from the current conversation
 argument-hint: <objective or raw flags>
 disable-model-invocation: true
 ---
 
-Run \`ovld protocol spawn --agent claude-code\` with \`$ARGUMENTS\`. If no flags are present, treat the arguments as the objective and call \`ovld protocol spawn --agent claude-code --objective "<objective>"\`.`
+Run \`ovld protocol prompt --agent claude-code\` with \`$ARGUMENTS\`. If no flags are present, treat the arguments as the objective and call \`ovld protocol prompt --agent claude-code --objective "<objective>"\`.`
       }
     ];
   }
@@ -430,9 +430,9 @@ Run \`ovld protocol spawn --agent claude-code\` with \`$ARGUMENTS\`. If no flags
           'Create a draft Overlord ticket.\n\nRun `ovld protocol create --agent cursor --objective "<objective>"` using the text after `/create` unless raw flags were provided. If raw flags were provided, pass them after `ovld protocol create --agent cursor`.\n'
       },
       {
-        path: path.join(base, 'spawn.md'),
+        path: path.join(base, 'prompt.md'),
         content:
-          'Create a new Overlord ticket.\n\nRun `ovld protocol spawn --agent cursor --objective "<objective>"` using the text after `/spawn` unless raw flags were provided. If raw flags were provided, pass them after `ovld protocol spawn --agent cursor`.\n'
+          'Create a new Overlord ticket.\n\nRun `ovld protocol prompt --agent cursor --objective "<objective>"` using the text after `/prompt` unless raw flags were provided. If raw flags were provided, pass them after `ovld protocol prompt --agent cursor`.\n'
       }
     ];
   }
@@ -456,9 +456,9 @@ Run \`ovld protocol spawn --agent claude-code\` with \`$ARGUMENTS\`. If no flags
           'description = "Create a draft Overlord ticket from the current conversation."\nprompt = """\nRun `ovld protocol create --agent gemini --objective "<objective>"` using `{{args}}` as the objective unless raw flags were provided. If raw flags were provided, pass them after `ovld protocol create --agent gemini`.\n"""\n'
       },
       {
-        path: path.join(base, 'spawn.toml'),
+        path: path.join(base, 'prompt.toml'),
         content:
-          'description = "Create a new Overlord ticket from the current conversation."\nprompt = """\nRun `ovld protocol spawn --agent gemini --objective "<objective>"` using `{{args}}` as the objective unless raw flags were provided. If raw flags were provided, pass them after `ovld protocol spawn --agent gemini`.\n"""\n'
+          'description = "Create a new Overlord ticket from the current conversation."\nprompt = """\nRun `ovld protocol prompt --agent gemini --objective "<objective>"` using `{{args}}` as the objective unless raw flags were provided. If raw flags were provided, pass them after `ovld protocol prompt --agent gemini`.\n"""\n'
       }
     ];
   }
@@ -493,13 +493,13 @@ agent: build
 Run \`ovld protocol create --agent opencode\` with \`$ARGUMENTS\`. If no flags are present, treat the arguments as the objective and call \`ovld protocol create --agent opencode --objective "<objective>"\`.`
     },
     {
-      path: path.join(base, 'spawn.md'),
+      path: path.join(base, 'prompt.md'),
       content: `---
 description: Create a new Overlord ticket from the current conversation
 agent: build
 ---
 
-Run \`ovld protocol spawn --agent opencode\` with \`$ARGUMENTS\`. If no flags are present, treat the arguments as the objective and call \`ovld protocol spawn --agent opencode --objective "<objective>"\`.`
+Run \`ovld protocol prompt --agent opencode\` with \`$ARGUMENTS\`. If no flags are present, treat the arguments as the objective and call \`ovld protocol prompt --agent opencode --objective "<objective>"\`.`
     }
   ];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "5.3.0",
+  "version": "5.5.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "type": "module",
   "bin": {

package/plugins/claude/README.md

@@ -5,9 +5,10 @@ Claude Code plugin that exposes the Overlord local ticket workflow to any Claude
 ## What ships
 
 - `skills/overlord-ticket/SKILL.md` — durable attach → update → ask → deliver workflow.
-- `commands/{connect,load,create,spawn}.md` — slash commands for session routing and ticket creation.
+- `commands/{connect,load,create,prompt}.md` — slash commands for session routing and ticket creation.
 - `hooks/hooks.json` + `scripts/permission-hook.sh` — PermissionRequest notifier that calls `ovld protocol permission-request`.
-- `userConfig` for `overlord_url`. Current installs should authenticate with `ovld auth login` or Overlord Desktop; env vars remain optional overrides for remote shells, CI, and explicit OAuth token injection.
+- If `ovld` reports `OVERLORD_URL` is unreachable, the workflow tells agents to request permission escalation or network access before retrying.
+- `userConfig` for `overlord_url`. Current installs should authenticate with `ovld auth repair` first when a shared session already exists, then `ovld auth login` or Overlord Desktop; env vars remain optional overrides for remote shells, CI, and explicit OAuth token injection.
 
 ## Requirements
 
@@ -36,6 +37,6 @@ Older plugin versions prompted for `overlord_url` and a legacy token at install
 Inside Claude Code the components are surfaced with the plugin prefix:
 
 - skill → `overlord:overlord-ticket`
-- commands → `/overlord:connect`, `/overlord:load`, `/overlord:create`, `/overlord:spawn`
+- commands → `/overlord:connect`, `/overlord:load`, `/overlord:create`, `/overlord:prompt`
 
 Prompts generated by Overlord (see `lib/overlord/ticket-prompt.ts`) already reference these names in `bundle` instruction mode.

package/plugins/claude/commands/connect.md

@@ -16,3 +16,4 @@ Rules:
 - Use `connect`, not `attach`.
 - Do not load extra ticket context unless the user explicitly asks for it.
 - After the command succeeds, report the returned `SESSION_KEY` and confirm that future updates should use that ticket.
+- If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.

package/plugins/claude/commands/create.md

@@ -14,3 +14,4 @@ Otherwise, treat `$ARGUMENTS` as the objective text and run:
 If no objective was provided, ask the user for one and stop.
 
 After the command succeeds, report the new `TICKET_ID`.
+- If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.

package/plugins/claude/commands/load.md

@@ -16,3 +16,4 @@ Rules:
 - Use `load-context`, not `attach`.
 - Do not create or switch sessions.
 - Summarize the returned ticket details, history, artifacts, and shared context for the user.
+- If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.

package/plugins/claude/commands/spawn.md

@@ -14,3 +14,4 @@ Otherwise, treat `$ARGUMENTS` as the objective text and run:
 If no objective was provided, ask the user for one and stop.
 
 After the command succeeds, report the new `TICKET_ID` and `SESSION_KEY`.
+- If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.

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

@@ -127,6 +127,15 @@ ovld protocol discover-project
 
 You can override with `--project-id` or `--working-directory` if needed.
 
+### Choosing `--execution-target`
+
+Pass `--execution-target agent` or `--execution-target human` (default: `human`) when creating tickets.
+
+- **`agent`** — any task an AI agent can complete in a computer environment: coding, internet research, document editing, data analysis, automated testing, etc.
+- **`human`** — any task requiring human presence or judgment: setting credentials or tokens in a third-party UI (e.g. Vercel, AWS), sending physical mail, making a product or business decision, physical-world actions.
+
+When in doubt, ask yourself: *can this be done entirely inside a terminal or browser by an AI without human intervention?* If yes → `agent`. If it requires a human to log in, decide, or act in the real world → `human`.
+
 ## Context And Artifacts
 
 ```bash
@@ -143,5 +152,8 @@ ovld protocol artifact-download-url --session-key <sessionKey> --ticket-id $TICK
 - Do not invent protocol subcommands. Use `ovld protocol help` when unsure.
 - The `summary` in deliver is what the PM reads first, so write it as a narrative, not a command list.
 - Use `write-context` for facts a future agent session should know.
+- If `ovld` reports `OVERLORD_URL` is unreachable, request permission escalation or network access before retrying.
 - 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.2.3 -->

package/plugins/cursor/commands/connect.md

@@ -1 +1,3 @@
 Run `ovld protocol connect --ticket-id <ticketId>` using the text after `/connect`.
+
+If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.

package/plugins/cursor/commands/create.md

@@ -7,3 +7,5 @@ Run:
 
 If raw flags are present, pass them through after:
 `ovld protocol create --agent cursor`
+
+If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.

package/plugins/cursor/commands/load.md

@@ -1 +1,3 @@
 Run `ovld protocol load-context --ticket-id <ticketId>` using the text after `/load`.
+
+If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.

package/plugins/cursor/commands/spawn.md

@@ -1 +1,3 @@
 Run `ovld protocol spawn --agent cursor --objective "<objective>"` using text after `/spawn` unless raw flags were provided.
+
+If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.

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

@@ -27,9 +27,22 @@ Use this skill whenever Cursor needs to work with Overlord, whether the session
 6. If you need other lifecycle commands or flags, run `ovld protocol help` and use the real subcommand list instead of guessing.
 7. Once you attach to a ticket, switch back to Mode 1 and follow the full ticket lifecycle.
 
+## Choosing `--execution-target` When Creating Tickets
+
+Pass `--execution-target agent` or `--execution-target human` (default: `human`) when creating tickets.
+
+- **`agent`** — any task an AI agent can complete in a computer environment: coding, internet research, document editing, data analysis, automated testing, etc.
+- **`human`** — any task requiring human presence or judgment: setting credentials or tokens in a third-party UI (e.g. Vercel, AWS), sending physical mail, making a product or business decision, physical-world actions.
+
+When in doubt, ask yourself: *can this be done entirely inside a terminal or browser by an AI without human intervention?* If yes → `agent`. If it requires a human to log in, decide, or act in the real world → `human`.
+
 ## Rules
 
 - Always attach first and always deliver last once you are on a ticket.
 - Use `ovld protocol` commands, the plugin commands, and the MCP tool instead of ad hoc scripts.
 - Do not invent protocol subcommands. Use `ovld protocol help` when unsure.
+- If `ovld` reports `OVERLORD_URL` is unreachable, request permission escalation or network access before retrying.
 - Include at least one progress update before delivering.
+- When creating follow-up tickets, always set `--execution-target` explicitly using the `agent`/`human` rule above.
+
+<!-- version: 0.2.3 -->

package/plugins/overlord/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Chat-driven access to Overlord ticket protocol workflows.",
   "author": {
     "name": "Cooperativ",
@@ -23,9 +23,9 @@
     "privacyPolicyURL": "https://www.ovld.ai/privacy",
     "termsOfServiceURL": "https://www.ovld.ai/terms",
     "defaultPrompt": [
-      "Attach to Overlord ticket 123 and summarize the context before editing code",
-      "Post an execute update to this Overlord ticket after a meaningful implementation step",
-      "Deliver this Overlord ticket with artifacts and change rationales"
+      "Create an Overlord ticket with the objective 'Implement feature X' and summarize the context before editing code",
+      "Execute Overlord ticket [ticket-id]",
+      "Find all Overlord tickets with the status 'next-up' and prioritize the most important one"
     ],
     "brandColor": "#1E6B5C",
     "composerIcon": "./assets/icon.png",

package/plugins/overlord/README.md

@@ -14,8 +14,9 @@ personal marketplace entry at `~/.agents/plugins/marketplace.json`.
 ## Requirements
 
 - Install the Overlord CLI so `ovld` is available on `PATH`.
-- Authenticate with `ovld auth login` or Overlord Desktop. `OVERLORD_URL` can be used to point the CLI at a non-default host.
+- If a shared session already exists but looks stale, authenticate with `ovld auth repair` first. If repair does not help, use `ovld auth login` or Overlord Desktop. `OVERLORD_URL` can be used to point the CLI at a non-default host.
 - Optionally set `OVLD_BIN` if the CLI lives at a non-standard path.
+- If `ovld` reports `OVERLORD_URL` is unreachable, the bundled workflow tells Codex to request permission escalation or network access before retrying.
 
 ## Tool coverage
 

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

@@ -610,10 +610,10 @@ async function handleRequest(message) {
       },
       serverInfo: {
         name: 'overlord',
-        version: '0.1.0'
+        version: '0.1.1'
       },
       instructions:
-        'Use these tools to drive Overlord ticket workflows through the installed ovld CLI. Most operations expect a session key from attach or connect.'
+        'Use these tools to drive Overlord ticket workflows through the installed ovld CLI. Most operations expect a session key from attach or connect. If the CLI reports that OVERLORD_URL is unreachable, request permission escalation or network access before retrying.'
     });
     return;
   }

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

@@ -121,10 +121,22 @@ ovld protocol create --agent codex --objective "Capture follow-up work from this
 ovld protocol spawn --agent codex --objective "Implement feature X" --priority medium
 ```
 
+### Choosing `--execution-target`
+
+Pass `--execution-target agent` or `--execution-target human` (default: `human`) when creating tickets.
+
+- **`agent`** — any task an AI agent can complete in a computer environment: coding, internet research, document editing, data analysis, automated testing, etc.
+- **`human`** — any task requiring human presence or judgment: setting credentials or tokens in a third-party UI (e.g. Vercel, AWS), sending physical mail, making a product or business decision, physical-world actions.
+
+When in doubt, ask yourself: *can this be done entirely inside a terminal or browser by an AI without human intervention?* If yes → `agent`. If it requires a human to log in, decide, or act in the real world → `human`.
+
 ## Rules
 
 - The authoritative lifecycle is the `ovld protocol` CLI once you are on a ticket.
 - Always attach first and always deliver last once you are working a ticket.
 - Prefer the installed `ovld` CLI and the plugin's MCP tools instead of ad hoc repo scripts.
 - Do not create or rely on a local Codex `AGENTS.md` bundle for Overlord.
+- If `ovld` reports `OVERLORD_URL` is unreachable, request permission escalation or network access before retrying.
 - When the ticket was launched by Overlord, the ticket prompt remains authoritative for the specific task objective and ticket-level constraints.
+
+<!-- version: 0.2.3 -->