overlord-cli 0.2605111118.0 → 0.2605120852.0

package/README.md

@@ -119,7 +119,7 @@ Agents can find docs here: https://www.ovld.ai/docs/for-agents
 - `permission-request` - notify Overlord that the agent is requesting tool permission
 - `read-context` - read shared persistent context for this ticket
 - `write-context` - write shared persistent context for future sessions
-- `deliver` - finish work, send artifacts, and move the ticket to review
+- `deliver` - create a local JJ/Git checkpoint when available, send artifacts/rationales, and move the ticket to review
 - `attachment-prepare-upload` - get a signed upload URL for an objective attachment
 - `attachment-finalize-upload` - finalize an uploaded objective attachment row after storage upload
 - `attachment-download-url` - get a signed download URL for an existing objective attachment

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
@@ -359,6 +358,238 @@ async function resolveSnapshotContext(flags) {
   return null;
 }
 
+/**
+ * Shallow-merge snapshot metadata: launch/env context first, then deliver payload
+ * (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}
+ */
+function mergeDeliverSnapshot(fromEnvOrFlags, fromPayload) {
+  const base =
+    fromEnvOrFlags && typeof fromEnvOrFlags === 'object' && !Array.isArray(fromEnvOrFlags)
+      ? { ...fromEnvOrFlags }
+      : {};
+  const overlay =
+    fromPayload && typeof fromPayload === 'object' && !Array.isArray(fromPayload)
+      ? { ...fromPayload }
+      : {};
+  const merged = { ...base, ...overlay };
+  return Object.keys(merged).length > 0 ? merged : null;
+}
+
+function runLocalCommand(command, args, options = {}) {
+  return execFileSync(command, args, {
+    cwd: options.cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: options.timeoutMs ?? 60000,
+    maxBuffer: 10 * 1024 * 1024
+  });
+}
+
+function resolveGitRepoRoot(workspacePath) {
+  try {
+    return runLocalCommand('git', ['-C', workspacePath, 'rev-parse', '--show-toplevel'], {
+      cwd: workspacePath,
+      timeoutMs: 15000
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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 workspacePath = path.resolve(
+    String(snapshot?.workspacePath ?? process.env.OVERLORD_WORKSPACE_PATH ?? process.cwd())
+  );
+  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 {
+      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 || null, kind },
+        snapshot: {
+          gitCommitId: gitCommitId || null,
+          headSha: gitCommitId || null,
+          diffStat: diffStat || null
+        }
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  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 {
+    existingSha = runLocalCommand('git', ['-C', repoRoot, 'rev-parse', '--verify', ref], {
+      cwd: repoRoot
+    }).trim();
+  } 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 },
+      snapshot: {
+        gitCommitId: commit,
+        gitRefName: ref,
+        headSha,
+        objectiveId: String(resolvedObjectiveId),
+        diffStat: diffStat || null
+      }
+    };
+  } 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 */
+    }
+  }
+}
+
+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;
 
@@ -534,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);
@@ -557,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));
 
@@ -580,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);
@@ -637,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);
 
