overlord-cli 0.2605211800.0 → 0.2605211850.1

package/bin/_cli/runner.mjs

@@ -9,6 +9,12 @@ import path from 'node:path';
 const OVLD_ENTRY = process.argv[1];
 const DEVICE_FILE = path.join(os.homedir(), '.ovld', 'device.json');
 
+/** @internal Test-only overrides for protocol/launch subprocess calls. */
+export const runnerTestHooks = {
+  execFileSync: null,
+  spawn: null
+};
+
 function printRunnerHelp(primaryCommand = 'ovld') {
   console.log(`Usage:
   ${primaryCommand} runner once [options]
@@ -45,7 +51,7 @@ function parseFlags(args) {
   return flags;
 }
 
-function readOrCreateDeviceFingerprint(flags) {
+export function readOrCreateDeviceFingerprint(flags) {
   const explicit =
     typeof flags['device-fingerprint'] === 'string'
       ? flags['device-fingerprint'].trim()
@@ -69,7 +75,8 @@ function readOrCreateDeviceFingerprint(flags) {
 }
 
 function runOvld(args, env = {}) {
-  return execFileSync(process.execPath, [OVLD_ENTRY, ...args], {
+  const exec = runnerTestHooks.execFileSync ?? execFileSync;
+  return exec(process.execPath, [OVLD_ENTRY, ...args], {
     encoding: 'utf8',
     env: { ...process.env, ...env }
   });
@@ -111,7 +118,7 @@ function failLaunch(requestId, deviceFingerprint, error) {
   );
 }
 
-function buildLaunchArgs(launch) {
+export function buildLaunchArgs(launch) {
   const args = ['launch', launch.agent, '--ticket-id', launch.ticketId];
   if (launch.workingDirectory) args.push('--working-directory', launch.workingDirectory);
   if (launch.launchMode === 'ask') args.push('--launch-mode', 'ask');
@@ -127,7 +134,7 @@ function buildLaunchArgs(launch) {
   return args;
 }
 
-async function launchClaimedRequest(claim, deviceFingerprint) {
+export async function launchClaimedRequest(claim, deviceFingerprint) {
   const requestId = claim.request?.id;
   if (!requestId || !claim.launch?.agent || !claim.launch?.ticketId) return false;
 
@@ -137,7 +144,8 @@ async function launchClaimedRequest(claim, deviceFingerprint) {
   );
 
   await new Promise((resolve, reject) => {
-    const child = spawn(process.execPath, [OVLD_ENTRY, ...args], {
+    const spawnImpl = runnerTestHooks.spawn ?? spawn;
+    const child = spawnImpl(process.execPath, [OVLD_ENTRY, ...args], {
       stdio: 'inherit',
       env: { ...process.env, OVERLORD_DEVICE_FINGERPRINT: deviceFingerprint }
     });
@@ -170,7 +178,7 @@ async function launchClaimedRequest(claim, deviceFingerprint) {
   return true;
 }
 
-async function runOnce(flags, deviceFingerprint) {
+export async function runOnce(flags, deviceFingerprint) {
   const claim = claimExecution(flags, deviceFingerprint);
   if (!claim.request) {
     process.stderr.write('[runner] no queued execution requests\n');

package/bin/_cli/setup.mjs

@@ -14,10 +14,86 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { checkForCliUpdate, getCurrentCliVersion, printCliUpdateNotice } from './cli-update.mjs';
-import {
-  geminiLegacyCommandFiles,
-  removeLegacyGeminiConnector as removeLegacyGeminiConnectorFiles
-} from '../../../../lib/overlord/legacy-gemini-connector.cjs';
+
+// ---------------------------------------------------------------------------
+// Legacy Gemini connector (inlined — the lib/ directory is not published with
+// the npm package, so the old relative import broke on global installs)
+// ---------------------------------------------------------------------------
+
+const GEMINI_LEGACY_COMMANDS_DIR = path.join(os.homedir(), '.gemini', 'commands');
+
+function geminiLegacyCommandFiles() {
+  const base = GEMINI_LEGACY_COMMANDS_DIR;
+  return [
+    {
+      path: path.join(base, 'connect.toml'),
+      content: `description = "Connect this session to another Overlord ticket (requires: ticket-id)."\nprompt = """\nConnect this session to another Overlord ticket.\n\nTreat \`{{args}}\` as the target ticket ID.\nIf no ticket ID was provided, ask the user for one and stop.\n\nRun:\n\`ovld protocol connect --ticket-id <ticket_id>\`\n\nRules:\n- Use \`connect\`, not \`attach\`.\n- Do not load extra ticket context unless the user explicitly asks for it.\n- After the command succeeds, report the returned \`SESSION_KEY\` and confirm that future updates should use that ticket.\n"""`
+    },
+    {
+      path: path.join(base, 'load.toml'),
+      content: `description = "Load Overlord ticket context (requires: ticket-id)."\nprompt = """\nLoad Overlord ticket context without attaching to the ticket.\n\nTreat \`{{args}}\` as the target ticket ID.\nIf no ticket ID was provided, ask the user for one and stop.\n\nRun:\n\`ovld protocol load-context --ticket-id <ticket_id>\`\n\nRules:\n- Use \`load-context\`, not \`attach\`.\n- Do not create or switch sessions.\n- Summarize the returned ticket details, history, artifacts, and shared context for the user.\n"""`
+    },
+    {
+      path: path.join(base, 'attach.toml'),
+      content: `description = "Attach this session to an Overlord ticket (requires: ticket-id)."\nprompt = """\nAttach this session to an Overlord ticket.\n\nTreat \`{{args}}\` as the target ticket ID.\nIf no ticket ID was provided, ask the user for one and stop.\n\nRun:\n\`ovld protocol attach --ticket-id <ticket_id>\`\n\nRules:\n- Use \`attach\` to establish a persistent session with a ticket.\n- After the command succeeds, report the returned \`SESSION_KEY\` and confirm that future updates should use that ticket.\n"""`
+    },
+    {
+      path: path.join(base, 'discuss-objective.toml'),
+      content: `description = "Mark a ticket's draft objective as submitted (in discussion)."\nprompt = """\nMark a draft objective as "submitted", indicating the ticket is in active discussion with an agent.\n\nTreat \`{{args}}\` as the target ticket ID.\nIf no ticket ID was provided, ask the user for one and stop.\n\nRun:\n\`ovld protocol discuss-objective --ticket-id <ticket_id>\`\n\nRules:\n- This does NOT start execution. Use \`attach\` for that.\n- After the command succeeds, confirm the objective was submitted.\n"""`
+    },
+    {
+      path: path.join(base, 'add-objectives.toml'),
+      content: `description = "Append ordered objectives to an existing Overlord ticket."\nprompt = """\nAppend ordered objectives to an existing ticket.\n\nUse this when prompts are sequential steps toward the same feature or goal. Create separate tickets when prompts represent different features or goals.\n\nRun:\n\`ovld protocol add-objectives --ticket-id <ticket_id> --objectives-json '[{"objective":"Step one"},{"objective":"Step two"}]'\`\n\nIndex 0 is the first newly added objective to execute; later indexes queue after it.\n"""`
+    },
+    {
+      path: path.join(base, 'create.toml'),
+      content: `description = "Create a draft Overlord ticket from the current conversation."\nprompt = """\nCreate a draft Overlord ticket from the user's request.\n\nUse \`{{args}}\` as the input.\nIf it already contains flags such as \`--title\`, \`--priority\`, \`--project-id\`, or \`--execution-target\`, pass those flags through after \`ovld protocol create --agent gemini\`.\nOtherwise, treat \`{{args}}\` as the objective text and run:\n\`ovld protocol create --agent gemini --objective "<objective>"\`\n\nIf no objective was provided, ask the user for one and stop.\n\nAfter the command succeeds, report the new \`TICKET_ID\`.\n"""`
+    },
+    {
+      path: path.join(base, 'prompt.toml'),
+      content: `description = "Create a new Overlord ticket from the current conversation."\nprompt = """\nCreate a new Overlord ticket from the user's request.\n\nUse \`{{args}}\` as the input.\nIf it already contains flags such as \`--title\`, \`--priority\`, \`--project-id\`, or \`--execution-target\`, pass those flags through after \`ovld protocol prompt --agent gemini\`.\nOtherwise, treat \`{{args}}\` as the objective text and run:\n\`ovld protocol prompt --agent gemini --objective "<objective>"\`\n\nIf no objective was provided, ask the user for one and stop.\n\nAfter the command succeeds, report the new \`TICKET_ID\` and \`SESSION_KEY\`.\n"""`
+    },
+    {
+      path: path.join(base, 'record-work.toml'),
+      content: `description = "Record completed-from-chat work as a ticket in review + feed post (no attach)."\nprompt = """\nImmediately record the work you just completed in this chat as a new Overlord ticket via \`ovld protocol record-work\`. No agent session is opened — the work is already done.\n\nSynthesize from the current conversation:\n- \`objective\`: what was asked / what was done.\n- \`summary\`: reviewer-friendly narrative for the feed.\n- \`changeRationales\`: one entry per meaningful git-tracked file change (\`label\`, \`file_path\`, \`summary\`, \`why\`, \`impact\`, optional \`hunks\`). Use \`git status\` and \`git diff\` to enumerate changed files.\n- \`artifacts\` (optional): \`next_steps\`, \`test_results\`, \`decision\`, \`note\`, \`url\`.\n\nIf \`{{args}}\` is non-empty, treat it as additional context to weave into the summary.\n\nRun \`ovld protocol record-work --payload-file -\` and stream a JSON object \`{ "objective": "...", "summary": "...", "artifacts": [...], "changeRationales": [...] }\` on stdin via a single-quoted heredoc.\n\nAfter the command succeeds, report the new \`TICKET_ID\`.\n\nRules:\n- Do NOT use this for in-progress work. Use \`/prompt\` for that.\n- The CLI validates that every changed git-tracked file is represented in \`changeRationales\` unless \`--skip-file-change-check\` is passed.\n- If project resolution fails, re-run with \`--project-id <id>\` or \`--personal\`.\n"""`
+    }
+  ];
+}
+
+function isRemovableLegacyGeminiCommandFile({ filePath, content, manifestFiles }) {
+  if (manifestFiles.has(filePath)) return true;
+  const managed = geminiLegacyCommandFiles().find(file => file.path === filePath);
+  if (!managed) return false;
+  return content.trim() === managed.content.trim();
+}
+
+function removeLegacyGeminiConnectorFiles({ readManifest, writeManifest, readTextFile, existsSync = fs.existsSync.bind(fs), rmSync = fs.rmSync.bind(fs) }) {
+  const removed = [];
+  const manifest = readManifest();
+  const manifestFiles = new Set(manifest.gemini?.files ?? []);
+
+  for (const file of geminiLegacyCommandFiles()) {
+    if (!existsSync(file.path)) continue;
+    const existing = readTextFile(file.path);
+    if (!isRemovableLegacyGeminiCommandFile({ filePath: file.path, content: existing, manifestFiles })) continue;
+    rmSync(file.path, { force: true });
+    removed.push(file.path);
+  }
+
+  for (const filePath of manifestFiles) {
+    if (removed.includes(filePath) || !existsSync(filePath)) continue;
+    if (!filePath.includes('.gemini/commands') || !filePath.endsWith('.toml')) continue;
+    rmSync(filePath, { force: true });
+    removed.push(filePath);
+  }
+
+  if (manifest.gemini) {
+    delete manifest.gemini;
+    writeManifest(manifest);
+  }
+
+  return removed;
+}
 
 const BUNDLE_VERSION = '1.12.0';
 const MD_MARKER_START = '<!-- overlord:managed:start -->';

package/package.json

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

@@ -58,7 +58,11 @@ Always include `changeRationales` when delivering. Optionally include them on up
 
 Before delivering, make sure every meaningful git-tracked file change is represented in `changeRationales`; do not send `file_changes` as an artifact. Record only meaningful behavioral changes. Skip formatting-only noise.
 
-For the `record-change-rationales` command and `--change-rationales-json` payload shape see [reference/cli.md](reference/cli.md).
+Each rationale entry requires these fields: `file_path`, `label`, `summary`, `why`, `impact` — all strings. Do **not** use `filePath` or `rationale`; those are a different internal shape and will cause a validation error.
+
+For more than a handful of entries, use `--change-rationales-file` with a temp file or stdin (`-`) instead of inline `--change-rationales-json` to avoid shell quoting failures with large arrays.
+
+For the `record-change-rationales` command and full payload shape with optional `hunks` see [reference/cli.md](reference/cli.md).
 
 ## Rules
 

package/plugins/claude/skills/overlord-ticket/reference/cli.md

@@ -64,6 +64,8 @@ ovld protocol revert --objective-id <objective-id>
 
 These are structured protocol payloads that Overlord stores as first-class rows in the `file_changes` table. Prefer inline JSON or the dedicated command below. Use `--payload-json` for compact full delivery payloads, or `--payload-file -` when the JSON is larger or quote-sensitive so summary, artifacts, and change rationales stay in one JSON document without creating a temporary file.
 
+**Required fields per entry:** `file_path`, `label`, `summary`, `why`, `impact` (all strings). Do not use `filePath` or `rationale` — those are the internal API shape and will fail CLI validation.
+
 ```bash
 ovld protocol record-change-rationales --session-key <sessionKey> --ticket-id $TICKET_ID \
   --summary "Recorded rationale details for the latest code changes." --phase execute \
@@ -76,6 +78,19 @@ ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID \
   --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 @@"}]}]'
 ```
 
+For many entries (roughly 5+), pipe via stdin to avoid shell quoting failures:
+
+```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-file - <<'EOF'
+[
+  {"label":"Add backoff","file_path":"lib/api.ts","summary":"Added retry.","why":"Transient failures.","impact":"Retries 3x."},
+  {"label":"Update config","file_path":"lib/config.ts","summary":"Added timeout.","why":"Match new defaults.","impact":"Requests time out after 30s."}
+]
+EOF
+```
+
 ## Project Discovery And Ticket Creation
 
 When creating tickets from within a repository:

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

@@ -58,7 +58,11 @@ Always include `changeRationales` when delivering. Optionally include them on up
 
 Before delivering, make sure every meaningful git-tracked file change is represented in `changeRationales`; do not send `file_changes` as an artifact. Record only meaningful behavioral changes. Skip formatting-only noise.
 
-For the `record-change-rationales` command and `--change-rationales-json` payload shape see [reference/cli.md](reference/cli.md).
+Each rationale entry requires these fields: `file_path`, `label`, `summary`, `why`, `impact` — all strings. Do **not** use `filePath` or `rationale`; those are a different internal shape and will cause a validation error.
+
+For more than a handful of entries, use `--change-rationales-file` with a temp file or stdin (`-`) instead of inline `--change-rationales-json` to avoid shell quoting failures with large arrays.
+
+For the `record-change-rationales` command and full payload shape with optional `hunks` see [reference/cli.md](reference/cli.md).
 
 ## Rules
 

package/plugins/cursor/skills/overlord-ticket/reference/cli.md

@@ -64,6 +64,8 @@ ovld protocol revert --objective-id <objective-id>
 
 These are structured protocol payloads that Overlord stores as first-class rows in the `file_changes` table. Prefer inline JSON or the dedicated command below. Use `--payload-json` for compact full delivery payloads, or `--payload-file -` when the JSON is larger or quote-sensitive so summary, artifacts, and change rationales stay in one JSON document without creating a temporary file.
 
+**Required fields per entry:** `file_path`, `label`, `summary`, `why`, `impact` (all strings). Do not use `filePath` or `rationale` — those are the internal API shape and will fail CLI validation.
+
 ```bash
 ovld protocol record-change-rationales --session-key <sessionKey> --ticket-id $TICKET_ID \
   --summary "Recorded rationale details for the latest code changes." --phase execute \
@@ -76,6 +78,19 @@ ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID \
   --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 @@"}]}]'
 ```
 
+For many entries (roughly 5+), pipe via stdin to avoid shell quoting failures:
+
+```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-file - <<'EOF'
+[
+  {"label":"Add backoff","file_path":"lib/api.ts","summary":"Added retry.","why":"Transient failures.","impact":"Retries 3x."},
+  {"label":"Update config","file_path":"lib/config.ts","summary":"Added timeout.","why":"Match new defaults.","impact":"Requests time out after 30s."}
+]
+EOF
+```
+
 ## Project Discovery And Ticket Creation
 
 When creating tickets from within a repository:

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

@@ -58,7 +58,11 @@ Always include `changeRationales` when delivering. Optionally include them on up
 
 Before delivering, make sure every meaningful git-tracked file change is represented in `changeRationales`; do not send `file_changes` as an artifact. Record only meaningful behavioral changes. Skip formatting-only noise.
 
-For the `record-change-rationales` command and `--change-rationales-json` payload shape see [reference/cli.md](reference/cli.md).
+Each rationale entry requires these fields: `file_path`, `label`, `summary`, `why`, `impact` — all strings. Do **not** use `filePath` or `rationale`; those are a different internal shape and will cause a validation error.
+
+For more than a handful of entries, use `--change-rationales-file` with a temp file or stdin (`-`) instead of inline `--change-rationales-json` to avoid shell quoting failures with large arrays.
+
+For the `record-change-rationales` command and full payload shape with optional `hunks` see [reference/cli.md](reference/cli.md).
 
 ## Rules
 

package/plugins/overlord/skills/overlord-ticket/reference/cli.md

@@ -64,6 +64,8 @@ ovld protocol revert --objective-id <objective-id>
 
 These are structured protocol payloads that Overlord stores as first-class rows in the `file_changes` table. Prefer inline JSON or the dedicated command below. Use `--payload-json` for compact full delivery payloads, or `--payload-file -` when the JSON is larger or quote-sensitive so summary, artifacts, and change rationales stay in one JSON document without creating a temporary file.
 
+**Required fields per entry:** `file_path`, `label`, `summary`, `why`, `impact` (all strings). Do not use `filePath` or `rationale` — those are the internal API shape and will fail CLI validation.
+
 ```bash
 ovld protocol record-change-rationales --session-key <sessionKey> --ticket-id $TICKET_ID \
   --summary "Recorded rationale details for the latest code changes." --phase execute \
@@ -76,6 +78,19 @@ ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID \
   --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 @@"}]}]'
 ```
 
+For many entries (roughly 5+), pipe via stdin to avoid shell quoting failures:
+
+```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-file - <<'EOF'
+[
+  {"label":"Add backoff","file_path":"lib/api.ts","summary":"Added retry.","why":"Transient failures.","impact":"Retries 3x."},
+  {"label":"Update config","file_path":"lib/config.ts","summary":"Added timeout.","why":"Match new defaults.","impact":"Requests time out after 30s."}
+]
+EOF
+```
+
 ## Project Discovery And Ticket Creation
 
 When creating tickets from within a repository: