overlord-cli 0.2605151257.0 → 0.2605160931.0

package/README.md

@@ -111,9 +111,10 @@ Agents can find docs here: https://www.ovld.ai/docs/for-agents
 
 - `auth-status` - return machine-readable auth status for agent runtimes
 - `discover-project` - resolve a project from the current (or given) working directory
-- `attach` - start a ticket session and return full working context
+- `attach` - start a ticket session, create a local git checkpoint per executing objective, and return full working context
 - `connect` - start a lightweight session without full context
 - `load-context` - read ticket context without creating a session
+- `revert` - restore the local working tree to an objective checkpoint after fetching its checkpoint row
 - `search-tickets` - find tickets by keyword, status, project, creator, or update date
 - `create` - create a draft ticket without attaching (standalone or follow-up)
 - `prompt` - create a ticket and attach to it immediately (`spawn` is a backward-compatible alias)
@@ -125,11 +126,15 @@ Agents can find docs here: https://www.ovld.ai/docs/for-agents
 - `hook-event` - record lifecycle hook events such as `UserPromptSubmit` / Cursor `beforeSubmitPrompt` without a session key
 - `read-context` - read shared persistent context for this ticket
 - `write-context` - write shared persistent context for future sessions
-- `deliver` - create a local JJ/Git checkpoint when available, send artifacts/rationales, and move the ticket to review
+- `deliver` - 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
 - `attachment-upload-file` - prepare, upload, and finalize a local objective attachment in one command
+- `get-device` / `update-device` - register the caller machine (per organization + user + fingerprint) and rename its label
+- `list-project-resources` / `add-project-resource` / `update-project-resource` - manage filesystem directories tied to a project device
+
+Devices are keyed by **(organization, user, fingerprint)** so the same physical workstation can appear once per org session.
 
 Use `create` for future work you want to track, `prompt` for work that should start immediately, and `record-work` for work that was already completed in chat and now needs a review ticket plus feed post.
 

package/bin/_cli/launcher.mjs

@@ -68,10 +68,11 @@ const agentIdentifierMap = {
   codex: 'codex',
   cursor: 'cursor',
   gemini: 'gemini',
-  opencode: 'opencode'
+  opencode: 'opencode',
+  pi: 'pi'
 };
 
