overlord-cli 0.2606010745.0 → 0.2606021051.0

package/README.md

@@ -141,7 +141,7 @@ Agents can find docs here: https://www.ovld.ai/docs/for-agents
 - `record-change-rationales` - persist structured change rationales without a normal progress update
 - `ask` - post a blocking question and move the ticket to review
 - `permission-request` - notify Overlord that the agent is requesting tool permission
-- `hook-event` - record lifecycle hook events such as `UserPromptSubmit` / Cursor `beforeSubmitPrompt` without a session key
+- `hook-event` - record lifecycle hook events such as `UserPromptSubmit` / Cursor `beforeSubmitPrompt` without a session key; optionally persist a native resume/session id onto the active Overlord session
 - `read-context` - read shared persistent context for this ticket
 - `write-context` - write shared persistent context for future sessions
 - `deliver` - send artifacts/rationales and move the ticket to review
@@ -158,6 +158,8 @@ Devices are keyed by **(organization, user, fingerprint)** so the same physical
 
 `ovld runner start` keeps a foreground runner alive for CLI-only or remote hosts. It claims compatible execution requests for the current device and launches the assigned agent/model with `ovld launch`; `ovld runner once` claims at most one request and exits. `ovld runner status` now prints the local device record plus the active queue visible to that runner. `ovld runner clear <objective_id>` clears one queued objective, and `ovld runner clear-all` clears every active queue row visible to the caller. By default a single runner drains queued requests from **every organization you belong to**, so you do not need one runner per org. Pin it to a single org with `--organization-id <id>` or `OVERLORD_ORGANIZATION_ID`.
 
+If you are troubleshooting "why is `ovld runner` randomly executing", the runner is usually claiming a request that was already queued by manual Run or auto-advance. Inspect the queue with `ovld runner status`, then clear the specific objective with `ovld runner clear 8974e557-bec4-4984-b12c-be46bd63207c` or `ovld protocol clear-execution-requests --objective-id 8974e557-bec4-4984-b12c-be46bd63207c`.
+
 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

@@ -34,6 +34,7 @@ Usage:
   ${primaryCommand} create "<objective>"       Create a ticket with numbered project selection; supports --agent/--model/--delegate
   ${primaryCommand} prompt "<objective>"       Create a ticket, then launch an agent on it
   ${primaryCommand} add-cwd                   Register the current directory as a project resource (interactive)
+  ${primaryCommand} onboard                   Create an account, project, cwd link, and onboarding ticket
   ${primaryCommand} auth <subcommand>          Login, logout, repair, or check auth status
   ${primaryCommand} tickets <subcommand>       Create or list tickets
   ${primaryCommand} ticket <subcommand>        Work with a single ticket
@@ -117,6 +118,12 @@ export async function runCli({ primaryCommand }) {
     return;
   }
 
