overlord-cli 0.2605111118.0 → 0.2605111338.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

@@ -359,6 +359,164 @@ 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 jj ids without losing workspace
+ * paths 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 commandSucceeds(command, args, cwd) {
+  try {
+    runLocalCommand(command, args, { cwd, timeoutMs: 15000 });
+    return true;
+  } 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;
+}
+
+function createLocalDeliveryCheckpoint(flags, snapshot) {
+  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') {
+    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);
+      return {
+        checkpoint: {
+          diffStat: diffStat.trim() || null,
+          kind: 'delivery'
+        },
+        snapshot: {
+          backend: 'jj',
+          workspacePath,
+          workspaceName: snapshot?.workspaceName ?? path.basename(workspacePath),
+          jjChangeId,
+          jjCommitId,
+          jjOperationId: operation.trim() || null,
+          diffStat: diffStat.trim() || 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.`
+      );
+    }
+  }
+
+  if (preference === 'jj') {
+    throw new Error(`JJ checkpoint requested, but ${workspacePath} is not a JJ repository.`);
+  }
+
+  try {
+    const gitCommitId = runLocalCommand('git', ['-C', workspacePath, 'rev-parse', 'HEAD'], {
+      cwd: workspacePath
+    }).trim();
+    const diffStat = runLocalCommand('git', ['-C', workspacePath, 'diff', '--stat', 'HEAD'], {
+      cwd: workspacePath
+    }).trim();
+    return {
+      checkpoint: {
+        diffStat: diffStat || null,
+        kind: 'delivery'
+      },
+      snapshot: {
+        backend: 'git',
+        workspacePath,
+        workspaceName: snapshot?.workspaceName ?? path.basename(workspacePath),
+        gitCommitId: gitCommitId || null,
+        diffStat: diffStat || null
+      }
+    };
+  } catch {
+    if (preference === 'git') {
+      throw new Error(`Git checkpoint requested, but metadata could not be read in ${workspacePath}.`);
+    }
+    return null;
+  }
+}
+
 function normalizeRepoRelativeFilePath(filePath, repoRoot) {
   if (typeof filePath !== 'string') return null;
 
@@ -853,7 +1011,14 @@ async function protocolDeliver(args) {
 
   const changeRationales =
     deliverPayload?.changeRationales ?? (await resolveChangeRationales(flags));
-  const snapshot = (await resolveSnapshotContext(flags)) ?? deliverPayload?.snapshot ?? null;
+  let 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 = {
@@ -861,6 +1026,9 @@ async function protocolDeliver(args) {
     ticketId,
     summary,
     artifacts,
+    ...(checkpointResult?.checkpoint
+      ? { checkpoint: { ...checkpointResult.checkpoint, summary } }
+      : {}),
     ...(snapshot ? { snapshot } : {}),
     ...(changeRationales.length > 0 ? { changeRationales } : {})
   };
@@ -1621,10 +1789,13 @@ 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:
@@ -1761,6 +1932,7 @@ 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.2605111118.0",
+  "version": "0.2605111338.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,14 @@ 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.
+- `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 +164,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.5 -->

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,37 @@ 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`.
+- `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.5 -->

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

@@ -49,22 +49,18 @@ const tools = [
     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' }
+        external_session_id: { type: ['string', 'null'] }
       },
       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
+      'external-session-id': args.external_session_id
     }),
     subcommand: 'attach'
   },
@@ -74,7 +70,7 @@ const tools = [
     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' }
       },
@@ -103,8 +99,8 @@ const tools = [
     subcommand: 'load-context'
   },
   {
-    name: 'spawn_ticket',
-    description: 'Create a follow-up ticket and attach to it immediately.',
+    name: 'prompt_ticket',
+    description: 'Create a ticket and attach to it immediately.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -120,8 +116,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']
@@ -139,11 +133,9 @@ 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',
@@ -152,7 +144,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'] },
         event_type: { type: 'string', enum: ['update', 'user_follow_up', 'alert'] },
@@ -183,7 +175,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' }
@@ -206,7 +198,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.' },
         question: { type: 'string' },
         phase: { type: 'string', enum: ['draft', 'execute', 'review', 'deliver', 'complete', 'blocked', 'cancelled'] },
         payload: { type: 'object' }
@@ -229,7 +221,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.' },
         query: { type: 'string' },
         limit: { type: 'number' }
       },
@@ -250,7 +242,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.' },
         key: { type: 'string' },
         value: {},
         tags: { type: 'array', items: { type: 'string' } }
@@ -274,10 +266,26 @@ 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' },
         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.'
+        },
+        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' }
       },
       required: ['session_key', 'ticket_id', 'summary']
@@ -286,13 +294,18 @@ 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
     }),
-    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 +316,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 +335,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 +364,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 +393,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 +418,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' },
@@ -632,10 +645,10 @@ async function handleRequest(message) {
       },
       serverInfo: {
         name: 'overlord',
-        version: '0.2.1'
+        version: '0.1.2'
       },
       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. Most operations expect a session key from attach or connect.'
     });
     return;
   }

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,22 @@ 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 MCP tool defaults to `mcp`. Override with `--agent` / `--method` when calling from a different runtime.
+- `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.5 -->