overlord-cli 0.2605101225.0 → 0.2605111118.0

package/README.md

@@ -74,6 +74,8 @@ ovld setup all
 ovld doctor
 ```
 
+For ticket-scoped protocol and launch commands, `ticket_id` values such as `1:899` carry the organization id. The CLI uses that first, then `--organization-id` for UUID compatibility, then stored auth.
+
 ## Requirements
 
 - Node.js 20 or newer

package/bin/_cli/credentials.mjs

@@ -520,11 +520,20 @@ function isLocalDevCli() {
   return !sourcePath.split(path.sep).includes('node_modules');
 }
 
+function parseOrganizationIdHint(value) {
+  if (typeof value !== 'string' && typeof value !== 'number') return null;
+  const parsed = Number.parseInt(String(value), 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
 /**
  * Resolve the Overlord auth session from env vars or shared credentials.
  * Refreshes OAuth access tokens when possible.
+ *
+ * @param {{ organizationIdHint?: number | string | null }} [options]
  */
-export async function resolveAuth() {
+export async function resolveAuth(options = {}) {
+  const organizationIdHint = parseOrganizationIdHint(options.organizationIdHint);
   const selectedCredentials = selectStoredCredentials();
   const creds = selectedCredentials?.credentials ?? migrateLegacyCredentials();
   const overlordUrlFromEnv = normalizePlatformUrl(process.env.OVERLORD_URL);
@@ -548,7 +557,8 @@ export async function resolveAuth() {
       typeof process.env.OVERLORD_ORGANIZATION_ID === 'string'
         ? Number.parseInt(process.env.OVERLORD_ORGANIZATION_ID, 10)
         : null;
-    if (!Number.isFinite(envOrganizationId)) {
+    const resolvedOrganizationId = organizationIdHint ?? envOrganizationId;
+    if (!Number.isFinite(resolvedOrganizationId)) {
       throw new Error(
         'OVERLORD_ACCESS_TOKEN requires OVERLORD_ORGANIZATION_ID so protocol requests stay scoped.'
       );
@@ -559,7 +569,7 @@ export async function resolveAuth() {
         platformUrl,
         bearerToken: envAccessToken,
         localSecret,
-        organizationId: envOrganizationId,
+        organizationId: resolvedOrganizationId,
         authMode: 'oauth_env'
       };
     }
@@ -606,7 +616,7 @@ export async function resolveAuth() {
       platformUrl,
       bearerToken: nextCredentials.access_token,
       localSecret,
-      organizationId: nextCredentials.organization_id,
+      organizationId: organizationIdHint ?? nextCredentials.organization_id,
       authMode: 'oauth'
     };
   }

package/bin/_cli/launcher.mjs

@@ -72,7 +72,6 @@ const agentIdentifierMap = {
 };
 
 const supportedAgents = ['claude', 'codex', 'cursor', 'gemini', 'opencode'];
-const TICKET_ID_REGEX = /^(\d+):\d+$/;
 
 function shellQuote(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`;
@@ -112,14 +111,17 @@ function parseOrganizationId(value) {
 }
 
 function organizationIdFromTicketId(ticketId) {
-  const match = String(ticketId ?? '').trim().match(TICKET_ID_REGEX);
-  return match ? parseOrganizationId(match[1]) : null;
+  const [organizationPart, _ticketSequencePart, ...rest] = String(ticketId ?? '')
+    .trim()
+    .split(':');
+  if (rest.length > 0) return null;
+  return parseOrganizationId(organizationPart);
 }
 
 function resolveLaunchOrganizationId(ticketId, optionsOrganizationId, authOrganizationId) {
   return (
-    parseOrganizationId(optionsOrganizationId) ??
     organizationIdFromTicketId(ticketId) ??
+    parseOrganizationId(optionsOrganizationId) ??
     parseOrganizationId(authOrganizationId)
   );
 }
