overlord-cli 0.2605111338.0 → 0.2605120852.0

package/bin/_cli/protocol.mjs

@@ -7,7 +7,6 @@ import path from 'node:path';
 
 import { buildAuthHeaders, getAuthStatus, resolveAuth } from './credentials.mjs';
 
-
 /**
  * Parse simple CLI flags: --key value or --key=value
  * @param {string[]} args
@@ -361,8 +360,8 @@ async function resolveSnapshotContext(flags) {
 
 /**
  * Shallow-merge snapshot metadata: launch/env context first, then deliver payload
- * (payload wins on duplicate keys) so agents can add jj ids without losing workspace
- * paths from OVERLORD_SNAPSHOT_JSON.
+ * (payload wins on duplicate keys) so agents can add provenance details without
+ * losing launch context from OVERLORD_SNAPSHOT_JSON.
  * @param {Record<string, unknown> | null | undefined} fromEnvOrFlags
  * @param {Record<string, unknown> | null | undefined} fromPayload
  * @returns {Record<string, unknown> | null}
@@ -390,133 +389,207 @@ function runLocalCommand(command, args, options = {}) {
   });
 }
 
-function commandSucceeds(command, args, cwd) {
+function resolveGitRepoRoot(workspacePath) {
   try {
-    runLocalCommand(command, args, { cwd, timeoutMs: 15000 });
-    return true;
+    return runLocalCommand('git', ['-C', workspacePath, 'rev-parse', '--show-toplevel'], {
+      cwd: workspacePath,
+      timeoutMs: 15000
+    }).trim();
   } catch {
-    return false;
-  }
-}
-
-function detectLocalCheckpointBackend(workspacePath, preference) {
-  if (!workspacePath || !fs.existsSync(workspacePath)) return null;
-  if (preference === 'jj') return 'jj';
-  if (preference === 'git') return 'git';
-  if (
-    fs.existsSync(path.join(workspacePath, '.jj')) ||
-    commandSucceeds('jj', ['--repository', workspacePath, 'root'], workspacePath)
-  ) {
-    return 'jj';
-  }
-  if (commandSucceeds('git', ['-C', workspacePath, 'rev-parse', '--show-toplevel'], workspacePath)) {
-    return 'git';
+    return null;
   }
-  return null;
 }
 
-function createLocalDeliveryCheckpoint(flags, snapshot) {
+/**
+ * Snapshot the working tree to a hidden ref refs/overlord/checkpoints/<objectiveId>.
+ * Captures tracked + untracked + staged + unstaged in one commit-tree object.
+ * Idempotent: if the ref already exists, returns the existing sha.
+ * Returns null when not in a git repo or when no objectiveId is available.
+ */
+function createLocalCheckpoint({ flags, kind = 'objective', objectiveId, snapshot = null }) {
   if (flags['skip-checkpoint']) return null;
 
-  const preference = String(flags['checkpoint-backend'] ?? 'auto').trim();
-  if (!['auto', 'jj', 'git'].includes(preference)) {
-    throw new Error('--checkpoint-backend must be one of: auto, jj, git');
-  }
-
   const workspacePath = path.resolve(
     String(snapshot?.workspacePath ?? process.env.OVERLORD_WORKSPACE_PATH ?? process.cwd())
   );
-  if (!fs.existsSync(workspacePath)) return null;
-
-  const backend = detectLocalCheckpointBackend(workspacePath, preference);
-  if (!backend) return null;
-
-  if (backend === 'jj') {
+  const repoRoot = fs.existsSync(workspacePath) ? resolveGitRepoRoot(workspacePath) : null;
+  if (!repoRoot) return null;
+
+  const resolvedObjectiveId =
+    objectiveId ?? snapshot?.objectiveId ?? process.env.OVERLORD_OBJECTIVE_ID ?? null;
+  if (!resolvedObjectiveId || !/^[A-Za-z0-9_-]+$/.test(String(resolvedObjectiveId))) {
+    // Without an objective id we cannot name the ref deterministically.
+    // Fall back to recording HEAD only so the protocol still has provenance.
     try {
-      runLocalCommand('jj', ['--repository', workspacePath, 'util', 'snapshot'], {
-        cwd: workspacePath
-      });
-      const commit = runLocalCommand(
-        'jj',
-        ['--repository', workspacePath, 'log', '-r', '@', '-T', 'change_id ++ " " ++ commit_id'],
-        { cwd: workspacePath }
-      );
-      const operation = runLocalCommand(
-        'jj',
-        [
-          '--repository',
-          workspacePath,
-          'op',
-          'log',
-          '--at-op=@',
-          '--ignore-working-copy',
-          '-n',
-          '1',
-          '-T',
-          'id'
-        ],
-        { cwd: workspacePath }
-      );
-      const diffStat = runLocalCommand('jj', ['--repository', workspacePath, 'diff', '--stat'], {
-        cwd: workspacePath
-      });
-      const [jjChangeId = null, jjCommitId = null] = commit.trim().split(/\s+/, 2);
+      const gitCommitId = runLocalCommand('git', ['-C', repoRoot, 'rev-parse', 'HEAD'], {
+        cwd: repoRoot
+      }).trim();
+      const diffStat = runLocalCommand('git', ['-C', repoRoot, 'diff', '--stat', 'HEAD'], {
+        cwd: repoRoot
+      }).trim();
       return {
-        checkpoint: {
-          diffStat: diffStat.trim() || null,
-          kind: 'delivery'
-        },
+        checkpoint: { diffStat: diffStat || null, kind },
         snapshot: {
-          backend: 'jj',
-          workspacePath,
-          workspaceName: snapshot?.workspaceName ?? path.basename(workspacePath),
-          jjChangeId,
-          jjCommitId,
-          jjOperationId: operation.trim() || null,
-          diffStat: diffStat.trim() || null
+          gitCommitId: gitCommitId || null,
+          headSha: gitCommitId || null,
+          diffStat: diffStat || null
         }
       };
-    } catch (error) {
-      throw new Error(
-        `Failed to create JJ delivery checkpoint in ${workspacePath}: ${
-          error instanceof Error ? error.message : String(error)
-        }\nRe-run with --skip-checkpoint only if you intentionally want to deliver without local JJ provenance.`
-      );
+    } catch {
+      return null;
     }
   }
 
-  if (preference === 'jj') {
-    throw new Error(`JJ checkpoint requested, but ${workspacePath} is not a JJ repository.`);
-  }
+  const ref = `refs/overlord/checkpoints/${resolvedObjectiveId}`;
+  const headSha = runLocalCommand('git', ['-C', repoRoot, 'rev-parse', 'HEAD'], {
+    cwd: repoRoot
+  }).trim();
 
+  // If the ref already exists, return the existing snapshot.
+  let existingSha = '';
   try {
-    const gitCommitId = runLocalCommand('git', ['-C', workspacePath, 'rev-parse', 'HEAD'], {
-      cwd: workspacePath
+    existingSha = runLocalCommand('git', ['-C', repoRoot, 'rev-parse', '--verify', ref], {
+      cwd: repoRoot
     }).trim();
-    const diffStat = runLocalCommand('git', ['-C', workspacePath, 'diff', '--stat', 'HEAD'], {
-      cwd: workspacePath
+  } catch {
+    /* not present */
+  }
+
+  if (existingSha) {
+    let diffStat = '';
+    try {
+      diffStat = runLocalCommand('git', ['-C', repoRoot, 'diff', '--stat', `${existingSha}^!`], {
+        cwd: repoRoot
+      }).trim();
+    } catch {
+      /* ignore */
+    }
+    return {
+      checkpoint: { diffStat: diffStat || null, kind },
+      snapshot: {
+        gitCommitId: existingSha,
+        gitRefName: ref,
+        headSha,
+        objectiveId: String(resolvedObjectiveId),
+        diffStat: diffStat || null
+      }
+    };
+  }
+
+  // Build a tree from the current working copy without polluting the user's
+  // index by writing to a temporary index file.
+  const tempIndex = path.join(repoRoot, '.git', `overlord-snap-index-${Date.now()}`);
+  const env = { ...process.env, NO_COLOR: '1', GIT_INDEX_FILE: tempIndex };
+  try {
+    execFileSync('git', ['-C', repoRoot, 'read-tree', 'HEAD'], { cwd: repoRoot, env });
+    execFileSync('git', ['-C', repoRoot, 'add', '-A'], { cwd: repoRoot, env });
+    const tree = execFileSync('git', ['-C', repoRoot, 'write-tree'], {
+      cwd: repoRoot,
+      env,
+      encoding: 'utf8'
     }).trim();
+    if (!tree) throw new Error('git write-tree produced no output.');
+    const commit = execFileSync(
+      'git',
+      [
+        '-C',
+        repoRoot,
+        'commit-tree',
+        tree,
+        '-p',
+        headSha,
+        '-m',
+        `overlord checkpoint ${resolvedObjectiveId}`
+      ],
+      { cwd: repoRoot, env: { ...process.env, NO_COLOR: '1' }, encoding: 'utf8' }
+    ).trim();
+    if (!commit) throw new Error('git commit-tree produced no output.');
+    execFileSync('git', ['-C', repoRoot, 'update-ref', ref, commit], {
+      cwd: repoRoot
+    });
+    let diffStat = '';
+    try {
+      diffStat = runLocalCommand('git', ['-C', repoRoot, 'diff', '--stat', `${commit}^!`], {
+        cwd: repoRoot
+      }).trim();
+    } catch {
+      /* ignore */
+    }
     return {
-      checkpoint: {
-        diffStat: diffStat || null,
-        kind: 'delivery'
-      },
+      checkpoint: { diffStat: diffStat || null, kind },
       snapshot: {
-        backend: 'git',
-        workspacePath,
-        workspaceName: snapshot?.workspaceName ?? path.basename(workspacePath),
-        gitCommitId: gitCommitId || null,
+        gitCommitId: commit,
+        gitRefName: ref,
+        headSha,
+        objectiveId: String(resolvedObjectiveId),
         diffStat: diffStat || null
       }
     };
-  } catch {
-    if (preference === 'git') {
-      throw new Error(`Git checkpoint requested, but metadata could not be read in ${workspacePath}.`);
+  } catch (error) {
+    throw new Error(
+      `Failed to create git checkpoint in ${repoRoot}: ${
+        error instanceof Error ? error.message : String(error)
+      }\nRe-run attach with --skip-checkpoint to proceed without local provenance.`
+    );
+  } finally {
+    try {
+      fs.unlinkSync(tempIndex);
+    } catch {
+      /* ignore */
     }
-    return null;
   }
 }
 
+async function createAndRecordPendingCheckpoints({
+  attachData,
+  bearerToken,
+  flags,
+  localSecret,
+  organizationId,
+  platformUrl,
+  ticketId,
+  timeoutMs
+}) {
+  const pendingObjectiveIds = Array.isArray(attachData.pendingCheckpointObjectiveIds)
+    ? attachData.pendingCheckpointObjectiveIds.filter(id => typeof id === 'string' && id.trim())
+    : [];
+  const sessionKey = attachData.session?.sessionKey;
+  if (!sessionKey || pendingObjectiveIds.length === 0) return [];
+
+  const recorded = [];
+  for (const objectiveId of pendingObjectiveIds) {
+    const checkpointResult = createLocalCheckpoint({
+      flags,
+      kind: 'objective',
+      objectiveId: objectiveId.trim()
+    });
+    if (!checkpointResult?.snapshot) {
+      process.stderr.write(
+        `[protocol] Skipped checkpoint for objective ${objectiveId}: no git repository found at ${process.cwd()}.\n`
+      );
+      continue;
+    }
+
+    await apiPost(
+      platformUrl,
+      bearerToken,
+      localSecret,
+      organizationId,
+      '/api/protocol/update',
+      {
+        sessionKey,
+        ticketId,
+        summary: `Created local git checkpoint for objective ${objectiveId}.`,
+        phase: 'execute',
+        snapshot: checkpointResult.snapshot
+      },
+      timeoutMs
+    );
+    recorded.push(objectiveId);
+  }
+  return recorded;
+}
+
 function normalizeRepoRelativeFilePath(filePath, repoRoot) {
   if (typeof filePath !== 'string') return null;
 
@@ -692,7 +765,8 @@ 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 resolveProtocolAuthForFlags(flags, ticketId);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const externalSessionId = resolveExternalSessionId(flags);
@@ -715,6 +789,20 @@ async function protocolAttach(args) {
     timeoutMs
   );
 
+  const recordedCheckpointObjectiveIds = await createAndRecordPendingCheckpoints({
+    attachData: data,
+    bearerToken,
+    flags,
+    localSecret,
+    organizationId,
+    platformUrl,
+    ticketId,
+    timeoutMs
+  });
+  if (recordedCheckpointObjectiveIds.length > 0) {
+    data.recordedCheckpointObjectiveIds = recordedCheckpointObjectiveIds;
+  }
+
   const sessionKey = data.session?.sessionKey;
   console.log(JSON.stringify(data, null, 2));
 
@@ -738,7 +826,8 @@ async function protocolUpdate(args) {
     ? readTextFile(String(flags['summary-file']), '--summary-file')
     : requireFlag(flags, 'summary', undefined);
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
   const changeRationales = await resolveChangeRationales(flags);
   const externalSessionId = resolveExternalSessionId(flags);
@@ -795,7 +884,8 @@ async function protocolRecordChangeRationales(args) {
     );
   }
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
   const snapshot = await resolveSnapshotContext(flags);
 
@@ -837,7 +927,8 @@ async function protocolAsk(args) {
     ? readTextFile(String(flags['question-file']), '--question-file')
     : requireFlag(flags, 'question', undefined);
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const body = {
@@ -873,7 +964,8 @@ async function protocolPermissionRequest(args) {
     ? await readJsonFileOrStdin(String(flags['payload-file']), '--payload-file')
     : {};
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const data = await apiPost(
@@ -898,7 +990,8 @@ 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 resolveProtocolAuthForFlags(flags, ticketId);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const body = {
@@ -942,7 +1035,8 @@ async function protocolWriteContext(args) {
     value = String(flags.value);
   }
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const body = {
@@ -989,7 +1083,8 @@ async function protocolDeliver(args) {
       ? readTextFile(String(flags['summary-file']), '--summary-file')
       : requireFlag(flags, 'summary', undefined));
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   let artifacts = deliverPayload?.artifacts ?? [];
@@ -1011,14 +1106,10 @@ async function protocolDeliver(args) {
 
   const changeRationales =
     deliverPayload?.changeRationales ?? (await resolveChangeRationales(flags));
-  let snapshot = mergeDeliverSnapshot(
+  const snapshot = mergeDeliverSnapshot(
     await resolveSnapshotContext(flags),
     deliverPayload?.snapshot ?? null
   );
-  const checkpointResult = createLocalDeliveryCheckpoint(flags, snapshot);
-  if (checkpointResult) {
-    snapshot = mergeDeliverSnapshot(snapshot, checkpointResult.snapshot);
-  }
   validateDeliverFileChanges(flags, changeRationales);
 
   const body = {
@@ -1026,9 +1117,6 @@ async function protocolDeliver(args) {
     ticketId,
     summary,
     artifacts,
-    ...(checkpointResult?.checkpoint
-      ? { checkpoint: { ...checkpointResult.checkpoint, summary } }
-      : {}),
     ...(snapshot ? { snapshot } : {}),
     ...(changeRationales.length > 0 ? { changeRationales } : {})
   };
@@ -1055,7 +1143,8 @@ 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 resolveProtocolAuthForFlags(flags, ticketId);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const body = {
@@ -1084,7 +1173,8 @@ async function protocolAttachmentPrepareUpload(args) {
   const objectiveId = requireFlag(flags, 'objective-id', undefined);
   const fileName = requireFlag(flags, 'file-name', undefined);
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const body = {
@@ -1121,7 +1211,8 @@ async function protocolAttachmentFinalizeUpload(args) {
   const storagePath = requireFlag(flags, 'storage-path', undefined);
   const label = requireFlag(flags, 'label', undefined);
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const body = {
@@ -1161,7 +1252,8 @@ async function protocolAttachmentGetDownloadUrl(args) {
     throw new Error('--objective-id is required when using --storage-path');
   }
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const body = {
@@ -1202,7 +1294,8 @@ async function protocolAttachmentUploadFile(args) {
   const fileStats = await stat(filePath);
   const fileBytes = await readFile(filePath);
 
-  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveProtocolAuthForFlags(flags, ticketId);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const metadata = flags['metadata-json']
@@ -1293,7 +1386,8 @@ 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 resolveProtocolAuthForFlags(flags, ticketId);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const body = {
@@ -1328,7 +1422,8 @@ 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 resolveProtocolAuthForFlags(flags, ticketId);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
   const body = { ticketId };
@@ -1421,7 +1516,8 @@ 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 resolveProtocolAuthForFlags(flags, ticketId);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
   const agentIdentifier = resolveProtocolAgentIdentifier(flags);
   const modelIdentifier = resolveProtocolModelIdentifier(flags);
@@ -1664,10 +1760,12 @@ attach:
     --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
+    --skip-checkpoint          Bypass automatic objective-start git checkpoint creation
   Returns:
     Full JSON including session.sessionKey, ticket, history, artifacts, sharedState, and promptContext
   Notes:
     If --external-session-id is omitted, the CLI may auto-detect Codex or Claude session ids
+    Attach creates and records missing local git checkpoints for executing objectives before work starts.
 
 connect:
   Purpose:
@@ -1789,13 +1887,10 @@ deliver:
     --artifacts-file <path|->
     --change-rationales-json <json>
     --change-rationales-file <path|->
-    --checkpoint-backend <auto|jj|git>  Backend for the local delivery checkpoint (default: auto)
-    --skip-checkpoint       Bypass automatic local checkpoint creation
     --skip-file-change-check  Bypass local git vs changeRationales validation
   Notes:
     Use --payload-file - to read the full delivery JSON from stdin without creating a scratch file.
     Do not combine --payload-file with --artifacts-json/--artifacts-file or change-rationale flags.
-    Deliver creates a local checkpoint before the API request when the current workspace is JJ- or Git-managed.
     In a git workspace, deliver validates that changed files are represented by changeRationales unless skipped.
 
 prompt:
@@ -1932,7 +2027,6 @@ Examples:
   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" --checkpoint-backend jj
   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
 `);

package/package.json

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

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

@@ -152,6 +152,7 @@ The `attach` and `load-context` responses already include `attachments` and `obj
 ## Defaults And Notes
 
 - API requires `agentIdentifier` and `connectionMethod` on attach/connect/prompt. The CLI defaults them to `claude-code`/`cli`; the MCP tool defaults to `mcp`. Override with `--agent` / `--method` when calling from a different runtime.
+- Hosted Overlord MCP (`/functions/v1/mcp`) uses the same canonical tool names as any local MCP shim that shells into `ovld protocol` (`attach`, `update`, `deliver`, …). Hosted calls use camelCase JSON keys (`ticketId`, `sessionKey`) matching `POST /api/protocol/*` bodies; the local shim uses snake_case keys mapped to CLI flags (`ticket_id`, `session_key`).
 - `permission-request` is invoked by the Claude Code permission hook installed by the bundle. Agents do not normally call it directly.
 - `record_change_rationales` (MCP) and `ovld protocol record-change-rationales` (CLI) both write to the same `file_changes` table. The dedicated CLI route is `POST /api/protocol/record-change-rationales`.
 - Objective attachment tools follow the `<verb>_<noun>` MCP naming: `list_attachments`, `prepare_attachment_upload`, `finalize_attachment_upload`, `get_attachment_download_url`, `upload_attachment_file`. CLI commands use `attachment-*` and require `--objective-id` for upload/finalize.
@@ -169,4 +170,4 @@ The `attach` and `load-context` responses already include `attachments` and `obj
 - 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.4.5 -->
+<!-- version: 0.4.7 -->

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

@@ -69,7 +69,7 @@ process.stdin.on('data', async chunk => {
         result: {
           protocolVersion: PROTOCOL_VERSION,
           capabilities: { tools: { listChanged: false } },
-          serverInfo: { name: 'overlord-cursor', version: '0.1.0' }
+          serverInfo: { name: 'overlord-cursor', version: '0.1.2' }
         }
       });
       continue;
@@ -81,21 +81,26 @@ process.stdin.on('data', async chunk => {
         result: {
           tools: [
             {
-              name: 'attach_ticket',
+              name: 'attach',
               description: 'Attach to an Overlord ticket.',
               inputSchema: { type: 'object', properties: { ticket_id: { type: 'string' } }, required: ['ticket_id'] }
             },
             {
-              name: 'post_update',
+              name: 'update',
               description: 'Post a progress update.',
               inputSchema: {
                 type: 'object',
-                properties: { session_key: { type: 'string' }, ticket_id: { type: 'string' }, summary: { type: 'string' } },
+                properties: {
+                  session_key: { type: 'string' },
+                  ticket_id: { type: 'string' },
+                  summary: { type: 'string' },
+                  phase: { type: 'string' }
+                },
                 required: ['session_key', 'ticket_id', 'summary']
               }
             },
             {
-              name: 'deliver_ticket',
+              name: 'deliver',
               description: 'Deliver completed work.',
               inputSchema: {
                 type: 'object',
@@ -111,9 +116,9 @@ process.stdin.on('data', async chunk => {
     if (message.method === 'tools/call') {
       const toolName = message.params?.name;
       const args = message.params?.arguments ?? {};
-      if (toolName === 'attach_ticket') {
+      if (toolName === 'attach') {
         send({ jsonrpc: '2.0', id: message.id, result: await runProtocol('attach', { 'ticket-id': args.ticket_id }) });
-      } else if (toolName === 'post_update') {
+      } else if (toolName === 'update') {
         send({
           jsonrpc: '2.0',
           id: message.id,
@@ -121,10 +126,10 @@ process.stdin.on('data', async chunk => {
             'session-key': args.session_key,
             'ticket-id': args.ticket_id,
             summary: args.summary,
-            phase: 'execute'
+            phase: args.phase && String(args.phase).trim() ? String(args.phase).trim() : 'execute'
           })
         });
-      } else if (toolName === 'deliver_ticket') {
+      } else if (toolName === 'deliver') {
         send({
           jsonrpc: '2.0',
           id: message.id,

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

@@ -137,6 +137,7 @@ Objective attachment uploads also expose two-step variants — `attachment-prepa
 ## Defaults And Notes
 
 - The Overlord API requires `agentIdentifier` and `connectionMethod` on attach/connect/prompt, but the CLI defaults them to `cursor`/`cli` (override with `--agent` / `--method`). The MCP tools default to `mcp`.
+- The Cursor local MCP stub exposes `attach`, `update`, and `deliver` only (same names as the hosted Overlord MCP core set).
 - `permission-request` is invoked by the installed permission hook; agents normally do not call it directly.
 - The `record_change_rationales` MCP tool and `ovld protocol record-change-rationales` CLI both write to the same `file_changes` table; pick whichever fits your runtime.
 
@@ -151,4 +152,4 @@ Objective attachment uploads also expose two-step variants — `attachment-prepa
 - If you must run `ovld auth login`, always include `--organization-id <id>` — use the organization ID from the ticket prompt context to select the organization non-interactively and avoid a blocking TTY prompt.
 - Delivery is the concluding step. After delivering, stop unless the user follows up or the ticket is reopened.
 
-<!-- version: 0.4.5 -->
+<!-- version: 0.4.7 -->

package/plugins/overlord/README.md

@@ -22,9 +22,9 @@ personal marketplace entry at `~/.agents/plugins/marketplace.json`.
 
 - Project resolution: `discover_project`
 - Ticket search: `search_tickets` — keyword search + status/filter (direct API call)
-- Ticket session flow: `attach_ticket`, `connect_ticket`, `load_ticket_context`, `spawn_ticket`
-- Progress and review flow: `post_update`, `record_change_rationales`, `ask_blocking_question`, `deliver_ticket`
-- Shared context: `read_shared_context`, `write_shared_context`
+- Ticket session flow: `attach`, `connect`, `load_ticket_context`, `prompt`
+- Progress and review flow: `update`, `record_change_rationales`, `ask`, `deliver`
+- Shared context: `read_context`, `write_context`
 - Objective attachments: `list_attachments`, `prepare_attachment_upload`, `finalize_attachment_upload`, `get_attachment_download_url`, `upload_attachment_file`
 
 The MCP server shells into the installed `ovld` binary so the plugin stays aligned with the shipped CLI behavior instead of depending on this repository checkout.

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

@@ -44,7 +44,7 @@ const tools = [
     subcommand: 'discover-project'
   },
   {
-    name: 'attach_ticket',
+    name: 'attach',
     description: 'Attach an agent session to an existing Overlord ticket and return the working context.',
     inputSchema: {
       type: 'object',
@@ -52,7 +52,11 @@ const tools = [
         ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
         agent: { type: 'string' },
         method: { type: 'string' },
-        external_session_id: { type: ['string', 'null'] }
+        external_session_id: { type: ['string', 'null'] },
+        metadata: {
+          type: 'object',
+          description: 'Optional extra metadata merged into the attach request (same as --metadata-json on the CLI).'
+        }
       },
       required: ['ticket_id']
     },
@@ -60,36 +64,47 @@ const tools = [
       'ticket-id': args.ticket_id,
       agent: args.agent,
       method: args.method,
-      'external-session-id': args.external_session_id
+      'external-session-id': args.external_session_id,
+      ...(args.metadata && typeof args.metadata === 'object' && !Array.isArray(args.metadata)
+        ? { 'metadata-json': args.metadata }
+        : {})
     }),
     subcommand: 'attach'
   },
   {
-    name: 'connect_ticket',
+    name: 'connect',
     description: 'Create a lightweight Overlord session without loading the full ticket context.',
     inputSchema: {
       type: 'object',
       properties: {
         ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
         agent: { type: 'string' },
-        method: { type: 'string' }
+        method: { type: 'string' },
+        metadata: {
+          type: 'object',
+          description: 'Optional extra metadata merged into the connect request (same as --metadata-json on the CLI).'
+        }
       },
       required: ['ticket_id']
     },
     toCliFlags: args => ({
       'ticket-id': args.ticket_id,
       agent: args.agent,
-      method: args.method
+      method: args.method,
+      ...(args.metadata && typeof args.metadata === 'object' && !Array.isArray(args.metadata)
+        ? { 'metadata-json': args.metadata }
+        : {})
     }),
     subcommand: 'connect'
   },
   {
     name: 'load_ticket_context',
-    description: 'Fetch Overlord ticket context without creating a session.',
+    description:
+      'Fetch Overlord ticket context without creating a session (maps to ovld protocol load-context; not the same as read_context).',
     inputSchema: {
       type: 'object',
       properties: {
-        ticket_id: { type: 'string' }
+        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' }
       },
       required: ['ticket_id']
     },
@@ -99,8 +114,8 @@ const tools = [
     subcommand: 'load-context'
   },
   {
-    name: 'prompt_ticket',
-    description: 'Create a ticket and attach to it immediately.',
+    name: 'prompt',
+    description: 'Create a ticket and attach to it immediately (ovld protocol prompt).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -109,6 +124,7 @@ const tools = [
         priority: { type: 'string', enum: ['low', 'medium', 'high', 'urgent'] },
         project_id: { type: 'string' },
         working_directory: { type: 'string' },
+        personal: { type: 'boolean', description: 'Create without assigning a project (private ticket).' },
         acceptance_criteria: { type: 'string' },
         available_tools: { type: 'string' },
         execution_target: { type: 'string', enum: ['agent', 'human'] },
@@ -126,6 +142,7 @@ const tools = [
       priority: args.priority,
       'project-id': args.project_id,
       'working-directory': args.working_directory,
+      personal: args.personal === true ? true : undefined,
       'acceptance-criteria': args.acceptance_criteria,
       'available-tools': args.available_tools,
       'execution-target': args.execution_target,
@@ -138,7 +155,7 @@ const tools = [
     subcommand: 'prompt'
   },
   {
-    name: 'post_update',
+    name: 'update',
     description: 'Post an Overlord progress update or activity event.',
     inputSchema: {
       type: 'object',
@@ -192,7 +209,7 @@ const tools = [
     subcommand: 'record-change-rationales'
   },
   {
-    name: 'ask_blocking_question',
+    name: 'ask',
     description: 'Send a blocking question to the human reviewer or PM.',
     inputSchema: {
       type: 'object',
@@ -215,7 +232,7 @@ const tools = [
     subcommand: 'ask'
   },
   {
-    name: 'read_shared_context',
+    name: 'read_context',
     description: 'Read persistent shared context entries for a ticket.',
     inputSchema: {
       type: 'object',
@@ -236,7 +253,7 @@ const tools = [
     subcommand: 'read-context'
   },
   {
-    name: 'write_shared_context',
+    name: 'write_context',
     description: 'Write a persistent shared context entry for future Overlord sessions.',
     inputSchema: {
       type: 'object',
@@ -259,9 +276,9 @@ const tools = [
     subcommand: 'write-context'
   },
   {
-    name: 'deliver_ticket',
+    name: 'deliver',
     description:
-      'Deliver final work back into Overlord with summary, artifacts, and change rationales. Large payloads are streamed to the CLI through stdin, so this tool does not create delivery scratch files.',
+      'Deliver final work back into Overlord with summary, optional artifacts, and optional change rationales (matches POST /api/protocol/deliver). Large payloads are streamed to the CLI through stdin, so this tool does not create delivery scratch files.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -280,11 +297,6 @@ const tools = [
           description:
             'Optional checkpoint metadata. The local CLI creates this automatically for JJ/Git workspaces during deliver.'
         },
-        checkpoint_backend: {
-          type: 'string',
-          enum: ['auto', 'jj', 'git'],
-          description: 'Backend for automatic local checkpointing when routed through the CLI.'
-        },
         skip_checkpoint: { type: 'boolean' },
         skip_file_change_check: { type: 'boolean' }
       },
@@ -294,7 +306,6 @@ const tools = [
       'session-key': args.session_key,
       'ticket-id': args.ticket_id,
       'payload-file': '-',
-      'checkpoint-backend': args.checkpoint_backend,
       'skip-checkpoint': args.skip_checkpoint,
       'skip-file-change-check': args.skip_file_change_check
     }),
@@ -466,7 +477,7 @@ const searchTicketsTool = {
       },
       limit: {
         type: 'number',
-        description: 'Maximum number of results to return (1–20, default 8).'
+        description: 'Maximum number of results to return (1–50, default 8).'
       }
     }
   },
@@ -479,10 +490,9 @@ const searchTicketsTool = {
   subcommand: 'search-tickets'
 };
 
-const toolMap = new Map([
-  ...tools.map(tool => [tool.name, tool]),
-  [searchTicketsTool.name, searchTicketsTool]
-]);
+const allListedTools = [...tools, searchTicketsTool];
+
+const toolMap = new Map(allListedTools.map(tool => [tool.name, tool]));
 let buffer = Buffer.alloc(0);
 
 function serializeMessage(message) {
@@ -645,10 +655,10 @@ async function handleRequest(message) {
       },
       serverInfo: {
         name: 'overlord',
-        version: '0.1.2'
+        version: '0.1.4'
       },
       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. Tool names match the hosted Overlord MCP server (attach, update, deliver, …). Most operations expect a session key from attach or connect.'
     });
     return;
   }
@@ -660,7 +670,7 @@ async function handleRequest(message) {
 
   if (method === 'tools/list') {
     success(id, {
-      tools: [...tools, searchTicketsTool].map(tool => ({
+      tools: allListedTools.map(tool => ({
         name: tool.name,
         description: tool.description,
         inputSchema: tool.inputSchema

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

@@ -138,7 +138,8 @@ The `attach` and `load-context` responses already include `attachments` and `obj
 
 ## Defaults And Notes
 
-- API requires `agentIdentifier` and `connectionMethod` on attach/connect/prompt. The CLI defaults them to `codex`/`cli`; the MCP tool defaults to `mcp`. Override with `--agent` / `--method` when calling from a different runtime.
+- API requires `agentIdentifier` and `connectionMethod` on attach/connect/prompt. The CLI defaults them to `codex`/`cli`; the hosted MCP defaults to `mcp`. Override with `--agent` / `--method` when calling from a different runtime.
+- Hosted MCP and the local `overlord-mcp.mjs` shim use the same **tool names** (\`attach\`, \`update\`, \`deliver\`, …). The shim uses **snake_case** JSON keys (\`ticket_id\`, \`session_key\`) that map to CLI flags; hosted MCP uses **camelCase** (\`ticketId\`, \`sessionKey\`) matching REST bodies.
 - `permission-request` is invoked by the local Codex plugin's permission rules; agents do not normally call it directly.
 - `record_change_rationales` (MCP) and `ovld protocol record-change-rationales` (CLI) both write to the `file_changes` table; the dedicated route is `POST /api/protocol/record-change-rationales`.
 - Objective attachment MCP tools use `<verb>_<noun>` names — `list_attachments`, `prepare_attachment_upload`, `finalize_attachment_upload`, `get_attachment_download_url`, `upload_attachment_file`. CLI commands use `attachment-*` and require `--objective-id` for upload/finalize.
@@ -154,4 +155,4 @@ The `attach` and `load-context` responses already include `attachments` and `obj
 - If a protocol or MCP call fails with auth/session errors, run `ovld auth repair` yourself before asking the user to log in again or proceed without Overlord updates.
 - If you must run `ovld auth login`, always include `--organization-id <id>` — use the organization ID from the ticket prompt context to select the organization non-interactively and avoid a blocking TTY prompt.
 
-<!-- version: 0.4.5 -->
+<!-- version: 0.4.7 -->