+  if (command === 'onboard') {
+    const { runOnboardCommand } = await import('./onboard.mjs');
+    await runOnboardCommand(rest);
+    return;
+  }
+
   // Auth group
   if (command === 'auth') {
     await runAuthCommand(rest[0], rest.slice(1));

package/bin/_cli/onboard.mjs

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+import { stdin as input, stdout as output } from 'node:process';
+
+import { authLoginViaDeviceFlow, resolveLoginPlatformUrl } from './auth.mjs';
+import {
+  buildAuthHeaders,
+  loadCredentials,
+  loadRuntime,
+  saveCredentials
+} from './credentials.mjs';
+import { upsertLocalOverlordConfig } from './local-config.mjs';
+import { readOrCreateDeviceFingerprint } from './runner.mjs';
+
+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 openBrowser(url) {
+  try {
+    if (process.platform === 'darwin') execFileSync('open', [url]);
+    else if (process.platform === 'win32') execFileSync('cmd', ['/c', 'start', '', url]);
+    else execFileSync('xdg-open', [url]);
+  } catch {
+    // Best effort. The URL is also printed.
+  }
+}
+
+function trimFlag(flags, name) {
+  const value = flags[name];
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+async function promptForValue(question, defaultValue = '') {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return defaultValue;
+  }
+
+  const rl = readline.createInterface({ input, output });
+  try {
+    return await new Promise((resolve, reject) => {
+      const handleError = error => {
+        rl.off('error', handleError);
+        reject(error);
+      };
+      rl.once('error', handleError);
+      const suffix = defaultValue ? ` (${defaultValue})` : '';
+      rl.question(`${question}${suffix}: `, answer => {
+        rl.off('error', handleError);
+        const trimmed = answer.trim();
+        resolve(trimmed || defaultValue);
+      });
+    });
+  } finally {
+    rl.close();
+  }
+}
+
+async function promptForYes(question, defaultYes = true) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return defaultYes;
+  }
+
+  const rl = readline.createInterface({ input, output });
+  try {
+    return await new Promise((resolve, reject) => {
+      const handleError = error => {
+        rl.off('error', handleError);
+        reject(error);
+      };
+      rl.once('error', handleError);
+      const suffix = defaultYes ? 'Y/n' : 'y/N';
+      rl.question(`${question} (${suffix}): `, answer => {
+        rl.off('error', handleError);
+        const normalized = answer.trim().toLowerCase();
+        if (!normalized) resolve(defaultYes);
+        else resolve(normalized === 'y' || normalized === 'yes');
+      });
+    });
+  } finally {
+    rl.close();
+  }
+}
+
+function buildSignupUrl(platformUrl, verificationUri, name) {
+  const verificationUrl = new URL(verificationUri);
+  const signupUrl = new URL('/signup', platformUrl);
+  signupUrl.searchParams.set('next', `${verificationUrl.pathname}${verificationUrl.search}`);
+  if (name) signupUrl.searchParams.set('name', name);
+  return signupUrl.toString();
+}
+
+async function completeCliOnboarding(platformUrl, localSecret, credentials, payload) {
+  const res = await fetch(`${platformUrl}/api/auth/cli-onboarding`, {
+    method: 'POST',
+    headers: {
+      ...buildAuthHeaders(credentials.access_token, localSecret),
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(payload)
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(
+      `Onboarding setup failed (${res.status}): ${data.error ?? JSON.stringify(data)}`
+    );
+  }
+  return data;
+}
+
+function buildWebProjectUrl(platformUrl, result) {
+  const projectId = result?.project?.id;
+  if (!projectId) return `${platformUrl}/u`;
+  return `${platformUrl}/projects/${projectId}`;
+}
+
+export async function runOnboardCommand(args) {
+  const flags = parseFlags(args);
+
+  if (flags.help === true || flags.h === true || args[0] === 'help') {
+    console.log(`Usage: ovld onboard [--name <name>] [--organization-name <name>] [--project-name <name>] [--directory <path>] [--yes] [--no-desktop]
+
+Creates an Overlord account setup from the terminal:
+  1. collects your name, organization, project, and repository directory
+  2. opens browser signup/login and authorizes the CLI
+  3. creates the organization/project, links this directory, and creates the first onboarding ticket
+  4. opens the Desktop download page, or the web project when --no-desktop is used
+
+Run this from the repository you want Overlord agents to work in.`);
+    return;
+  }
+
+  const directoryPath = path.resolve(trimFlag(flags, 'directory') || process.cwd());
+  const directoryName = path.basename(directoryPath) || 'My project';
+  const inferredName = os.userInfo().username || 'User';
+  const name = trimFlag(flags, 'name') || (await promptForValue('Your name', inferredName));
+  const organizationName =
+    trimFlag(flags, 'organization-name') || (await promptForValue('Organization name', name));
+  const projectName =
+    trimFlag(flags, 'project-name') || (await promptForValue('Project name', directoryName));
+
+  if (!name || !organizationName || !projectName) {
+    throw new Error('Name, organization name, and project name are required.');
+  }
+
+  const storedCredentials = loadCredentials();
+  const platformUrl = resolveLoginPlatformUrl(null, storedCredentials?.platform_url ?? null);
+  const runtime = loadRuntime(platformUrl);
+  const localSecret = runtime?.local_secret ?? process.env.OVERLORD_LOCAL_SECRET ?? '';
+
+  console.log('\nStarting Overlord onboarding in your browser.');
+  console.log('Create an account or sign in, then approve the CLI authorization request.\n');
+
+  const credentials = await authLoginViaDeviceFlow(platformUrl, localSecret, {
+    browserOpener: verificationUri => {
+      const signupUrl = buildSignupUrl(platformUrl, verificationUri, name);
+      console.log(`  Signup URL: ${signupUrl}`);
+      openBrowser(signupUrl);
+    }
+  });
+
+  const resolvedPlatformUrl = credentials.platform_url ?? platformUrl;
+  const deviceFingerprint = readOrCreateDeviceFingerprint(flags);
+  const result = await completeCliOnboarding(resolvedPlatformUrl, localSecret, credentials, {
+    name,
+    organizationName,
+    projectName,
+    directoryPath,
+    deviceFingerprint,
+    deviceHostname: os.hostname(),
+    devicePlatform: process.platform
+  });
+
+  saveCredentials({
+    access_token: credentials.access_token,
+    access_token_expires_at: credentials.access_token_expires_at ?? undefined,
+    refresh_token: credentials.refresh_token,
+    organization_id: result.organization.organizationId,
+    platform_url: resolvedPlatformUrl
+  });
+
+  try {
+    const localConfig = await upsertLocalOverlordConfig({
+      directoryPath,
+      project: { id: result.project.id, name: result.project.name }
+    });
+    console.log(`\nWrote ${localConfig.filePath} (${localConfig.action}).`);
+  } catch (error) {
+    console.log(
+      `\nWarning: could not update .overlord/project.json: ${error instanceof Error ? error.message : error}`
+    );
+  }
+
+  console.log('\nOverlord setup complete.');
+  console.log(`  Organization: ${result.organization.organizationName}`);
+  console.log(`  Project: ${result.project.name}`);
+  console.log(`  Directory: ${directoryPath}`);
+  console.log(`  Onboarding ticket: ${result.ticket.reference ?? result.ticket.id}`);
+
+  const skipDesktop = flags['no-desktop'] === true || flags.desktop === 'false';
+  const autoYes = flags.yes === true || flags.y === true;
+  const shouldOpenDesktop =
+    !skipDesktop &&
+    (autoYes ||
+      (await promptForYes(
+        '\nRecommended: download Overlord Desktop for terminal launches and file-change tracking. Open downloads now?',
+        true
+      )));
+
+  if (shouldOpenDesktop) {
+    const downloadsUrl = `${resolvedPlatformUrl}/downloads`;
+    console.log(`Opening ${downloadsUrl}`);
+    openBrowser(downloadsUrl);
+  } else {
+    const webUrl = buildWebProjectUrl(resolvedPlatformUrl, result);
+    console.log(`Opening ${webUrl}`);
+    openBrowser(webUrl);
+  }
+
+  console.log('\nNext command from this repo:');
+  console.log('  ovld prompt --objectives-json \'[{"objective":"Describe the work you want done"}]\'');
+}

package/bin/_cli/protocol.mjs

@@ -85,6 +85,18 @@ async function resolveProtocolMetadata(flags = {}, base = {}) {
     metadata.model = modelIdentifier;
   }
 
+  // Thread the originating execution request id (set by the runner via
+  // OVERLORD_EXECUTION_REQUEST_ID, or an explicit flag) into attach metadata so
+  // the server marks that exact request `launched` instead of falling back to
+  // matching by objective.
+  const executionRequestId =
+    (typeof flags['execution-request-id'] === 'string'
+      ? flags['execution-request-id'].trim()
+      : '') || process.env.OVERLORD_EXECUTION_REQUEST_ID?.trim();
+  if (executionRequestId) {
+    metadata.executionRequestId = executionRequestId;
+  }
+
   const snapshot = await resolveSnapshotContext(flags);
   if (snapshot) {
     metadata.snapshot = snapshot;
@@ -1284,6 +1296,12 @@ async function protocolHookEvent(args) {
       ? { turnIndex: parseInt(String(flags['turn-index']), 10) }
       : {}),
     ...(flags['follow-up-intent'] ? { followUpIntent: String(flags['follow-up-intent']) } : {}),
+    ...(() => {
+      if (flags['external-session-id'] === undefined) return {};
+      const raw = String(flags['external-session-id']).trim();
+      if (raw === '') return {};
+      return { externalSessionId: raw.toLowerCase() === 'null' ? null : raw };
+    })(),
     ...(sessionKey ? { sessionKey } : {})
   };
 
@@ -2188,11 +2206,13 @@ async function protocolConnect(args) {
   const { platformUrl, bearerToken, localSecret, organizationId } =
     await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
+  const externalSessionId = resolveExternalSessionId(flags);
 
   const body = {
     ticketId,
     agentIdentifier: resolveProtocolAgentIdentifier(flags),
     connectionMethod: String(flags.method ?? 'cli'),
+    ...(externalSessionId !== undefined ? { externalSessionId } : {}),
     metadata: await resolveProtocolMetadata(flags, { cwd: process.cwd() })
   };
 
@@ -2801,9 +2821,12 @@ connect:
     --agent <identifier>
     --model <identifier>
     --method <connectionMethod>
+    --external-session-id <id|null>  Store the native agent thread/session id, or clear it with null
     --metadata-json <json>     Extra session metadata object
   Returns:
     Session JSON and SESSION_KEY on stderr when available
+  Notes:
+    If --external-session-id is omitted, the CLI may auto-detect Codex or Claude session ids
 
 load-context:
   Purpose:
@@ -2926,6 +2949,7 @@ hook-event:
     --prompt <text>
     --turn-index <n>
     --follow-up-intent <mode> discussion | execution | pending_delivery
+    --external-session-id <id|null>  Native agent resume/session id to persist on the attached session
 
 read-context:
   Purpose:

package/bin/_cli/runner.mjs

@@ -171,13 +171,17 @@ function resolvePinnedOrganizationId(flags) {
 const ORGANIZATION_REFRESH_MS = 60_000;
 
 /**
- * Resolves which organizations a poll pass should claim from.
+ * Resolves which organizations a fan-out pass (list / clear-all) should act on.
  *
  * - When the user pins an org (`--organization-id` flag or
- *   `OVERLORD_ORGANIZATION_ID`), only that org is polled.
- * - Otherwise the runner discovers every org the authenticated user belongs to
- *   and polls each one. If discovery fails or returns nothing, it falls back to
- *   the credential default (an empty scope id) so behavior never regresses.
+ *   `OVERLORD_ORGANIZATION_ID`), only that org is used.
+ * - Otherwise the runner discovers every org the authenticated user belongs to.
+ *   If discovery fails or returns nothing, it falls back to the credential
+ *   default (an empty scope id) so behavior never regresses.
+ *
+ * NOTE: this is for the per-org fan-out commands. The claim poll uses
+ * {@link createClaimOrganizationScope}, which is org-agnostic — the server's
+ * `claim-execution` is authoritative and spans the user's target-sharing orgs.
  */
 export function createOrganizationScope(flags, deviceFingerprint) {
   const pinned = resolvePinnedOrganizationId(flags);
@@ -211,6 +215,17 @@ export function createOrganizationScope(flags, deviceFingerprint) {
   };
 }
 
+/**
+ * Resolves the org scope for the claim poll (G3). A pinned org still scopes the
+ * poll; otherwise the runner does a single org-agnostic poll (empty scope) and
+ * lets the server claim across every org the user belongs to that shares the
+ * claiming target — no org discovery or per-org looping needed.
+ */
+export function createClaimOrganizationScope(flags) {
+  const pinned = resolvePinnedOrganizationId(flags);
+  return { pinned: Boolean(pinned), resolve: () => [pinned || ''] };
+}
+
 function completeLaunch(requestId, deviceFingerprint) {
   protocolJson(
     'complete-execution-launch',
@@ -276,11 +291,19 @@ function normalizeRunnerTerminalProfile(value) {
   };
 }
 
-function buildRunnerLaunchShellCommand(args, deviceFingerprint) {
-  return [
-    `export OVERLORD_DEVICE_FINGERPRINT=${shellQuote(deviceFingerprint)}`,
+function buildRunnerLaunchShellCommand(args, deviceFingerprint, executionRequestId) {
+  const lines = [`export OVERLORD_DEVICE_FINGERPRINT=${shellQuote(deviceFingerprint)}`];
+  // Terminal-profile launches run this generated script in a fresh shell, so the
+  // request id must be exported here too (the direct-spawn path inherits it via
+  // the child env). Without it, attach in the new terminal falls back to
+  // objective matching.
+  if (executionRequestId) {
+    lines.push(`export OVERLORD_EXECUTION_REQUEST_ID=${shellQuote(executionRequestId)}`);
+  }
+  lines.push(
     `exec ${shellQuote(process.execPath)} ${[OVLD_ENTRY, ...args].map(shellQuote).join(' ')}`
-  ].join('\n');
+  );
+  return lines.join('\n');
 }
 
 function writeRunnerLaunchScript(launchCommand) {
@@ -375,7 +398,7 @@ export function buildRunnerTerminalOpenCommand(
 
 function spawnLaunchProcess(args, claim, deviceFingerprint) {
   const spawnImpl = runnerTestHooks.spawn ?? spawn;
-  const launchCommand = buildRunnerLaunchShellCommand(args, deviceFingerprint);
+  const launchCommand = buildRunnerLaunchShellCommand(args, deviceFingerprint, claim.request?.id);
   const terminalCommand = buildRunnerTerminalOpenCommand(
     claim.launch?.runnerTerminalProfile,
     launchCommand,
@@ -466,7 +489,7 @@ export async function launchClaimedRequest(claim, deviceFingerprint) {
 }
 
 export async function runOnce(flags, deviceFingerprint, organizationScope) {
-  const scope = organizationScope ?? createOrganizationScope(flags, deviceFingerprint);
+  const scope = organizationScope ?? createClaimOrganizationScope(flags);
   const organizationIds = scope.resolve();
 
   let launchedAny = false;

package/package.json

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

@@ -454,6 +454,11 @@ const tools = [
           type: 'string',
           enum: ['discussion', 'execution', 'pending_delivery']
         },
+        external_session_id: {
+          type: ['string', 'null'],
+          description:
+            'Optional native agent resume/session id to persist on the attached Overlord session.'
+        },
         session_key: {
           type: 'string',
           description:
@@ -468,6 +473,7 @@ const tools = [
       prompt: args.prompt,
       'turn-index': args.turn_index,
       'follow-up-intent': args.follow_up_intent,
+      'external-session-id': args.external_session_id,
       'session-key': args.session_key
     }),
     subcommand: 'hook-event'

package/plugins/antigravity/scripts/user-prompt-submit-hook.sh

@@ -72,7 +72,29 @@ if turn_index is None:
         handle.write(str(turn_index))
 
 tid = os.environ.get('TICKET_ID', '')
-print(json.dumps({'hookType': 'UserPromptSubmit', 'ticketId': tid, 'prompt': text, 'turnIndex': turn_index}))
+session_key = os.environ.get('SESSION_KEY') or ''
+if not session_key:
+    encoded = __import__('base64').urlsafe_b64encode(os.getcwd().encode()).decode().rstrip('=')
+    session_file = os.path.join(__import__('tempfile').gettempdir(), f'.overlord-session-{encoded}')
+    try:
+        with open(session_file, encoding='utf-8') as handle:
+            persisted = json.load(handle)
+        if persisted.get('ticketId') == tid:
+            session_key = persisted.get('sessionKey') or ''
+    except Exception:
+        session_key = ''
+
+payload = {
+    'hookType': 'UserPromptSubmit',
+    'ticketId': tid,
+    'prompt': text,
+    'turnIndex': turn_index,
+}
+if sid != 'unknown':
+    payload['externalSessionId'] = sid
+if session_key:
+    payload['sessionKey'] = session_key
+print(json.dumps(payload))
 " 2>/dev/null
   )
   if [ -z "$PAYLOAD" ]; then

package/plugins/claude/scripts/user-prompt-submit-hook.sh

@@ -62,7 +62,29 @@ with open(path, 'w', encoding='utf-8') as handle:
     handle.write(str(turn_index))
 
 tid = os.environ.get('TICKET_ID', '')
-print(json.dumps({'hookType': 'UserPromptSubmit', 'ticketId': tid, 'prompt': text, 'turnIndex': turn_index}))
+session_key = os.environ.get('SESSION_KEY') or ''
+if not session_key:
+    encoded = __import__('base64').urlsafe_b64encode(os.getcwd().encode()).decode().rstrip('=')
+    session_file = os.path.join(__import__('tempfile').gettempdir(), f'.overlord-session-{encoded}')
+    try:
+        with open(session_file, encoding='utf-8') as handle:
+            persisted = json.load(handle)
+        if persisted.get('ticketId') == tid:
+            session_key = persisted.get('sessionKey') or ''
+    except Exception:
+        session_key = ''
+
+payload = {
+    'hookType': 'UserPromptSubmit',
+    'ticketId': tid,
+    'prompt': text,
+    'turnIndex': turn_index,
+}
+if sid != 'unknown':
+    payload['externalSessionId'] = sid
+if session_key:
+    payload['sessionKey'] = session_key
+print(json.dumps(payload))
 " 2>/dev/null
   )
   if [ -z "$PAYLOAD" ]; then

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

@@ -74,7 +74,7 @@ Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`,
 ovld protocol revert --objective-id <objective-id>
 ```
 
-`revert` restores the local working tree to the recorded objective checkpoint and saves a safety ref under `refs/overlord/safety/` first.
+`revert` restores the local working tree to the recorded objective state.
 
 ## Record Change Rationales
 

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

@@ -1,6 +1,6 @@
 # Execution Targets And Checkout Paths
 
-Execution targets are canonical rows keyed by a real `device_fingerprint` when known, or by an SSH placeholder until the remote target registers. Organization labels, user access, SSH credential references, and project membership live in separate association rows. Persist a fingerprint per workstation, upsert via `ovld protocol get-device`, then maintain checkout paths via `list-project-resources`, `add-project-resource`, `update-project-resource`, and `update-device` (`ovld protocol help` lists flags).
+Execution targets are canonical rows keyed by a real `device_fingerprint` when known, or by a placeholder until the target registers. Organization labels, user access, project membership, and project checkout paths live in separate association rows. Persist a fingerprint per machine, upsert via `ovld protocol get-device`, then maintain checkout paths via `list-project-resources`, `add-project-resource`, `update-project-resource`, and `update-device` (`ovld protocol help` lists flags).
 
 ```bash
 ovld protocol get-device --device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"

package/plugins/cursor/hooks/overlord-user-prompt-submit.sh

@@ -46,7 +46,29 @@ with open(path, 'w', encoding='utf-8') as handle:
     handle.write(str(turn_index))
 
 tid = os.environ.get('TICKET_ID', '')
-print(json.dumps({'hookType': 'UserPromptSubmit', 'ticketId': tid, 'prompt': text, 'turnIndex': turn_index}))
+session_key = os.environ.get('SESSION_KEY') or ''
+if not session_key:
+    encoded = __import__('base64').urlsafe_b64encode(os.getcwd().encode()).decode().rstrip('=')
+    session_file = os.path.join(__import__('tempfile').gettempdir(), f'.overlord-session-{encoded}')
+    try:
+        with open(session_file, encoding='utf-8') as handle:
+            persisted = json.load(handle)
+        if persisted.get('ticketId') == tid:
+            session_key = persisted.get('sessionKey') or ''
+    except Exception:
+        session_key = ''
+
+payload = {
+    'hookType': 'UserPromptSubmit',
+    'ticketId': tid,
+    'prompt': text,
+    'turnIndex': turn_index,
+}
+if cid != 'unknown':
+    payload['externalSessionId'] = cid
+if session_key:
+    payload['sessionKey'] = session_key
+print(json.dumps(payload))
 " 2>/dev/null
   )
   if [ -n "$PAYLOAD" ]; then

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

@@ -74,7 +74,7 @@ Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`,
 ovld protocol revert --objective-id <objective-id>
 ```
 
-`revert` restores the local working tree to the recorded objective checkpoint and saves a safety ref under `refs/overlord/safety/` first.
+`revert` restores the local working tree to the recorded objective state.
 
 ## Record Change Rationales
 

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

@@ -1,6 +1,6 @@
 # Execution Targets And Checkout Paths
 
-Execution targets are canonical rows keyed by a real `device_fingerprint` when known, or by an SSH placeholder until the remote target registers. Organization labels, user access, SSH credential references, and project membership live in separate association rows. Persist a fingerprint per workstation, upsert via `ovld protocol get-device`, then maintain checkout paths via `list-project-resources`, `add-project-resource`, `update-project-resource`, and `update-device` (`ovld protocol help` lists flags).
+Execution targets are canonical rows keyed by a real `device_fingerprint` when known, or by a placeholder until the target registers. Organization labels, user access, project membership, and project checkout paths live in separate association rows. Persist a fingerprint per machine, upsert via `ovld protocol get-device`, then maintain checkout paths via `list-project-resources`, `add-project-resource`, `update-project-resource`, and `update-device` (`ovld protocol help` lists flags).
 
 ```bash
 ovld protocol get-device --device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"

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

@@ -139,6 +139,7 @@ const tools = [
         },
         agent: { type: 'string' },
         method: { type: 'string' },
+        external_session_id: { type: ['string', 'null'] },
         metadata: {
           type: 'object',
           description:
@@ -151,6 +152,7 @@ const tools = [
       'ticket-id': args.ticket_id,
       agent: args.agent,
       method: args.method,
+      'external-session-id': args.external_session_id,
       ...(args.metadata && typeof args.metadata === 'object' && !Array.isArray(args.metadata)
         ? { 'metadata-json': args.metadata }
         : {})
@@ -179,7 +181,7 @@ const tools = [
   {
     name: 'revert',
     description:
-      'Restore the local working tree to an objective checkpoint (maps to ovld protocol revert).',
+      'Restore the local working tree to the recorded objective state (maps to ovld protocol revert).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -454,6 +456,11 @@ const tools = [
           type: 'string',
           enum: ['discussion', 'execution', 'pending_delivery']
         },
+        external_session_id: {
+          type: ['string', 'null'],
+          description:
+            'Optional native agent resume/session id to persist on the attached Overlord session.'
+        },
         session_key: {
           type: 'string',
           description:
@@ -468,6 +475,7 @@ const tools = [
       prompt: args.prompt,
       'turn-index': args.turn_index,
       'follow-up-intent': args.follow_up_intent,
+      'external-session-id': args.external_session_id,
       'session-key': args.session_key
     }),
     subcommand: 'hook-event'

package/plugins/overlord/scripts/user-prompt-submit-hook.sh

@@ -28,7 +28,40 @@ if [ -z "$OVERLORD_BASE_URL" ] || [ -z "$OVERLORD_TOKEN" ] || [ -z "${TICKET_ID:
 fi
 
 if [ -n "$OVERLORD_BASE_URL" ] && [ -n "$OVERLORD_TOKEN" ] && [ -n "$TICKET_ID" ]; then
-  PAYLOAD=$(printf '%s' "$BODY" | python3 -c "import json,sys; body=json.load(sys.stdin); print(json.dumps({'hookType': 'UserPromptSubmit', 'ticketId': __import__('os').environ['TICKET_ID'], 'prompt': body.get('prompt', ''), 'turnIndex': body.get('turn_number', 0)}))" 2>/dev/null || echo '')
+  PAYLOAD=$(printf '%s' "$BODY" | python3 -c "
+import base64
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+body = json.load(sys.stdin)
+external_session_id = os.environ.get('CODEX_THREAD_ID') or os.environ.get('CODEX_SESSION_ID') or None
+session_key = os.environ.get('SESSION_KEY') or ''
+
+if not session_key:
+    encoded = base64.urlsafe_b64encode(os.getcwd().encode()).decode().rstrip('=')
+    session_file = Path(tempfile.gettempdir()) / f'.overlord-session-{encoded}'
+    try:
+        persisted = json.loads(session_file.read_text(encoding='utf-8'))
+        if persisted.get('ticketId') == os.environ.get('TICKET_ID'):
+            session_key = persisted.get('sessionKey') or ''
+    except Exception:
+        session_key = ''
+
+payload = {
+    'hookType': 'UserPromptSubmit',
+    'ticketId': os.environ['TICKET_ID'],
+    'prompt': body.get('prompt', ''),
+    'turnIndex': body.get('turn_number', 0),
+}
+if external_session_id:
+    payload['externalSessionId'] = external_session_id
+if session_key:
+    payload['sessionKey'] = session_key
+print(json.dumps(payload))
+" 2>/dev/null || echo '')
   if [ -z "$PAYLOAD" ]; then
     log_hook "failed to build hook-event payload from submit body"
     exit 0

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

@@ -74,7 +74,7 @@ Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`,
 ovld protocol revert --objective-id <objective-id>
 ```
 
-`revert` restores the local working tree to the recorded objective checkpoint and saves a safety ref under `refs/overlord/safety/` first.
+`revert` restores the local working tree to the recorded objective state.
 
 ## Record Change Rationales
 

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

@@ -1,6 +1,6 @@
 # Execution Targets And Checkout Paths
 
-Execution targets are canonical rows keyed by a real `device_fingerprint` when known, or by an SSH placeholder until the remote target registers. Organization labels, user access, SSH credential references, and project membership live in separate association rows. Persist a fingerprint per workstation, upsert via `ovld protocol get-device`, then maintain checkout paths via `list-project-resources`, `add-project-resource`, `update-project-resource`, and `update-device` (`ovld protocol help` lists flags).
+Execution targets are canonical rows keyed by a real `device_fingerprint` when known, or by a placeholder until the target registers. Organization labels, user access, project membership, and project checkout paths live in separate association rows. Persist a fingerprint per machine, upsert via `ovld protocol get-device`, then maintain checkout paths via `list-project-resources`, `add-project-resource`, `update-project-resource`, and `update-device` (`ovld protocol help` lists flags).
 
 ```bash
 ovld protocol get-device --device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"