@@ -278,8 +280,15 @@ async function runAgent(agent, mode = 'run', options = {}) {
     process.chdir(options.workingDirectory);
   }
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
   const launchOrganizationId = resolveLaunchOrganizationId(
+    ticketId,
+    options.organizationId,
+    null
+  );
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth({
+    organizationIdHint: launchOrganizationId
+  });
+  const resolvedLaunchOrganizationId = resolveLaunchOrganizationId(
     ticketId,
     options.organizationId,
     organizationId
@@ -287,7 +296,7 @@ async function runAgent(agent, mode = 'run', options = {}) {
   if (options.sshCommand?.trim()) {
     const remoteCommand = buildRemoteLaunchCommand(agent, {
       ...options,
-      organizationId: launchOrganizationId
+      organizationId: resolvedLaunchOrganizationId
     });
     try {
       execFileSync('sh', ['-lc', remoteCommand], { stdio: 'inherit', env: process.env });
@@ -303,7 +312,7 @@ async function runAgent(agent, mode = 'run', options = {}) {
     platformUrl,
     bearerToken,
     localSecret,
-    launchOrganizationId,
+    resolvedLaunchOrganizationId,
     ticketId,
     agent
   );
@@ -311,7 +320,9 @@ async function runAgent(agent, mode = 'run', options = {}) {
   const childEnv = {
     ...process.env,
     AGENT_IDENTIFIER: agentIdentifierMap[agent],
-    ...(launchOrganizationId ? { OVERLORD_ORGANIZATION_ID: String(launchOrganizationId) } : {})
+    ...(resolvedLaunchOrganizationId
+      ? { OVERLORD_ORGANIZATION_ID: String(resolvedLaunchOrganizationId) }
+      : {})
   };
   const extraArgs = buildExtraArgs(agent, options);
 

package/bin/_cli/protocol.mjs

@@ -7,6 +7,7 @@ import path from 'node:path';
 
 import { buildAuthHeaders, getAuthStatus, resolveAuth } from './credentials.mjs';
 
+
 /**
  * Parse simple CLI flags: --key value or --key=value
  * @param {string[]} args
@@ -69,7 +70,7 @@ export function resolveProtocolModelIdentifier(flags = {}) {
   return envModel || null;
 }
 
-function resolveProtocolMetadata(flags = {}, base = {}) {
+async function resolveProtocolMetadata(flags = {}, base = {}) {
   const metadata = { ...base };
 
   if (flags['metadata-json']) {
@@ -85,6 +86,11 @@ function resolveProtocolMetadata(flags = {}, base = {}) {
     metadata.model = modelIdentifier;
   }
 
+  const snapshot = await resolveSnapshotContext(flags);
+  if (snapshot) {
+    metadata.snapshot = snapshot;
+  }
+
   return metadata;
 }
 
@@ -233,6 +239,28 @@ function requireFlag(flags, name, envAlias) {
   return String(value);
 }
 
+function parseOrganizationId(value) {
+  if (typeof value !== 'string' && typeof value !== 'number') return null;
+  const parsed = Number.parseInt(String(value), 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
+function organizationIdFromTicketId(ticketId) {
+  const [organizationPart, _ticketSequencePart, ...rest] = String(ticketId ?? '')
+    .trim()
+    .split(':');
+  if (rest.length > 0) return null;
+  return parseOrganizationId(organizationPart);
+}
+
+function resolveOrganizationIdHint(flags, ticketId) {
+  return organizationIdFromTicketId(ticketId) ?? parseOrganizationId(flags['organization-id']);
+}
+
+async function resolveProtocolAuthForFlags(flags, ticketId = '') {
+  return resolveAuth({ organizationIdHint: resolveOrganizationIdHint(flags, ticketId) });
+}
+
 function parseJsonFlag(flagName, rawValue) {
   try {
     return JSON.parse(String(rawValue));
@@ -318,6 +346,19 @@ async function resolveChangeRationales(flags) {
   return [];
 }
 
+async function resolveSnapshotContext(flags) {
+  if (flags['snapshot-file']) {
+    return await readJsonFileOrStdin(String(flags['snapshot-file']), '--snapshot-file');
+  }
+  if (flags['snapshot-json']) {
+    return parseJsonFlag('--snapshot-json', flags['snapshot-json']);
+  }
+  if (process.env.OVERLORD_SNAPSHOT_JSON?.trim()) {
+    return parseJsonFlag('--snapshot-json', process.env.OVERLORD_SNAPSHOT_JSON);
+  }
+  return null;
+}
+
 function normalizeRepoRelativeFilePath(filePath, repoRoot) {
   if (typeof filePath !== 'string') return null;
 
@@ -493,7 +534,7 @@ function resolveExternalSessionId(flags) {
 async function protocolAttach(args) {
   const flags = parseFlags(args);
   const ticketId = requireFlag(flags, 'ticket-id', 'TICKET_ID');
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const externalSessionId = resolveExternalSessionId(flags);
@@ -503,7 +544,7 @@ async function protocolAttach(args) {
     agentIdentifier: resolveProtocolAgentIdentifier(flags),
     connectionMethod: String(flags.method ?? 'cli'),
     ...(externalSessionId !== undefined ? { externalSessionId } : {}),
-    metadata: resolveProtocolMetadata(flags, { cwd: process.cwd() })
+    metadata: await resolveProtocolMetadata(flags, { cwd: process.cwd() })
   };
 
   const data = await apiPost(
@@ -539,10 +580,11 @@ async function protocolUpdate(args) {
     ? readTextFile(String(flags['summary-file']), '--summary-file')
     : requireFlag(flags, 'summary', undefined);
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
   const changeRationales = await resolveChangeRationales(flags);
   const externalSessionId = resolveExternalSessionId(flags);
+  const snapshot = await resolveSnapshotContext(flags);
 
   const body = {
     sessionKey,
@@ -562,6 +604,7 @@ async function protocolUpdate(args) {
     ...(flags['payload-json']
       ? { payload: parseJsonFlag('--payload-json', flags['payload-json']) }
       : {}),
+    ...(snapshot ? { snapshot } : {}),
     ...(changeRationales.length > 0 ? { changeRationales } : {})
   };
 
@@ -594,8 +637,9 @@ async function protocolRecordChangeRationales(args) {
     );
   }
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
+  const snapshot = await resolveSnapshotContext(flags);
 
   const body = {
     sessionKey,
@@ -606,7 +650,8 @@ async function protocolRecordChangeRationales(args) {
       : flags.summary
         ? { summary: String(flags.summary) }
         : {}),
-    ...(flags.phase ? { phase: String(flags.phase) } : {})
+    ...(flags.phase ? { phase: String(flags.phase) } : {}),
+    ...(snapshot ? { snapshot } : {})
   };
 
   const data = await apiPost(
@@ -634,7 +679,7 @@ async function protocolAsk(args) {
     ? readTextFile(String(flags['question-file']), '--question-file')
     : requireFlag(flags, 'question', undefined);
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const body = {
@@ -670,7 +715,7 @@ async function protocolPermissionRequest(args) {
     ? await readJsonFileOrStdin(String(flags['payload-file']), '--payload-file')
     : {};
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const data = await apiPost(
@@ -695,7 +740,7 @@ async function protocolReadContext(args) {
   if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
   if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const body = {
@@ -739,7 +784,7 @@ async function protocolWriteContext(args) {
     value = String(flags.value);
   }
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const body = {
@@ -786,7 +831,7 @@ async function protocolDeliver(args) {
       ? readTextFile(String(flags['summary-file']), '--summary-file')
       : requireFlag(flags, 'summary', undefined));
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   let artifacts = deliverPayload?.artifacts ?? [];
@@ -808,6 +853,7 @@ async function protocolDeliver(args) {
 
   const changeRationales =
     deliverPayload?.changeRationales ?? (await resolveChangeRationales(flags));
+  const snapshot = (await resolveSnapshotContext(flags)) ?? deliverPayload?.snapshot ?? null;
   validateDeliverFileChanges(flags, changeRationales);
 
   const body = {
@@ -815,6 +861,7 @@ async function protocolDeliver(args) {
     ticketId,
     summary,
     artifacts,
+    ...(snapshot ? { snapshot } : {}),
     ...(changeRationales.length > 0 ? { changeRationales } : {})
   };
 
@@ -840,7 +887,7 @@ async function protocolAttachmentList(args) {
   if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
   if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const body = {
@@ -869,7 +916,7 @@ async function protocolAttachmentPrepareUpload(args) {
   const objectiveId = requireFlag(flags, 'objective-id', undefined);
   const fileName = requireFlag(flags, 'file-name', undefined);
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const body = {
@@ -906,7 +953,7 @@ async function protocolAttachmentFinalizeUpload(args) {
   const storagePath = requireFlag(flags, 'storage-path', undefined);
   const label = requireFlag(flags, 'label', undefined);
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const body = {
@@ -946,7 +993,7 @@ async function protocolAttachmentGetDownloadUrl(args) {
     throw new Error('--objective-id is required when using --storage-path');
   }
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const body = {
@@ -987,7 +1034,7 @@ async function protocolAttachmentUploadFile(args) {
   const fileStats = await stat(filePath);
   const fileBytes = await readFile(filePath);
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const metadata = flags['metadata-json']
@@ -1049,7 +1096,8 @@ async function protocolAttachmentUploadFile(args) {
 
 async function protocolDiscoverProject(args) {
   const flags = parseFlags(args);
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags);
   const timeoutMs = resolveTimeout(flags);
 
   const workingDirectory = String(flags['working-directory'] ?? process.cwd());
@@ -1077,14 +1125,14 @@ async function protocolDiscoverProject(args) {
 async function protocolConnect(args) {
   const flags = parseFlags(args);
   const ticketId = requireFlag(flags, 'ticket-id', 'TICKET_ID');
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const body = {
     ticketId,
     agentIdentifier: resolveProtocolAgentIdentifier(flags),
     connectionMethod: String(flags.method ?? 'cli'),
-    metadata: resolveProtocolMetadata(flags, { cwd: process.cwd() })
+    metadata: await resolveProtocolMetadata(flags, { cwd: process.cwd() })
   };
 
   const data = await apiPost(
@@ -1112,7 +1160,7 @@ async function protocolConnect(args) {
 async function protocolLoadContext(args) {
   const flags = parseFlags(args);
   const ticketId = requireFlag(flags, 'ticket-id', 'TICKET_ID');
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const body = { ticketId };
@@ -1136,7 +1184,12 @@ async function protocolLoadContext(args) {
 async function protocolPrompt(args) {
   const flags = parseFlags(args);
   const objective = requireFlag(flags, 'objective', undefined);
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const parentTicketId =
+    flags['parent-ticket-id'] !== undefined
+      ? String(flags['parent-ticket-id'] ?? process.env.TICKET_ID ?? '')
+      : '';
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, parentTicketId);
   const timeoutMs = resolveTimeout(flags);
   const agentIdentifier = resolveProtocolAgentIdentifier(flags);
   const modelIdentifier = resolveProtocolModelIdentifier(flags);
@@ -1152,7 +1205,7 @@ async function protocolPrompt(args) {
     objective,
     agentIdentifier,
     connectionMethod: String(flags.method ?? 'cli'),
-    metadata: resolveProtocolMetadata(flags, { cwd: process.cwd() }),
+    metadata: await resolveProtocolMetadata(flags, { cwd: process.cwd() }),
     ...(flags.title ? { title: String(flags.title) } : {}),
     ...(flags.priority ? { priority: String(flags.priority) } : {}),
     ...(flags['project-id'] ? { projectId: String(flags['project-id']) } : {}),
@@ -1167,9 +1220,7 @@ async function protocolPrompt(args) {
     ...(flags['parent-session-key']
       ? { parentSessionKey: String(flags['parent-session-key']) }
       : {}),
-    ...(flags['parent-ticket-id']
-      ? { parentTicketId: String(flags['parent-ticket-id'] ?? process.env.TICKET_ID ?? '') }
-      : {})
+    ...(parentTicketId ? { parentTicketId } : {})
   };
 
   const data = await apiPost(
@@ -1202,7 +1253,7 @@ async function protocolCreateTicket(args) {
   const flags = parseFlags(args);
   const { sessionKey, ticketId } = resolveSessionFlags(flags);
   const objective = requireFlag(flags, 'objective', undefined);
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
   const agentIdentifier = resolveProtocolAgentIdentifier(flags);
   const modelIdentifier = resolveProtocolModelIdentifier(flags);
@@ -1283,7 +1334,8 @@ async function protocolCreateTicket(args) {
 
 async function protocolSearchTickets(args) {
   const flags = parseFlags(args);
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags);
   const timeoutMs = resolveTimeout(flags);
 
   const statuses = flags.status
@@ -1407,10 +1459,13 @@ Environment fallback:
 Common flags:
   --timeout <ms>              Request timeout in milliseconds (default: ${DEFAULT_TIMEOUT_MS})
   --ticket-id <ticket_id>     Ticket identifier (e.g. 1:899) when the subcommand operates on an existing ticket
+  --organization-id <id>      Legacy organization override for UUID ticket ids; inferred from ticket_id when possible
   --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)
+  --snapshot-json <json>      Snapshot metadata to attach to sessions/file changes
+  --snapshot-file <path|->    Read snapshot metadata JSON from a file or stdin
 
 auth-status:
   Purpose:
@@ -1463,7 +1518,7 @@ load-context:
   Purpose:
     Read ticket details without creating a session
   Required:
-    --ticket-id <id>
+    --ticket-id <ticket_id>
 
 search-tickets:
   Purpose:
@@ -1486,7 +1541,7 @@ update:
     Post progress or activity events during execution
   Required:
     --session-key <key>
-    --ticket-id <id>
+    --ticket-id <ticket_id>
     --summary <text> or --summary-file <path>
   Optional:
     --phase <status>          draft | execute | review | deliver | complete | blocked | cancelled
@@ -1504,7 +1559,7 @@ record-change-rationales:
     Persist structured file-change rationale records without also posting a normal update
   Required:
     --session-key <key>
-    --ticket-id <id>
+    --ticket-id <ticket_id>
     --change-rationales-json <json> or --change-rationales-file <path>
   Optional:
     --summary <text> or --summary-file <path>
@@ -1515,7 +1570,7 @@ ask:
     Raise a blocking question for a human reviewer/PM
   Required:
     --session-key <key>
-    --ticket-id <id>
+    --ticket-id <ticket_id>
     --question <text> or --question-file <path>
   Optional:
     --phase <status>
@@ -1528,7 +1583,7 @@ permission-request:
     Notify Overlord that the local agent runtime is requesting tool permission.
     This is primarily used by installed permission hooks.
   Required:
-    --ticket-id <id>
+    --ticket-id <ticket_id>
   Optional:
     --payload-file <path|->   Hook JSON payload, or stdin when "-"
 
@@ -1537,7 +1592,7 @@ read-context:
     Read persistent shared context written by earlier sessions
   Required:
     --session-key <key>
-    --ticket-id <id>
+    --ticket-id <ticket_id>
   Optional:
     --query <text>            Filter by key substring
     --limit <n>               Max entries to return
@@ -1547,7 +1602,7 @@ write-context:
     Save shared facts for future sessions
   Required:
     --session-key <key>
-    --ticket-id <id>
+    --ticket-id <ticket_id>
     --key <name>
     --value <json-or-string>  Parsed as JSON first; stored as a string if JSON parsing fails
   Optional:
@@ -1558,7 +1613,7 @@ deliver:
     Conclude the session and submit the final narrative plus artifacts/change rationales
   Required:
     --session-key <key>
-    --ticket-id <id>
+    --ticket-id <ticket_id>
     --summary <text> or --summary-file <path>
     or: --payload-file <path|-> containing { summary, artifacts, changeRationales }
   Optional:
@@ -1590,7 +1645,7 @@ prompt:
     --execution-target <t>    agent | human
     --delegate <model>        Model or delegate identifier that created the ticket
     --parent-session-key <key>
-    --parent-ticket-id <id>
+    --parent-ticket-id <ticket_id>
     --agent <identifier>
     --model <identifier>
     --method <connectionMethod>
@@ -1607,7 +1662,7 @@ create:
     --objective <text>
   Optional:
     --session-key <key>
-    --ticket-id <id>
+    --ticket-id <ticket_id>
     --working-directory <path>  Resolve project by your configured local working directory (default: cwd)
     --project-id <id>           Explicit project for standalone draft creation
     --personal                  Create a private standalone draft without a project
@@ -1628,7 +1683,7 @@ create:
 attachment-list:
   Required:
     --session-key <key>
-    --ticket-id <id>
+    --ticket-id <ticket_id>
   Optional:
     --objective-id <id>       Filter to a single objective
   Returns:
@@ -1637,7 +1692,7 @@ attachment-list:
 attachment-prepare-upload:
   Required:
     --session-key <key>
-    --ticket-id <id>
+    --ticket-id <ticket_id>
     --objective-id <id>
     --file-name <name>
   Optional:
@@ -1649,7 +1704,7 @@ attachment-prepare-upload:
 attachment-finalize-upload:
   Required:
     --session-key <key>
-    --ticket-id <id>
+    --ticket-id <ticket_id>
     --objective-id <id>
     --storage-path <path>
     --label <text>
@@ -1661,7 +1716,7 @@ attachment-finalize-upload:
 attachment-download-url:
   Required:
     --session-key <key>
-    --ticket-id <id>
+    --ticket-id <ticket_id>
     one of: --attachment-id <id> | --storage-path <path>
   Optional:
     --objective-id <id>       Required when using --storage-path
@@ -1670,7 +1725,7 @@ attachment-download-url:
 attachment-upload-file:
   Required:
     --session-key <key>
-    --ticket-id <id>
+    --ticket-id <ticket_id>
     --objective-id <id>
     --file <path>
   Optional:
@@ -1684,30 +1739,30 @@ Examples:
   ovld protocol discover-project
   ovld protocol discover-project --working-directory /path/to/repo
   ovld protocol prompt --agent codex --objective "Implement feature X"   # auto-resolves project from cwd
-  ovld protocol attach --ticket-id abc-123
-  ovld protocol attach --ticket-id abc-123 --external-session-id null
-  ovld protocol connect --ticket-id abc-123
-  ovld protocol load-context --ticket-id abc-123
+  ovld protocol attach --ticket-id 1:899
+  ovld protocol attach --ticket-id 1:899 --external-session-id null
+  ovld protocol connect --ticket-id 1:899
+  ovld protocol load-context --ticket-id 1:899
   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 create --agent codex --session-key <key> --ticket-id <ticket_id> --objective "Capture follow-up work"
   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":"@@ ... @@"}]}]'
-  ovld protocol ask --session-key <key> --ticket-id <id> --question-file ./question.txt
-  ovld protocol read-context --session-key <key> --ticket-id <id> --query arch --limit 5
-  ovld protocol write-context --session-key <key> --ticket-id <id> --key "arch" --value '"monorepo"' --tags repo,agent
-  ovld protocol attachment-list --session-key <key> --ticket-id <id>
-  ovld protocol attachment-prepare-upload --session-key <key> --ticket-id <id> --objective-id <objective-id> --file-name spec.pdf --content-type application/pdf
-  ovld protocol attachment-upload-file --session-key <key> --ticket-id <id> --objective-id <objective-id> --file ./spec.pdf
-  ovld protocol attachment-download-url --session-key <key> --ticket-id <id> --attachment-id <attachment-id>
-  ovld protocol deliver --session-key <key> --ticket-id <id> --summary "Done"
-  ovld protocol deliver --session-key <key> --ticket-id <id> --summary "Done" --artifacts-file ./artifacts.json
-  ovld protocol deliver --session-key <key> --ticket-id <id> --payload-file ./deliver.json
-  ovld protocol deliver --session-key <key> --ticket-id <id> --payload-file -
-  ovld protocol deliver --session-key <key> --ticket-id <id> --summary "Done" --skip-file-change-check
-  ovld protocol deliver --session-key <key> --ticket-id <id> --summary "Done" --timeout 60000
+  ovld protocol update --session-key <key> --ticket-id <ticket_id> --summary "Did X" --phase execute
+  ovld protocol update --session-key <key> --ticket-id <ticket_id> --summary-file ./update.txt --event-type user_follow_up
+  ovld protocol record-change-rationales --session-key <key> --ticket-id <ticket_id> --change-rationales-json '[{"label":"...","file_path":"...","summary":"...","why":"...","impact":"...","hunks":[{"header":"@@ ... @@"}]}]'
+  ovld protocol ask --session-key <key> --ticket-id <ticket_id> --question-file ./question.txt
+  ovld protocol read-context --session-key <key> --ticket-id <ticket_id> --query arch --limit 5
+  ovld protocol write-context --session-key <key> --ticket-id <ticket_id> --key "arch" --value '"monorepo"' --tags repo,agent
+  ovld protocol attachment-list --session-key <key> --ticket-id <ticket_id>
+  ovld protocol attachment-prepare-upload --session-key <key> --ticket-id <ticket_id> --objective-id <objective-id> --file-name spec.pdf --content-type application/pdf
+  ovld protocol attachment-upload-file --session-key <key> --ticket-id <ticket_id> --objective-id <objective-id> --file ./spec.pdf
+  ovld protocol attachment-download-url --session-key <key> --ticket-id <ticket_id> --attachment-id <attachment-id>
+  ovld protocol 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-file ./deliver.json
+  ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --payload-file -
+  ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --summary "Done" --skip-file-change-check
+  ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --summary "Done" --timeout 60000
 `);
     return;
   }

package/package.json

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