overlord-cli 3.23.0 → 3.24.0

package/bin/_cli/protocol.mjs

@@ -189,6 +189,37 @@ function readJsonFile(filePath, label) {
   }
 }
 
+async function readTextFromStdin(label) {
+  const chunks = [];
+  try {
+    for await (const chunk of process.stdin) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    }
+  } catch (err) {
+    throw new Error(
+      `${label}: could not read stdin: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+async function readJsonFileOrStdin(filePath, label) {
+  if (filePath !== '-') {
+    return readJsonFile(filePath, label);
+  }
+
+  try {
+    return JSON.parse(await readTextFromStdin(label));
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith(`${label}: could not read stdin`)) {
+      throw err;
+    }
+    throw new Error(
+      `${label}: could not parse stdin: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+
 // ---------------------------------------------------------------------------
 // changeRationales helper
 // ---------------------------------------------------------------------------
@@ -200,7 +231,10 @@ function readJsonFile(filePath, label) {
  */
 async function resolveChangeRationales(flags) {
   if (flags['change-rationales-file']) {
-    return readJsonFile(String(flags['change-rationales-file']), '--change-rationales-file');
+    return await readJsonFileOrStdin(
+      String(flags['change-rationales-file']),
+      '--change-rationales-file'
+    );
   }
   if (flags['change-rationales-json']) {
     try {
@@ -624,7 +658,7 @@ async function protocolDeliver(args) {
   if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
   if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
   const deliverPayload = flags['payload-file']
-    ? readJsonFile(String(flags['payload-file']), '--payload-file')
+    ? await readJsonFileOrStdin(String(flags['payload-file']), '--payload-file')
     : null;
   const summary = deliverPayload?.summary ??
     (flags['summary-file']
@@ -642,7 +676,7 @@ async function protocolDeliver(args) {
     throw new Error('Use either --payload-file or --artifacts-json, not both');
   }
   if (flags['artifacts-file']) {
-    artifacts = readJsonFile(String(flags['artifacts-file']), '--artifacts-file');
+    artifacts = await readJsonFileOrStdin(String(flags['artifacts-file']), '--artifacts-file');
   } else if (flags['artifacts-json']) {
     try {
       artifacts = JSON.parse(String(flags['artifacts-json']));
@@ -1144,14 +1178,15 @@ deliver:
     --session-key <key>
     --ticket-id <id>
     --summary <text> or --summary-file <path>
-    or: --payload-file <path> containing { summary, artifacts, changeRationales }
+    or: --payload-file <path|-> containing { summary, artifacts, changeRationales }
   Optional:
     --artifacts-json <json>
-    --artifacts-file <path>
+    --artifacts-file <path|->
     --change-rationales-json <json>
-    --change-rationales-file <path>
+    --change-rationales-file <path|->
     --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.
     In a git workspace, deliver validates that changed files are represented by changeRationales unless skipped.
 
@@ -1243,6 +1278,7 @@ Examples:
   ovld protocol deliver --session-key <key> --ticket-id <id> --summary "Done"
   ovld protocol deliver --session-key <key> --ticket-id <id> --summary "Done" --artifacts-file ./artifacts.json
   ovld protocol deliver --session-key <key> --ticket-id <id> --payload-file ./deliver.json
+  ovld protocol deliver --session-key <key> --ticket-id <id> --payload-file -
   ovld protocol deliver --session-key <key> --ticket-id <id> --summary "Done" --skip-file-change-check
   ovld protocol deliver --session-key <key> --ticket-id <id> --summary "Done" --timeout 60000
 `);

package/bin/_cli/setup.mjs

@@ -84,11 +84,11 @@ If you receive a prompt with a specified ticket ID, adhere to the following. If
      --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 or quote-sensitive deliveries, prefer a single JSON file:
+   For larger or quote-sensitive deliveries, prefer a single JSON payload on stdin:
    \`\`\`bash
-   ovld protocol deliver --session-key <sessionKey> --ticket-id $TICKET_ID --payload-file ./deliver.json
+   ovld protocol deliver --session-key <sessionKey> --ticket-id $TICKET_ID --payload-file -
    \`\`\`
-   Treat \`deliver.json\` as ephemeral scratch data only. Create it outside the repository when practical, never commit it, and remove it after delivery.
+   This avoids creating a scratch delivery file that needs cleanup. If your runtime cannot provide stdin directly, \`--payload-file ./deliver.json\` remains supported; treat that file as ephemeral scratch data, never commit it, and remove it after delivery.
 
 ## Change Rationales
 
@@ -96,7 +96,7 @@ Always include \`changeRationales\` when delivering. Optionally include them on
 
 Before delivering, make sure every meaningful git-tracked file change is represented in \`changeRationales\`; do not send \`file_changes\` as an artifact.
 
-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. For quote-sensitive deliveries, prefer \`--payload-file\` so summary, artifacts, and change rationales stay in one JSON document, but treat that JSON as ephemeral scratch data rather than a repository artifact. Ordinary deliver artifacts should use \`next_steps\`, \`test_results\`, \`migration\`, \`note\`, \`url\`, or \`decision\`.
+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. For larger full delivery payloads, prefer \`--payload-file -\` so summary, artifacts, and change rationales stay in one JSON document without creating a temporary file. Ordinary deliver artifacts should use \`next_steps\`, \`test_results\`, \`migration\`, \`note\`, \`url\`, or \`decision\`.
 
 \`\`\`bash
 ovld protocol record-change-rationales --session-key <sessionKey> --ticket-id $TICKET_ID \\\\
@@ -158,11 +158,11 @@ If you receive a prompt with a specified ticket ID, adhere to the following. If
      --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 @@"}]}]'
    \`\`\`
-   If you use \`--payload-file\`, \`--artifacts-file\`, or \`--change-rationales-file\` for larger JSON, treat that file as ephemeral scratch data outside the repository and remove it after delivery. Do not leave delivery JSON checked into the worktree.
+   For larger delivery JSON, prefer \`--payload-file -\` and stream the full payload 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. Do not leave delivery JSON checked into the worktree.
 
 ## Change Rationales
 
-Always include \`changeRationales\` when delivering. 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. Overlord stores these as structured rows in the \`file_changes\` table. If you need a JSON file for transport, keep it ephemeral and out of the repository.
+Always include \`changeRationales\` when delivering. 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. Overlord stores these as structured rows in the \`file_changes\` table. For larger delivery payloads, prefer \`--payload-file -\` with stdin. If you need a JSON file for transport, keep it ephemeral and out of the repository.
 
 \`\`\`bash
 ovld protocol record-change-rationales --session-key <sessionKey> --ticket-id $TICKET_ID \\\\
@@ -231,7 +231,7 @@ When done, deliver with artifacts and change rationales:
 \`\`\`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 @@"}]}]'
 \`\`\`
-If you use a JSON file for delivery transport, keep it ephemeral scratch data outside the repository and remove it after the protocol call.
+For larger delivery JSON, prefer \`--payload-file -\` with stdin so no scratch file needs to be created or removed. If you use a JSON file for delivery transport, keep it ephemeral scratch data outside the repository and remove it after the protocol call.
 
 Rules:
 - Always attach first and deliver last.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "3.23.0",
+  "version": "3.24.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "type": "module",
   "bin": {

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

@@ -7,6 +7,27 @@ const execFileAsync = promisify(execFile);
 const OVLD_BIN = process.env.OVLD_BIN?.trim() || 'ovld';
 const PROTOCOL_VERSION = '2025-06-18';
 
+function execFileWithOptionalInput(file, args, options, input) {
+  if (input === undefined) {
+    return execFileAsync(file, args, options);
+  }
+
+  return new Promise((resolve, reject) => {
+    const child = execFile(file, args, options, (error, stdout, stderr) => {
+      if (error) {
+        error.stdout = stdout;
+        error.stderr = stderr;
+        reject(error);
+        return;
+      }
+
+      resolve({ stdout, stderr });
+    });
+
+    child.stdin?.end(input);
+  });
+}
+
 const tools = [
   {
     name: 'discover_project',
@@ -239,7 +260,8 @@ const tools = [
   },
   {
     name: 'deliver_ticket',
-    description: 'Deliver final work back into Overlord with summary, artifacts, and change rationales.',
+    description:
+      'Deliver final work back into Overlord with summary, artifacts, and change rationales. Large payloads are streamed to the CLI through stdin, so this tool does not create delivery scratch files.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -255,11 +277,14 @@ const tools = [
     toCliFlags: args => ({
       'session-key': args.session_key,
       'ticket-id': args.ticket_id,
-      summary: args.summary,
-      'artifacts-json': args.artifacts,
-      'change-rationales-json': args.change_rationales,
+      'payload-file': '-',
       '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 } : {})
+    }),
     subcommand: 'deliver'
   },
   {
@@ -490,17 +515,24 @@ function cliArgsFromFlags(flags) {
 }
 
 async function runProtocol(tool, args) {
-  const cliArgs = ['protocol', tool.subcommand, ...cliArgsFromFlags(tool.toCliFlags(args ?? {}))];
+  const toolArgs = args ?? {};
+  const cliArgs = ['protocol', tool.subcommand, ...cliArgsFromFlags(tool.toCliFlags(toolArgs))];
+  const stdin = typeof tool.toCliStdin === 'function' ? tool.toCliStdin(toolArgs) : undefined;
 
   try {
-    const { stdout, stderr } = await execFileAsync(OVLD_BIN, cliArgs, {
-      cwd: process.cwd(),
-      env: {
-        ...process.env,
-        AGENT_IDENTIFIER: process.env.AGENT_IDENTIFIER ?? 'codex-overlord-plugin'
+    const { stdout, stderr } = await execFileWithOptionalInput(
+      OVLD_BIN,
+      cliArgs,
+      {
+        cwd: process.cwd(),
+        env: {
+          ...process.env,
+          AGENT_IDENTIFIER: process.env.AGENT_IDENTIFIER ?? 'codex-overlord-plugin'
+        },
+        maxBuffer: 20 * 1024 * 1024
       },
-      maxBuffer: 20 * 1024 * 1024
-    });
+      stdin
+    );
 
     const trimmed = stdout.trim();
     const data = trimmed ? JSON.parse(trimmed) : {};

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

@@ -15,7 +15,7 @@ Overlord plugin.
    and stop.
 6. Deliver last with `ovld protocol deliver`, including meaningful `changeRationales` for every
    behavioral git-tracked change.
-   If you need `--payload-file`, `--artifacts-file`, or `--change-rationales-file`, treat that JSON as ephemeral scratch data, not as a repository file. Remove it after delivery and never commit it.
+   For larger delivery JSON, prefer `--payload-file -` and stream the full payload on stdin so no scratch file needs to be created or removed. If you need `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that JSON as ephemeral scratch data, not as a repository file. Remove it after delivery and never commit it.
 
 ## Rules