@@ -679,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 = {
@@ -715,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(
@@ -740,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 = {
@@ -784,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 = {
@@ -831,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 ?? [];
@@ -853,7 +1106,10 @@ async function protocolDeliver(args) {
 
   const changeRationales =
     deliverPayload?.changeRationales ?? (await resolveChangeRationales(flags));
-  const snapshot = (await resolveSnapshotContext(flags)) ?? deliverPayload?.snapshot ?? null;
+  const snapshot = mergeDeliverSnapshot(
+    await resolveSnapshotContext(flags),
+    deliverPayload?.snapshot ?? null
+  );
   validateDeliverFileChanges(flags, changeRationales);
 
   const body = {
@@ -887,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 = {
@@ -916,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 = {
@@ -953,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 = {
@@ -993,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 = {
@@ -1034,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']
@@ -1125,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 = {
@@ -1160,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 };
@@ -1253,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);
@@ -1496,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:

package/package.json

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

@@ -65,7 +65,7 @@ ovld protocol deliver --session-key <sessionKey> \
   --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
 ```
 
-For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
+`ovld protocol deliver` automatically creates a local checkpoint before the API request when the workspace is JJ- or Git-managed; use `--skip-checkpoint` only when intentionally bypassing local provenance. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
 
 ## Mode 2: Asked From Chat To Use Overlord
 
@@ -73,14 +73,15 @@ Use this mode when the conversation starts normally and the user asks Claude to
 
 1. If the user wants to create tickets (and does not ask to start execution), run `ovld protocol create --agent claude-code --objective "..."`.
    - When `--session-key` and `--ticket-id` are provided, it creates a follow-up draft.
-   - When session flags are omitted, it resolves the project by matching current working directory (or `--working-directory`) to the caller's configured Overlord `project_user.local_working_directory`, then creates a standalone draft.
-2. Default to `create` for new tickets. Only use `/overlord:spawn` or `ovld protocol spawn --agent claude-code --objective "..."` when the user explicitly asks to create and execute immediately.
-   `spawn` creates the ticket in `execute` status and attaches immediately.
+   - When session flags are omitted, it resolves the project by matching current working directory (or `--working-directory`) to Overlord `local_working_directory`, then creates a standalone draft.
+2. Default to `create` for new tickets. Only use `/overlord:prompt` or `ovld protocol prompt --agent claude-code --objective "..."` when the user explicitly asks to create and execute immediately.
+   `prompt` creates the ticket in `execute` status and attaches immediately.
 3. If the user already has a ticket ID and only wants to inspect it, use `/overlord:load` or run `ovld protocol load-context --ticket-id <ticket_id>`.
 4. If the user wants to route the current session onto an existing ticket by ID, use `/overlord:connect` or run `ovld protocol connect --ticket-id <ticket_id>`.
-5. If the user wants to find a ticket but does not know the ID, use `ovld attach` for interactive ticket search and agent launch, or ask the user for the ticket ID if staying strictly inside chat is the better fit.
-6. If you need other lifecycle commands or flags, run `ovld protocol help` and use the real subcommand list instead of guessing.
-7. Once you attach to a ticket, switch back to Mode 1 and follow the full ticket lifecycle.
+5. If the user wants to establish a persistent session with a ticket by ID, use `/overlord:attach` or run `ovld protocol attach --ticket-id <ticket_id>`.
+6. If the user wants to find a ticket but does not know the ID, use `ovld attach` for interactive ticket search and agent launch, or run `ovld protocol search-tickets --query "..." --status next-up,execute` and ask the user to confirm.
+7. If you need other lifecycle commands or flags, run `ovld protocol help` and use the real subcommand list instead of guessing.
+8. Once you attach to a ticket, switch back to Mode 1 and follow the full ticket lifecycle.
 
 ## Change Rationales
 
@@ -108,7 +109,7 @@ Record only meaningful behavioral changes. Skip formatting-only noise.
 
 When creating tickets from within a repository:
 - Prefer `create` by default for draft ticket creation.
-- Use `spawn` only when the user explicitly asks to start execution immediately.
+- Use `prompt` only when the user explicitly asks to start execution immediately.
 - Both commands can resolve the project from the current working directory; use `--working-directory` to override.
 
 ```bash
@@ -116,7 +117,7 @@ ovld protocol create --agent claude-code --objective "Capture follow-up work fro
 ```
 
 ```bash
-ovld protocol spawn --agent claude-code --objective "Implement feature X" --priority medium
+ovld protocol prompt --agent claude-code --objective "Implement feature X" --priority medium
 ```
 
 To inspect project resolution explicitly:
@@ -148,6 +149,15 @@ ovld protocol attachment-download-url --session-key <sessionKey> --ticket-id $TI
 
 The `attach` and `load-context` responses already include `attachments` and `objectives` arrays — use those for `<attachment-id>` and `<objective-id>` values. Run `attachment-list` mid-session if new files have been uploaded since attach.
 
+## 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.
+- "Artifacts" in `deliver` are the structured records an agent submits at delivery time (next_steps, test_results, migration, decision, note, url) — not user-uploaded files. Files attached by users live on objectives via the attachment tools above.
+
 ## Rules
 
 - Always attach first and always deliver last once you are on a ticket.
@@ -155,10 +165,9 @@ The `attach` and `load-context` responses already include `attachments` and `obj
 - Do not invent protocol subcommands. Use `ovld protocol help` when unsure.
 - The `summary` in deliver is what the PM reads first, so write it as a narrative, not a command list.
 - Use `write-context` for facts a future agent session should know.
-- If `ovld` reports `OVERLORD_URL` is unreachable, request permission escalation or network access before retrying.
 - 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.
 - Do not add or commit changes unless the user explicitly asks you to commit.
 - Delivery is the concluding step. After delivering, stop unless the user follows up or the ticket is reopened.
 
-<!-- version: 0.2.6 -->
+<!-- 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

@@ -17,17 +17,99 @@ Use this skill whenever Cursor needs to work with Overlord, whether the session
 6. If blocked, call `ovld protocol ask` and stop.
 7. Deliver last with `ovld protocol deliver`, including `changeRationales` for each meaningful behavioral file change.
 
+### Mode 1 Reference
+
+Attach:
+
+```bash
+ovld protocol attach --ticket-id $TICKET_ID
+```
+
+Update:
+
+```bash
+ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID --summary "What you did and why." --phase execute
+```
+
+Supported `--phase` values:
+- `draft`
+- `execute`
+- `review`
+- `deliver`
+- `complete`
+- `blocked`
+- `cancelled`
+
+Event types:
+- `update` for standard progress updates
+- `user_follow_up` for human follow-up messages after the initial ticket
+- `alert` for warnings or non-blocking issues
+
+Ask when blocked:
+
+```bash
+ovld protocol ask --session-key <sessionKey> --ticket-id $TICKET_ID --question "Specific question for the PM."
+```
+
+Deliver:
+
+```bash
+ovld protocol deliver --session-key <sessionKey> \
+  --ticket-id $TICKET_ID \
+  --summary "Narrative: what you did, next steps." \
+  --artifacts-json '[{"type":"next_steps","label":"Next steps","content":"..."}]' \
+  --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
+```
+
+`ovld protocol deliver` automatically creates a local checkpoint before the API request when the workspace is JJ- or Git-managed; use `--skip-checkpoint` only when intentionally bypassing local provenance. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed.
+
 ## Mode 2: Asked From Chat To Use Overlord
 
 1. If the user wants to create tickets (and does not ask to start execution), use `/create` or run `ovld protocol create --agent cursor --objective "..."`.
-2. Default to `create` for new tickets. Only use `/spawn` or `ovld protocol spawn --agent cursor --objective "..."` when the user explicitly asks to create and execute immediately.
+   - When `--session-key` and `--ticket-id` are provided, it creates a follow-up draft.
+   - When session flags are omitted, it resolves the project by matching current working directory (or `--working-directory`) to Overlord `local_working_directory`, then creates a standalone draft.
+2. Default to `create` for new tickets. Only use `/prompt` or `ovld protocol prompt --agent cursor --objective "..."` when the user explicitly asks to create and execute immediately.
 3. If the user already has a ticket ID and only wants to inspect it, use `/load` or run `ovld protocol load-context --ticket-id <ticket_id>`.
 4. If the user wants to route the current session onto an existing ticket by ID, use `/connect` or run `ovld protocol connect --ticket-id <ticket_id>`.
-5. If the user wants to search for tickets by keyword or status, use the `search_tickets` MCP tool.
-6. If you need other lifecycle commands or flags, run `ovld protocol help` and use the real subcommand list instead of guessing.
-7. Once you attach to a ticket, switch back to Mode 1 and follow the full ticket lifecycle.
+5. If the user wants to establish a persistent session with a ticket by ID, use `/attach` or run `ovld protocol attach --ticket-id <ticket_id>`.
+6. If the user wants to find a ticket by keyword/status/project/creator/date, run `ovld protocol search-tickets --query "..." --status next-up,execute`.
+7. If you need other lifecycle commands or flags, run `ovld protocol help` and use the real subcommand list instead of guessing.
+8. Once you attach to a ticket, switch back to Mode 1 and follow the full ticket lifecycle.
+
+## Change Rationales
+
+Always include `changeRationales` when delivering. Optionally include them on updates during long-running work.
+
+Before delivering, make sure every meaningful git-tracked file change is represented in `changeRationales`; do not send `file_changes` as an artifact.
 
-## Choosing `--execution-target` When Creating Tickets
+```bash
+ovld protocol record-change-rationales --session-key <sessionKey> --ticket-id $TICKET_ID \
+  --summary "Recorded rationale details for the latest code changes." --phase execute \
+  --change-rationales-json '[{"label":"Add backoff","file_path":"lib/api.ts","summary":"Added retry.","why":"Transient failures.","impact":"Retries 3x.","hunks":[{"header":"@@ -22,4 +22,18 @@"}]}]'
+```
+
+```bash
+ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID \
+  --summary "Added retry logic." --phase execute \
+  --change-rationales-json '[{"label":"Add backoff","file_path":"lib/api.ts","summary":"Added retry.","why":"Transient failures.","impact":"Retries 3x.","hunks":[{"header":"@@ -22,4 +22,18 @@"}]}]'
+```
+
+Record only meaningful behavioral changes. Skip formatting-only noise.
+
+## Project Discovery And Ticket Creation
+
+When creating tickets from within a repository:
+- Prefer `create` by default for draft ticket creation.
+- Use `prompt` only when the user explicitly asks to start execution immediately.
+- Both commands resolve the project from the current working directory; use `--working-directory` to override or `--project-id` to be explicit.
+
+```bash
+ovld protocol create --agent cursor --objective "Capture follow-up work from this repository"
+ovld protocol prompt --agent cursor --objective "Implement feature X" --priority medium
+ovld protocol discover-project
+```
+
+### Choosing `--execution-target`
 
 Pass `--execution-target agent` or `--execution-target human` (default: `human`) when creating tickets.
 
@@ -36,14 +118,38 @@ Pass `--execution-target agent` or `--execution-target human` (default: `human`)
 
 When in doubt, ask yourself: *can this be done entirely inside a terminal or browser by an AI without human intervention?* If yes → `agent`. If it requires a human to log in, decide, or act in the real world → `human`.
 
+## Context And Artifacts
+
+```bash
+ovld protocol read-context --session-key <sessionKey> --ticket-id $TICKET_ID
+ovld protocol write-context --session-key <sessionKey> --ticket-id $TICKET_ID --key "key" --value '"json-value"'
+ovld protocol attachment-list --session-key <sessionKey> --ticket-id $TICKET_ID
+ovld protocol attachment-upload-file --session-key <sessionKey> --ticket-id $TICKET_ID --objective-id <objective-id> --file ./spec.pdf --content-type application/pdf
+ovld protocol attachment-download-url --session-key <sessionKey> --ticket-id $TICKET_ID --attachment-id <attachment-id>
+```
+
+The `attach` and `load-context` responses already include `attachments` and `objectives` arrays — use those for `<attachment-id>` and `<objective-id>` values. Run `attachment-list` mid-session if new files have been uploaded since attach.
+
+Objective attachment uploads also expose two-step variants — `attachment-prepare-upload` and `attachment-finalize-upload` — for callers that need a signed URL directly. Prefer `attachment-upload-file` for one-shot uploads.
+
+"Artifacts" in `deliver` are the structured records an agent submits at delivery time (next_steps, test_results, migration, decision, note, url) — not user-uploaded files.
+
+## 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.
+
 ## Rules
 
 - Always attach first and always deliver last once you are on a ticket.
 - Use `ovld protocol` commands, the plugin commands, and the MCP tool instead of ad hoc scripts.
 - Do not invent protocol subcommands. Use `ovld protocol help` when unsure.
-- If `ovld` reports `OVERLORD_URL` is unreachable, request permission escalation or network access before retrying.
-- 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.
 - Include at least one progress update before delivering.
-- When creating follow-up tickets, always set `--execution-target` explicitly using the `agent`/`human` rule above.
+- The `summary` in deliver is what the PM reads first, so write it as a narrative, not a command list.
+- 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.
+- Delivery is the concluding step. After delivering, stop unless the user follows up or the ticket is reopened.
 
-<!-- version: 0.2.4 -->
+<!-- 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,56 +44,67 @@ 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',
       properties: {
-        ticket_id: { type: 'string', description: 'Target ticket ID' },
+        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
         agent: { type: 'string' },
-        model: { type: 'string' },
         method: { type: 'string' },
         external_session_id: { type: ['string', 'null'] },
-        metadata: { type: 'object' }
+        metadata: {
+          type: 'object',
+          description: 'Optional extra metadata merged into the attach request (same as --metadata-json on the CLI).'
+        }
       },
       required: ['ticket_id']
     },
     toCliFlags: args => ({
       'ticket-id': args.ticket_id,
       agent: args.agent,
-      model: args.model,
       method: args.method,
       'external-session-id': args.external_session_id,
-      'metadata-json': args.metadata
+      ...(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' },
+        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']
     },
@@ -103,8 +114,8 @@ const tools = [
     subcommand: 'load-context'
   },
   {
-    name: 'spawn_ticket',
-    description: 'Create a follow-up ticket and attach to it immediately.',
+    name: 'prompt',
+    description: 'Create a ticket and attach to it immediately (ovld protocol prompt).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -113,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'] },
@@ -120,8 +132,6 @@ const tools = [
         parent_session_key: { type: 'string' },
         parent_ticket_id: { type: 'string' },
         agent: { type: 'string' },
-        model: { type: 'string' },
-        metadata: { type: 'object' },
         method: { type: 'string' }
       },
       required: ['objective']
@@ -132,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,
@@ -139,20 +150,18 @@ const tools = [
       'parent-session-key': args.parent_session_key,
       'parent-ticket-id': args.parent_ticket_id,
       agent: args.agent,
-      model: args.model,
-      'metadata-json': args.metadata,
       method: args.method
     }),
-    subcommand: 'spawn'
+    subcommand: 'prompt'
   },
   {
-    name: 'post_update',
+    name: 'update',
     description: 'Post an Overlord progress update or activity event.',
     inputSchema: {
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string' },
+        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
         summary: { type: 'string' },
         phase: { type: 'string', enum: ['draft', 'execute', 'review', 'deliver', 'complete', 'blocked', 'cancelled'] },
         event_type: { type: 'string', enum: ['update', 'user_follow_up', 'alert'] },
@@ -183,7 +192,7 @@ const tools = [
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string' },
+        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
         summary: { type: 'string' },
         phase: { type: 'string', enum: ['draft', 'execute', 'review', 'deliver', 'complete', 'blocked', 'cancelled'] },
         change_rationales: { type: 'array' }
@@ -200,13 +209,13 @@ 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',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string' },
+        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
         question: { type: 'string' },
         phase: { type: 'string', enum: ['draft', 'execute', 'review', 'deliver', 'complete', 'blocked', 'cancelled'] },
         payload: { type: 'object' }
@@ -223,13 +232,13 @@ const tools = [
     subcommand: 'ask'
   },
   {
-    name: 'read_shared_context',
+    name: 'read_context',
     description: 'Read persistent shared context entries for a ticket.',
     inputSchema: {
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string' },
+        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
         query: { type: 'string' },
         limit: { type: 'number' }
       },
@@ -244,13 +253,13 @@ 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',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string' },
+        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
         key: { type: 'string' },
         value: {},
         tags: { type: 'array', items: { type: 'string' } }
@@ -267,17 +276,28 @@ 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: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string' },
+        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
         summary: { type: 'string' },
         artifacts: { type: 'array' },
         change_rationales: { type: 'array' },
+        snapshot: {
+          type: 'object',
+          description:
+            'Optional snapshot metadata (jj/git-worktree, workspace, jj ids). Merged with OVERLORD_SNAPSHOT_JSON when both are set.'
+        },
+        checkpoint: {
+          type: 'object',
+          description:
+            'Optional checkpoint metadata. The local CLI creates this automatically for JJ/Git workspaces during deliver.'
+        },
+        skip_checkpoint: { type: 'boolean' },
         skip_file_change_check: { type: 'boolean' }
       },
       required: ['session_key', 'ticket_id', 'summary']
@@ -286,13 +306,17 @@ const tools = [
       'session-key': args.session_key,
       'ticket-id': args.ticket_id,
       'payload-file': '-',
+      'skip-checkpoint': args.skip_checkpoint,
       'skip-file-change-check': args.skip_file_change_check
     }),
-    toCliStdin: args => JSON.stringify({
-      summary: args.summary,
-      ...(Array.isArray(args.artifacts) ? { artifacts: args.artifacts } : {}),
-      ...(Array.isArray(args.change_rationales) ? { changeRationales: args.change_rationales } : {})
-    }),
+    toCliStdin: args =>
+      JSON.stringify({
+        summary: args.summary,
+        ...(Array.isArray(args.artifacts) ? { artifacts: args.artifacts } : {}),
+        ...(Array.isArray(args.change_rationales) ? { changeRationales: args.change_rationales } : {}),
+        ...(args.snapshot && typeof args.snapshot === 'object' ? { snapshot: args.snapshot } : {}),
+        ...(args.checkpoint && typeof args.checkpoint === 'object' ? { checkpoint: args.checkpoint } : {})
+      }),
     subcommand: 'deliver'
   },
   {
@@ -303,7 +327,7 @@ const tools = [
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string' },
+        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
         objective_id: { type: 'string' }
       },
       required: ['session_key', 'ticket_id']
@@ -322,7 +346,7 @@ const tools = [
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string' },
+        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
         objective_id: { type: 'string' },
         file_name: { type: 'string' },
         label: { type: 'string' },
@@ -351,7 +375,7 @@ const tools = [
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string' },
+        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
         objective_id: { type: 'string' },
         storage_path: { type: 'string' },
         label: { type: 'string' },
@@ -380,7 +404,7 @@ const tools = [
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string' },
+        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
         objective_id: { type: 'string' },
         attachment_id: { type: 'string' },
         storage_path: { type: 'string' },
@@ -405,7 +429,7 @@ const tools = [
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string' },
+        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
         objective_id: { type: 'string' },
         file: { type: 'string' },
         file_name: { type: 'string' },
@@ -453,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).'
       }
     }
   },
@@ -466,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) {
@@ -632,10 +655,10 @@ async function handleRequest(message) {
       },
       serverInfo: {
         name: 'overlord',
-        version: '0.2.1'
+        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. If the CLI reports that OVERLORD_URL is unreachable, request permission escalation or network access before retrying.'
+        '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;
   }
@@ -647,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

@@ -63,18 +63,45 @@ ovld protocol deliver --session-key <sessionKey> \
   --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
 ```
 
-For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
+`ovld protocol deliver` automatically creates a local checkpoint before the API request when the workspace is JJ- or Git-managed; use `--skip-checkpoint` only when intentionally bypassing local provenance. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
 
 ## Mode 2: Asked From Chat To Use Overlord
 
 1. If the user wants to create tickets (and does not ask to start execution), run `ovld protocol create --agent codex --objective "..."`.
-2. Default to `create` for new tickets. Only use `ovld protocol spawn --agent codex --objective "..."` when the user explicitly asks to create and execute immediately.
+   - When `--session-key` and `--ticket-id` are provided, it creates a follow-up draft.
+   - When session flags are omitted, it resolves the project by matching current working directory (or `--working-directory`) to Overlord `local_working_directory`, then creates a standalone draft.
+2. Default to `create` for new tickets. Only use `ovld protocol prompt --agent codex --objective "..."` when the user explicitly asks to create and execute immediately.
+   `prompt` creates the ticket in `execute` status and attaches immediately.
 3. If the user wants to inspect an existing ticket without starting work, use `ovld protocol load-context --ticket-id <ticket_id>`.
-4. If the user wants to work an existing ticket, attach with `ovld protocol attach --ticket-id <ticket_id>` and then switch to Mode 1.
-5. If the user wants to find existing tickets by keyword or workflow state, use the `search_tickets` tool.
-6. If you need to understand project routing before spawning, use `ovld protocol discover-project`.
+4. If the user wants to work an existing ticket, attach with `ovld protocol attach --ticket-id <ticket_id>` and then switch to Mode 1. Use `ovld protocol connect --ticket-id <ticket_id>` instead when you only need a session key without the full ticket payload.
+5. If the user wants to find existing tickets by keyword, status, project, creator, or update window, run `ovld protocol search-tickets --query "..." --status next-up,execute --limit 10`. The MCP `search_tickets` tool exposes the same filters.
+6. If you need to understand project routing before prompting, use `ovld protocol discover-project`.
 7. If you need other lifecycle commands or flags, run `ovld protocol help` and use the real subcommand list instead of guessing.
 
+## Project Discovery And Ticket Creation
+
+When creating tickets from within a repository:
+- Prefer `create` by default for draft ticket creation.
+- Use `prompt` only when the user explicitly asks to start execution immediately.
+- Both commands can resolve the project from the current working directory; use `--working-directory` to override.
+
+```bash
+ovld protocol create --agent codex --objective "Capture follow-up work from this repository"
+```
+
+```bash
+ovld protocol prompt --agent codex --objective "Implement feature X" --priority medium
+```
+
+### Choosing `--execution-target`
+
+Pass `--execution-target agent` or `--execution-target human` (default: `human`) when creating tickets.
+
+- **`agent`** — any task an AI agent can complete in a computer environment: coding, internet research, document editing, data analysis, automated testing, etc.
+- **`human`** — any task requiring human presence or judgment: setting credentials or tokens in a third-party UI (e.g. Vercel, AWS), sending physical mail, making a product or business decision, physical-world actions.
+
+When in doubt, ask yourself: *can this be done entirely inside a terminal or browser by an AI without human intervention?* If yes → `agent`. If it requires a human to log in, decide, or act in the real world → `human`.
+
 ## Change Rationales
 
 Always include `changeRationales` when delivering. Optionally include them on updates during long-running work.
@@ -109,38 +136,23 @@ ovld protocol attachment-download-url --session-key <sessionKey> --ticket-id $TI
 
 The `attach` and `load-context` responses already include `attachments` and `objectives` arrays — use those for `<attachment-id>` and `<objective-id>` values. Run `attachment-list` mid-session if new files have been uploaded since attach.
 
-## Project Discovery And Ticket Creation
-
-When creating tickets from within a repository:
-- Prefer `create` by default for draft ticket creation.
-- Use `spawn` only when the user explicitly asks to start execution immediately.
-- Both commands can resolve the project from the current working directory; use `--working-directory` to override.
+## Defaults And Notes
 
-```bash
-ovld protocol create --agent codex --objective "Capture follow-up work from this repository"
-```
-
-```bash
-ovld protocol spawn --agent codex --objective "Implement feature X" --priority medium
-```
-
-### Choosing `--execution-target`
-
-Pass `--execution-target agent` or `--execution-target human` (default: `human`) when creating tickets.
-
-- **`agent`** — any task an AI agent can complete in a computer environment: coding, internet research, document editing, data analysis, automated testing, etc.
-- **`human`** — any task requiring human presence or judgment: setting credentials or tokens in a third-party UI (e.g. Vercel, AWS), sending physical mail, making a product or business decision, physical-world actions.
-
-When in doubt, ask yourself: *can this be done entirely inside a terminal or browser by an AI without human intervention?* If yes → `agent`. If it requires a human to log in, decide, or act in the real world → `human`.
+- 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.
+- "Artifacts" in `deliver` are the structured records an agent submits at delivery time (next_steps, test_results, migration, decision, note, url) — not user-uploaded files.
 
 ## Rules
 
 - The authoritative lifecycle is the `ovld protocol` CLI once you are on a ticket.
 - Always attach first and always deliver last once you are working a ticket.
-- Prefer the installed `ovld` CLI and the plugin's MCP tools instead of ad hoc repo scripts.
+- Prefer the installed `ovld protocol` CLI and the plugin's MCP tools instead of ad hoc repo scripts.
 - Do not create or rely on a local Codex `AGENTS.md` bundle for Overlord.
-- If `ovld` reports `OVERLORD_URL` is unreachable, request permission escalation or network access before retrying.
 - When the ticket was launched by Overlord, the ticket prompt remains authoritative for the specific task objective and ticket-level constraints.
 - 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.2.5 -->
+<!-- version: 0.4.7 -->