-const supportedAgents = ['claude', 'codex', 'cursor', 'gemini', 'opencode'];
+const supportedAgents = ['claude', 'codex', 'cursor', 'gemini', 'opencode', 'pi'];
 
 function shellQuote(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`;
@@ -98,6 +99,8 @@ function buildExtraArgs(agent, options = {}) {
       args.push('-c', `model_reasoning_effort=${toTomlString(options.thinking)}`);
     } else if (agent === 'gemini') {
       args.push('--thinking-level', options.thinking);
+    } else if (agent === 'pi') {
+      args.push('--thinking', options.thinking);
     }
   }
 
@@ -378,6 +381,17 @@ async function runAgent(agent, mode = 'run', options = {}) {
           env: childEnv
         });
       }
+    } else if (agent === 'pi') {
+      if (mode === 'resume') {
+        const piSessionId = process.env.PI_SESSION_ID?.trim();
+        const args = piSessionId
+          ? ['--session', piSessionId, context]
+          : ['--continue', context];
+        args.unshift(...extraArgs);
+        execFileSync('pi', args, { stdio: 'inherit', env: childEnv });
+      } else {
+        execFileSync('pi', [...extraArgs, context], { stdio: 'inherit', env: childEnv });
+      }
     } else if (agent === 'gemini') {
       // Write context to a temp file. Passing inline content as a positional arg
       // causes Gemini's @-reference parser to lstat(cwd + content) when it encounters
@@ -413,7 +427,9 @@ async function runAgent(agent, mode = 'run', options = {}) {
           ? `No prior Codex session was found. Start one with \`ovld launch codex --ticket-id <ticket_id>\` first.`
           : agent === 'opencode'
             ? `No prior OpenCode session was found. Start one with \`ovld launch opencode --ticket-id <ticket_id>\` first.`
-            : '';
+            : agent === 'pi'
+              ? `No prior Pi session was found. Start one with \`ovld launch pi --ticket-id <ticket_id>\` first.`
+              : '';
     const message = error instanceof Error ? error.message : String(error);
 
     if (isResume && noSessionHint) {

package/bin/_cli/protocol.mjs

@@ -548,6 +548,80 @@ function createLocalCheckpoint({ flags, kind = 'objective', objectiveId, snapsho
   }
 }
 
+function snapshotLocalWorkingTree(repoRoot, parentSha, message) {
+  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.');
+    return execFileSync(
+      'git',
+      ['-C', repoRoot, 'commit-tree', tree, '-p', parentSha, '-m', message],
+      {
+        cwd: repoRoot,
+        env: { ...process.env, NO_COLOR: '1' },
+        encoding: 'utf8'
+      }
+    ).trim();
+  } finally {
+    try {
+      fs.unlinkSync(tempIndex);
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+function restoreLocalCheckpoint({ workspacePath, objectiveId, gitCommitId }) {
+  const repoRoot = resolveGitRepoRoot(workspacePath);
+  if (!repoRoot) throw new Error(`No git repository found at ${workspacePath}.`);
+
+  const ref = `refs/overlord/checkpoints/${objectiveId}`;
+  const target = gitCommitId
+    ? runLocalCommand('git', ['-C', repoRoot, 'rev-parse', '--verify', `${gitCommitId}^{commit}`], {
+        cwd: repoRoot
+      }).trim()
+    : runLocalCommand('git', ['-C', repoRoot, 'rev-parse', '--verify', ref], {
+        cwd: repoRoot
+      }).trim();
+  if (!target) throw new Error(`No checkpoint exists for objective ${objectiveId}.`);
+
+  let safetyRef = null;
+  let safetySha = null;
+  try {
+    const headSha = runLocalCommand('git', ['-C', repoRoot, 'rev-parse', 'HEAD'], {
+      cwd: repoRoot
+    }).trim();
+    const stamp = new Date().toISOString().replace(/[^0-9A-Za-z]/g, '');
+    safetyRef = `refs/overlord/safety/${stamp}`;
+    safetySha = snapshotLocalWorkingTree(
+      repoRoot,
+      headSha,
+      `overlord pre-revert safety ${new Date().toISOString()}`
+    );
+    if (safetySha) {
+      runLocalCommand('git', ['-C', repoRoot, 'update-ref', safetyRef, safetySha], {
+        cwd: repoRoot
+      });
+    }
+  } catch {
+    safetyRef = null;
+    safetySha = null;
+  }
+
+  runLocalCommand('git', ['-C', repoRoot, 'read-tree', '--reset', '-u', target], {
+    cwd: repoRoot
+  });
+
+  return { ref, gitCommitId: target, safetyRef, safetySha };
+}
+
 async function createAndRecordPendingCheckpoints({
   attachData,
   bearerToken,
@@ -1441,6 +1515,223 @@ async function protocolDiscoverProject(args) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// get-device (identify / register the current device)
+// ---------------------------------------------------------------------------
+
+async function protocolGetDevice(args) {
+  const flags = parseFlags(args);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags);
+  const timeoutMs = resolveTimeout(flags);
+
+  const deviceFingerprint = String(flags['device-fingerprint'] ?? process.env.OVERLORD_DEVICE_FINGERPRINT ?? '');
+  if (!deviceFingerprint) {
+    console.error('Error: --device-fingerprint is required (or set OVERLORD_DEVICE_FINGERPRINT)');
+    process.exit(1);
+  }
+
+  const body = {
+    deviceFingerprint,
+    ...(flags['device-hostname'] ? { deviceHostname: String(flags['device-hostname']) } : {}),
+    ...(flags['device-platform'] ? { devicePlatform: String(flags['device-platform']) } : {})
+  };
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/get-device',
+    body,
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+
+  if (data.device?.label) {
+    process.stderr.write(`\nDEVICE_LABEL=${data.device.label}\n`);
+  }
+  if (data.device?.id) {
+    process.stderr.write(`DEVICE_ID=${data.device.id}\n`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// update-device (rename the device label)
+// ---------------------------------------------------------------------------
+
+async function protocolUpdateDevice(args) {
+  const flags = parseFlags(args);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags);
+  const timeoutMs = resolveTimeout(flags);
+
+  const deviceFingerprint = String(flags['device-fingerprint'] ?? process.env.OVERLORD_DEVICE_FINGERPRINT ?? '');
+  if (!deviceFingerprint) {
+    console.error('Error: --device-fingerprint is required (or set OVERLORD_DEVICE_FINGERPRINT)');
+    process.exit(1);
+  }
+  const label = typeof flags.label === 'string' ? flags.label.trim() : '';
+  if (!label) {
+    console.error('Error: --label is required');
+    process.exit(1);
+  }
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/update-device',
+    { deviceFingerprint, label },
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// list-project-resources (list resource directories for a project)
+// ---------------------------------------------------------------------------
+
+async function protocolListProjectResources(args) {
+  const flags = parseFlags(args);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags);
+  const timeoutMs = resolveTimeout(flags);
+
+  const projectId = typeof flags['project-id'] === 'string' ? flags['project-id'].trim() : '';
+  if (!projectId) {
+    console.error('Error: --project-id is required');
+    process.exit(1);
+  }
+
+  const deviceFingerprint = typeof flags['device-fingerprint'] === 'string'
+    ? flags['device-fingerprint'].trim()
+    : (process.env.OVERLORD_DEVICE_FINGERPRINT?.trim() ?? '');
+
+  const body = {
+    projectId,
+    ...(deviceFingerprint ? { deviceFingerprint } : {})
+  };
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/list-project-resources',
+    body,
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// add-project-resource (register a directory for a project on this device)
+// ---------------------------------------------------------------------------
+
+async function protocolAddProjectResource(args) {
+  const flags = parseFlags(args);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags);
+  const timeoutMs = resolveTimeout(flags);
+
+  const projectId = typeof flags['project-id'] === 'string' ? flags['project-id'].trim() : '';
+  const directoryPath = typeof flags['directory'] === 'string'
+    ? flags['directory'].trim()
+    : process.cwd();
+  const deviceFingerprint = String(
+    flags['device-fingerprint'] ?? process.env.OVERLORD_DEVICE_FINGERPRINT ?? ''
+  );
+
+  if (!projectId) {
+    console.error('Error: --project-id is required');
+    process.exit(1);
+  }
+  if (!deviceFingerprint) {
+    console.error('Error: --device-fingerprint is required (or set OVERLORD_DEVICE_FINGERPRINT)');
+    process.exit(1);
+  }
+
+  // Verify directory exists on this device before sending to server
+  const fs = await import('node:fs');
+  if (!fs.existsSync(directoryPath)) {
+    console.error(`Error: Directory does not exist: ${directoryPath}`);
+    process.exit(1);
+  }
+
+  const body = {
+    projectId,
+    directoryPath,
+    deviceFingerprint,
+    ...(typeof flags.label === 'string' ? { label: flags.label } : {}),
+    ...(flags['is-primary'] === true || flags['is-primary'] === 'true' ? { isPrimary: true } : {}),
+    ...(flags['device-hostname'] ? { deviceHostname: String(flags['device-hostname']) } : {}),
+    ...(flags['device-platform'] ? { devicePlatform: String(flags['device-platform']) } : {})
+  };
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/add-project-resource',
+    body,
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+
+  if (data.resource?.id) {
+    process.stderr.write(`\nRESOURCE_ID=${data.resource.id}\n`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// update-project-resource (update path, label, or primary status)
+// ---------------------------------------------------------------------------
+
+async function protocolUpdateProjectResource(args) {
+  const flags = parseFlags(args);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags);
+  const timeoutMs = resolveTimeout(flags);
+
+  const resourceId = typeof flags['resource-id'] === 'string' ? flags['resource-id'].trim() : '';
+  const deviceFingerprint = String(
+    flags['device-fingerprint'] ?? process.env.OVERLORD_DEVICE_FINGERPRINT ?? ''
+  );
+
+  if (!resourceId) {
+    console.error('Error: --resource-id is required');
+    process.exit(1);
+  }
+  if (!deviceFingerprint) {
+    console.error('Error: --device-fingerprint is required (or set OVERLORD_DEVICE_FINGERPRINT)');
+    process.exit(1);
+  }
+
+  const body = {
+    resourceId,
+    deviceFingerprint,
+    ...(typeof flags.directory === 'string' ? { directoryPath: flags.directory.trim() } : {}),
+    ...('label' in flags ? { label: flags.label === 'null' ? null : String(flags.label) } : {}),
+    ...(flags['is-primary'] !== undefined
+      ? { isPrimary: flags['is-primary'] === true || flags['is-primary'] === 'true' }
+      : {})
+  };
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/update-project-resource',
+    body,
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+}
+
 // ---------------------------------------------------------------------------
 // connect (lightweight session, no context returned)
 // ---------------------------------------------------------------------------
@@ -1502,6 +1793,42 @@ async function protocolLoadContext(args) {
   console.log(JSON.stringify(data, null, 2));
 }
 
+// ---------------------------------------------------------------------------
+// revert (restore local working tree to an objective checkpoint)
+// ---------------------------------------------------------------------------
+
+async function protocolRevert(args) {
+  const flags = parseFlags(args);
+  const objectiveId = requireFlag(flags, 'objective-id', 'OVERLORD_OBJECTIVE_ID');
+  const workspacePath = path.resolve(
+    String(flags['working-directory'] ?? process.env.OVERLORD_WORKSPACE_PATH ?? process.cwd())
+  );
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags);
+  const timeoutMs = resolveTimeout(flags);
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/revert',
+    { objectiveId },
+    timeoutMs
+  );
+  const checkpoint = data?.checkpoint;
+  if (!checkpoint?.git_commit_id) {
+    throw new Error('API response did not include a checkpoint git_commit_id.');
+  }
+
+  const result = restoreLocalCheckpoint({
+    workspacePath,
+    objectiveId,
+    gitCommitId: checkpoint.git_commit_id
+  });
+  console.log(JSON.stringify({ ok: true, checkpoint, restore: result }, null, 2));
+}
+
 // ---------------------------------------------------------------------------
 // prompt (create ticket + connect in one call)
 // ---------------------------------------------------------------------------
@@ -1902,6 +2229,7 @@ Subcommands:
   attach                    Start a ticket session and return full working context
   connect                   Start a lightweight session without full context
   load-context              Read ticket context without creating a session
+  revert                    Restore the local working tree to an objective checkpoint
   search-tickets            Find tickets by keyword, status, project, creator, or update date
   discuss-objective          Mark a draft objective as submitted (ready for review/execution)
   create                    Create a draft ticket without attaching (follow-up or standalone)
@@ -1920,6 +2248,11 @@ Subcommands:
   attachment-finalize-upload  Finalize an uploaded attachment row after storage upload
   attachment-download-url     Get a signed download URL for an existing attachment
   attachment-upload-file      Prepare, upload, and finalize a local file in one command
+  get-device                  Identify / register the current device and return its label
+  update-device               Rename this device's label (must be lowercase kebab-case)
+  list-project-resources      List resource directories registered for a project
+  add-project-resource        Register a local directory as a project resource on this device
+  update-project-resource     Update a resource directory's path, label, or primary status
 
 Environment fallback:
   --session-key  <- SESSION_KEY
@@ -1993,6 +2326,16 @@ load-context:
   Required:
     --ticket-id <ticket_id>
 
+revert:
+  Purpose:
+    Fetch an objective checkpoint from Overlord and restore the local git working tree to it.
+  Required:
+    --objective-id <objective-uuid>
+  Optional:
+    --working-directory <path>  Repository to restore (default: current working directory)
+  Notes:
+    A safety snapshot of the current working tree is saved under refs/overlord/safety/ first.
+
 search-tickets:
   Purpose:
     Find tickets in your organization by keyword, status, project, creator, or update window.
@@ -2272,6 +2615,44 @@ attachment-upload-file:
     --content-type <mime>     Defaults to application/octet-stream
     --metadata-json <json>
 
+get-device:
+  Required:
+    --device-fingerprint <fp>  (or OVERLORD_DEVICE_FINGERPRINT env var)
+  Optional:
+    --device-hostname <name>
+    --device-platform <platform>  (darwin|linux|windows)
+
+update-device:
+  Required:
+    --device-fingerprint <fp>  (or OVERLORD_DEVICE_FINGERPRINT env var)
+    --label <label>            Lowercase kebab-case, unique within org
+
+list-project-resources:
+  Required:
+    --project-id <uuid>
+  Optional:
+    --device-fingerprint <fp>  Filter to current device only
+
+add-project-resource:
+  Required:
+    --project-id <uuid>
+    --device-fingerprint <fp>  (or OVERLORD_DEVICE_FINGERPRINT env var)
+  Optional:
+    --directory <path>         Defaults to current working directory
+    --label <text>
+    --is-primary               Mark as primary directory for this device+project
+    --device-hostname <name>
+    --device-platform <platform>
+
+update-project-resource:
+  Required:
+    --resource-id <uuid>       From list-project-resources output
+    --device-fingerprint <fp>  (or OVERLORD_DEVICE_FINGERPRINT env var)
+  Optional:
+    --directory <path>         New absolute path
+    --label <text>             New label (pass 'null' to clear)
+    --is-primary <true|false>
+
 Examples:
   ovld protocol auth-status
   ovld protocol discover-project
@@ -2281,6 +2662,7 @@ Examples:
   ovld protocol attach --ticket-id 1:899 --external-session-id null
   ovld protocol connect --ticket-id 1:899
   ovld protocol load-context --ticket-id 1:899
+  ovld protocol revert --objective-id <objective-uuid>
   ovld protocol search-tickets --query "auth refactor" --status next-up,execute --limit 10
   ovld protocol discuss-objective --ticket-id 1:899
   ovld protocol discuss-objective --ticket-id 1:899 --objective-id <objective-uuid>
@@ -2309,6 +2691,14 @@ Examples:
   ovld protocol record-work --payload-file - <<'EOF'
     {"objective":"...","summary":"...","artifacts":[...],"changeRationales":[...]}
 EOF
+  ovld protocol get-device --device-fingerprint $OVERLORD_DEVICE_FINGERPRINT
+  ovld protocol update-device --device-fingerprint $OVERLORD_DEVICE_FINGERPRINT --label work-macbook
+  ovld protocol list-project-resources --project-id <project-uuid>
+  ovld protocol list-project-resources --project-id <project-uuid> --device-fingerprint $OVERLORD_DEVICE_FINGERPRINT
+  ovld protocol add-project-resource --project-id <project-uuid> --device-fingerprint $OVERLORD_DEVICE_FINGERPRINT
+  ovld protocol add-project-resource --project-id <project-uuid> --directory /path/to/repo --device-fingerprint $OVERLORD_DEVICE_FINGERPRINT --label "main checkout" --is-primary
+  ovld protocol update-project-resource --resource-id <resource-uuid> --device-fingerprint $OVERLORD_DEVICE_FINGERPRINT --label "docs branch"
+  ovld protocol update-project-resource --resource-id <resource-uuid> --device-fingerprint $OVERLORD_DEVICE_FINGERPRINT --is-primary true
 `);
     return;
   }
@@ -2333,6 +2723,10 @@ EOF
     await protocolLoadContext(args);
     return;
   }
+  if (subcommand === 'revert') {
+    await protocolRevert(args);
+    return;
+  }
   if (subcommand === 'search-tickets') {
     await protocolSearchTickets(args);
     return;
@@ -2405,6 +2799,26 @@ EOF
     await protocolDeliver(args);
     return;
   }
+  if (subcommand === 'get-device') {
+    await protocolGetDevice(args);
+    return;
+  }
+  if (subcommand === 'update-device') {
+    await protocolUpdateDevice(args);
+    return;
+  }
+  if (subcommand === 'list-project-resources') {
+    await protocolListProjectResources(args);
+    return;
+  }
+  if (subcommand === 'add-project-resource') {
+    await protocolAddProjectResource(args);
+    return;
+  }
+  if (subcommand === 'update-project-resource') {
+    await protocolUpdateProjectResource(args);
+    return;
+  }
 
   console.error(`Unknown protocol subcommand: ${subcommand}\n`);
   console.log('Run: ovld protocol help');

package/package.json

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

@@ -27,6 +27,8 @@ Attach:
 ovld protocol attach --ticket-id $TICKET_ID
 ```
 
+In a git workspace, `attach` automatically creates a local git checkpoint for each executing objective before work begins, stored under `refs/overlord/checkpoints/<objectiveId>`. Pass `--skip-checkpoint` only when intentionally bypassing local provenance.
+
 Update:
 
 ```bash
@@ -75,7 +77,15 @@ 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 @@"}]}]'
 ```
 
-`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. Use `--payload-json` when the full delivery object fits comfortably inline. 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 the summary contains special characters, use `--summary-file -` and pipe via a single-quoted heredoc (`<<'EOF'`) to prevent shell expansion. 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.
+Use `--payload-json` when the full delivery object fits comfortably inline. 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 the summary contains special characters, use `--summary-file -` and pipe via a single-quoted heredoc (`<<'EOF'`) to prevent shell expansion. 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.
+
+Revert an objective:
+
+```bash
+ovld protocol revert --objective-id <objective-id>
+```
+
+`revert` restores the local working tree to the recorded objective checkpoint and saves a safety ref under `refs/overlord/safety/` first.
 
 ## Mode 2: Asked From Chat To Use Overlord
 

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

@@ -25,6 +25,8 @@ Attach:
 ovld protocol attach --ticket-id $TICKET_ID
 ```
 
+In a git workspace, `attach` automatically creates a local git checkpoint for each executing objective before work begins, stored under `refs/overlord/checkpoints/<objectiveId>`. Pass `--skip-checkpoint` only when intentionally bypassing local provenance.
+
 Update:
 
 ```bash
@@ -61,7 +63,15 @@ 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 @@"}]}]'
 ```
 
-`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. Use `--payload-json` when the full delivery object fits comfortably inline. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed.
+Use `--payload-json` when the full delivery object fits comfortably inline. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed.
+
+Revert an objective:
+
+```bash
+ovld protocol revert --objective-id <objective-id>
+```
+
+`revert` restores the local working tree to the recorded objective checkpoint and saves a safety ref under `refs/overlord/safety/` first.
 
 ## Mode 2: Asked From Chat To Use Overlord
 

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

@@ -365,9 +365,8 @@ const tools = [
         checkpoint: {
           type: 'object',
           description:
-            'Optional checkpoint metadata. The local CLI creates this automatically for JJ/Git workspaces during deliver.'
+            'Optional checkpoint metadata. Local git checkpoints are created on `attach`, not deliver; this field is only for callers forwarding pre-recorded checkpoint provenance.'
         },
-        skip_checkpoint: { type: 'boolean' },
         skip_file_change_check: { type: 'boolean' }
       },
       required: ['session_key', 'ticket_id', 'summary']
@@ -376,7 +375,6 @@ 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 =>

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

@@ -25,6 +25,8 @@ Attach:
 ovld protocol attach --ticket-id $TICKET_ID
 ```
 
+In a git workspace, `attach` automatically creates a local git checkpoint for each executing objective before work begins, stored under `refs/overlord/checkpoints/<objectiveId>`. Pass `--skip-checkpoint` only when intentionally bypassing local provenance.
+
 Update:
 
 ```bash
@@ -65,7 +67,15 @@ 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 @@"}]}]'
 ```
 
-`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. Use `--payload-json` when the full delivery object fits comfortably inline. 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.
+Use `--payload-json` when the full delivery object fits comfortably inline. 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.
+
+Revert an objective:
+
+```bash
+ovld protocol revert --objective-id <objective-id>
+```
+
+`revert` restores the local working tree to the recorded objective checkpoint and saves a safety ref under `refs/overlord/safety/` first.
 
 ## Mode 2: Asked From Chat To Use Overlord