@kody-ade/kody-engine 0.3.50 → 0.3.52

package/dist/bin/kody.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.3.50",
+  version: "0.3.52",
   description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -50,7 +50,7 @@ var package_default = {
 };
 
 // src/chat-cli.ts
-import { execFileSync as execFileSync25 } from "child_process";
+import { execFileSync as execFileSync26 } from "child_process";
 import * as fs26 from "fs";
 import * as path23 from "path";
 
@@ -154,7 +154,7 @@ function loadConfig(projectDir = process.cwd()) {
     throw new Error(`kody.config.json is invalid JSON: ${msg}`);
   }
   const quality = raw.quality ?? {};
-  const git4 = raw.git ?? {};
+  const git5 = raw.git ?? {};
   const github = raw.github ?? {};
   const agent = raw.agent ?? {};
   if (!agent.model || typeof agent.model !== "string") {
@@ -171,7 +171,7 @@ function loadConfig(projectDir = process.cwd()) {
       testUnit: typeof quality.testUnit === "string" ? quality.testUnit : ""
     },
     git: {
-      defaultBranch: typeof git4.defaultBranch === "string" ? git4.defaultBranch : "main"
+      defaultBranch: typeof git5.defaultBranch === "string" ? git5.defaultBranch : "main"
     },
     github: {
       owner: String(github.owner),
@@ -605,7 +605,7 @@ async function emit(sink, type, sessionId, suffix, payload) {
 }
 
 // src/kody-cli.ts
-import { execFileSync as execFileSync24 } from "child_process";
+import { execFileSync as execFileSync25 } from "child_process";
 import * as fs25 from "fs";
 import * as path22 from "path";
 
@@ -1313,6 +1313,12 @@ function parseScriptList(p, key, raw) {
     if (r.with && typeof r.with === "object") {
       entry.with = r.with;
     }
+    if (typeof r.timeoutSec === "number" && r.timeoutSec > 0) {
+      if (!hasShell) {
+        throw new ProfileError(p, `scripts.${key}[${i}] "timeoutSec" only applies to shell entries`);
+      }
+      entry.timeoutSec = r.timeoutSec;
+    }
     out.push(entry);
   }
   return out;
@@ -4632,6 +4638,14 @@ function walkMd(root, visit) {
   }
 }
 
+// src/scripts/markFlowSuccess.ts
+var markFlowSuccess = async (ctx) => {
+  const exit = ctx.output.exitCode;
+  if (exit === void 0 || exit === 0) {
+    ctx.data.agentDone = true;
+  }
+};
+
 // src/scripts/memorizeFlow.ts
 import { execFileSync as execFileSync15 } from "child_process";
 import * as fs22 from "fs";
@@ -5558,6 +5572,120 @@ function tryPostPr3(prNumber, body, cwd) {
   }
 }
 
+// src/scripts/revertFlow.ts
+import { execFileSync as execFileSync19 } from "child_process";
+var SHA_RE = /^[0-9a-f]{4,40}$/i;
+var revertFlow = async (ctx) => {
+  const prNumber = ctx.args.pr;
+  const pr = getPr(prNumber, ctx.cwd);
+  if (pr.state !== "OPEN") {
+    ctx.output.exitCode = 1;
+    ctx.output.reason = `PR #${prNumber} is not OPEN (state: ${pr.state})`;
+    ctx.skipAgent = true;
+    return;
+  }
+  ctx.data.pr = pr;
+  ctx.data.commentTargetType = "pr";
+  ctx.data.commentTargetNumber = prNumber;
+  checkoutPrBranch(prNumber, ctx.cwd);
+  ctx.data.branch = getCurrentBranch(ctx.cwd);
+  const shasArg = String(ctx.args.shas ?? "").trim();
+  if (!shasArg) {
+    ctx.output.exitCode = 64;
+    ctx.output.reason = "no commit SHAs provided \u2014 usage: @kody revert <sha> [<sha> \u2026]";
+    ctx.skipAgent = true;
+    tryPostPr4(prNumber, `\u26A0\uFE0F kody revert FAILED: ${ctx.output.reason}`, ctx.cwd);
+    return;
+  }
+  const requested = shasArg.split(/\s+/).filter((s) => s.length > 0);
+  const bad = requested.filter((s) => !SHA_RE.test(s));
+  if (bad.length > 0) {
+    ctx.output.exitCode = 64;
+    ctx.output.reason = `not valid SHA-shaped tokens: ${bad.join(", ")}`;
+    ctx.skipAgent = true;
+    tryPostPr4(prNumber, `\u26A0\uFE0F kody revert FAILED: ${ctx.output.reason}`, ctx.cwd);
+    return;
+  }
+  const resolved = [];
+  const unreachable = [];
+  for (const s of requested) {
+    let full;
+    try {
+      full = git4(["rev-parse", "--verify", `${s}^{commit}`], ctx.cwd);
+    } catch {
+      unreachable.push(s);
+      continue;
+    }
+    if (!isAncestorOfHead(full, ctx.cwd)) {
+      unreachable.push(s);
+      continue;
+    }
+    let subject = "";
+    try {
+      subject = git4(["log", "-1", "--format=%s", full], ctx.cwd);
+    } catch {
+    }
+    resolved.push({ input: s, full, subject });
+  }
+  if (unreachable.length > 0) {
+    ctx.output.exitCode = 64;
+    ctx.output.reason = `commit(s) not found in this PR branch: ${unreachable.join(", ")}`;
+    ctx.skipAgent = true;
+    tryPostPr4(prNumber, `\u26A0\uFE0F kody revert FAILED: ${ctx.output.reason}`, ctx.cwd);
+    return;
+  }
+  ctx.args.shas = resolved.map((r) => r.full).join(" ");
+  ctx.data.commitMessage = buildCommitMessage(resolved);
+  ctx.data.prSummary = buildPrSummary(resolved);
+  ctx.skipAgent = true;
+  const runUrl = getRunUrl();
+  const runSuffix = runUrl ? `, run ${runUrl}` : "";
+  const shaList = resolved.map((r) => `\`${r.full.slice(0, 7)}\``).join(", ");
+  tryPostPr4(
+    prNumber,
+    `\u2699\uFE0F kody revert started on \`${ctx.data.branch}\`${runSuffix} \u2014 reverting ${shaList}`,
+    ctx.cwd
+  );
+};
+function buildCommitMessage(resolved) {
+  if (resolved.length === 1) {
+    const { full, subject } = resolved[0];
+    return subject ? `revert: "${subject}" (${full.slice(0, 7)})` : `revert: ${full.slice(0, 7)}`;
+  }
+  const shas = resolved.map((r) => r.full.slice(0, 7)).join(", ");
+  return `revert: ${resolved.length} commit(s) (${shas})`;
+}
+function buildPrSummary(resolved) {
+  return resolved.map((r) => `- Reverted \`${r.full.slice(0, 7)}\`${r.subject ? ` \u2014 ${r.subject}` : ""}`).join("\n");
+}
+function git4(args, cwd) {
+  return execFileSync19("git", args, {
+    encoding: "utf-8",
+    timeout: 3e4,
+    cwd,
+    env: { ...process.env, HUSKY: "0", SKIP_HOOKS: "1" },
+    stdio: ["pipe", "pipe", "pipe"]
+  }).trim();
+}
+function isAncestorOfHead(sha, cwd) {
+  try {
+    execFileSync19("git", ["merge-base", "--is-ancestor", sha, "HEAD"], {
+      cwd,
+      env: { ...process.env, HUSKY: "0", SKIP_HOOKS: "1" },
+      stdio: ["ignore", "ignore", "ignore"]
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function tryPostPr4(prNumber, body, cwd) {
+  try {
+    postPrReviewComment(prNumber, body, cwd);
+  } catch {
+  }
+}
+
 // src/scripts/resolvePreviewUrl.ts
 var DEFAULT_PREVIEW_URL = "http://localhost:3000";
 var resolvePreviewUrl = async (ctx) => {
@@ -5595,9 +5723,9 @@ var reviewFlow = async (ctx) => {
   ctx.data.prDiff = getPrDiff(prNumber, ctx.cwd);
   const runUrl = getRunUrl();
   const runSuffix = runUrl ? `, run ${runUrl}` : "";
-  tryPostPr4(prNumber, `\u{1F440} kody review started on PR #${prNumber}${runSuffix}`, ctx.cwd);
+  tryPostPr5(prNumber, `\u{1F440} kody review started on PR #${prNumber}${runSuffix}`, ctx.cwd);
 };
-function tryPostPr4(prNumber, body, cwd) {
+function tryPostPr5(prNumber, body, cwd) {
   try {
     postPrReviewComment(prNumber, body, cwd);
   } catch {
@@ -5710,11 +5838,11 @@ var skipAgent = async (ctx) => {
 };
 
 // src/scripts/stageMergeConflicts.ts
-import { execFileSync as execFileSync19 } from "child_process";
+import { execFileSync as execFileSync20 } from "child_process";
 var stageMergeConflicts = async (ctx) => {
   if (ctx.data.agentDone === false) return;
   try {
-    execFileSync19("git", ["add", "-A"], {
+    execFileSync20("git", ["add", "-A"], {
       cwd: ctx.cwd,
       env: { ...process.env, HUSKY: "0", SKIP_HOOKS: "1" },
       stdio: "pipe"
@@ -5724,7 +5852,7 @@ var stageMergeConflicts = async (ctx) => {
 };
 
 // src/scripts/startFlow.ts
-import { execFileSync as execFileSync20 } from "child_process";
+import { execFileSync as execFileSync21 } from "child_process";
 var API_TIMEOUT_MS9 = 3e4;
 var startFlow = async (ctx, profile, _agentResult, args) => {
   const entry = args?.entry;
@@ -5758,7 +5886,7 @@ function postKodyComment(target, issueNumber, state, next, cwd) {
   const sub = target === "pr" && state?.core.prUrl ? "pr" : "issue";
   const body = `@kody ${next}`;
   try {
-    execFileSync20("gh", [sub, "comment", String(targetNumber), "--body", body], {
+    execFileSync21("gh", [sub, "comment", String(targetNumber), "--body", body], {
       timeout: API_TIMEOUT_MS9,
       cwd,
       stdio: ["ignore", "pipe", "pipe"]
@@ -5772,7 +5900,7 @@ function postKodyComment(target, issueNumber, state, next, cwd) {
 }
 
 // src/scripts/syncFlow.ts
-import { execFileSync as execFileSync21 } from "child_process";
+import { execFileSync as execFileSync22 } from "child_process";
 var syncFlow = async (ctx, _profile, args) => {
   const announceOnSuccess = Boolean(args?.announceOnSuccess);
   const prNumber = ctx.args.pr;
@@ -5810,7 +5938,7 @@ var syncFlow = async (ctx, _profile, args) => {
     if (announceOnSuccess) {
       ctx.output.exitCode = 0;
       ctx.output.reason = `already up to date with origin/${baseBranch}`;
-      tryPostPr5(prNumber, `\u2139\uFE0F kody sync: already up to date with origin/${baseBranch}`, ctx.cwd);
+      tryPostPr6(prNumber, `\u2139\uFE0F kody sync: already up to date with origin/${baseBranch}`, ctx.cwd);
     }
     return;
   }
@@ -5827,7 +5955,7 @@ var syncFlow = async (ctx, _profile, args) => {
     ctx.output.reason = `merged origin/${baseBranch} into ${ctx.data.branch}`;
     const runUrl = getRunUrl();
     const runSuffix = runUrl ? ` ([logs](${runUrl}))` : "";
-    tryPostPr5(
+    tryPostPr6(
       prNumber,
       `\u2705 kody sync: merged \`origin/${baseBranch}\` into \`${ctx.data.branch}\`${runSuffix}`,
       ctx.cwd
@@ -5840,11 +5968,11 @@ function bail2(ctx, prNumber, reason) {
   ctx.output.reason = reason;
   const runUrl = getRunUrl();
   const runSuffix = runUrl ? ` ([logs](${runUrl}))` : "";
-  tryPostPr5(prNumber, `\u274C kody sync could not complete${runSuffix}: ${reason}`, ctx.cwd);
+  tryPostPr6(prNumber, `\u274C kody sync could not complete${runSuffix}: ${reason}`, ctx.cwd);
 }
 function revParseHead(cwd) {
   try {
-    return execFileSync21("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).toString().trim();
+    return execFileSync22("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).toString().trim();
   } catch {
     return "";
   }
@@ -5852,16 +5980,16 @@ function revParseHead(cwd) {
 function pushBranch(branch, cwd) {
   const env = { ...process.env, HUSKY: "0", SKIP_HOOKS: "1" };
   try {
-    execFileSync21("git", ["push", "-u", "origin", branch], { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    execFileSync22("git", ["push", "-u", "origin", branch], { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
   } catch {
-    execFileSync21("git", ["push", "--force-with-lease", "-u", "origin", branch], {
+    execFileSync22("git", ["push", "--force-with-lease", "-u", "origin", branch], {
       cwd,
       env,
       stdio: ["ignore", "pipe", "pipe"]
     });
   }
 }
-function tryPostPr5(prNumber, body, cwd) {
+function tryPostPr6(prNumber, body, cwd) {
   try {
     postPrReviewComment(prNumber, body, cwd);
   } catch {
@@ -5965,7 +6093,7 @@ var verify = async (ctx) => {
 };
 
 // src/scripts/waitForCi.ts
-import { execFileSync as execFileSync22 } from "child_process";
+import { execFileSync as execFileSync23 } from "child_process";
 var API_TIMEOUT_MS10 = 3e4;
 var waitForCi = async (ctx, _profile, _agentResult, args) => {
   const timeoutMinutes = numArg(args, "timeoutMinutes", 30);
@@ -5996,7 +6124,7 @@ var waitForCi = async (ctx, _profile, _agentResult, args) => {
     const summary = summarize(rows);
     if (summary !== lastSummary) {
       lastSummary = summary;
-      tryPostPr6(prNumber, `\u23F3 kody waitForCi: ${summary}`, ctx.cwd);
+      tryPostPr7(prNumber, `\u23F3 kody waitForCi: ${summary}`, ctx.cwd);
     }
     const failed = rows.filter((r) => r.bucket === "fail" || r.bucket === "cancel");
     const pending = rows.filter((r) => r.bucket === "pending");
@@ -6008,7 +6136,7 @@ var waitForCi = async (ctx, _profile, _agentResult, args) => {
           failedChecks: detail,
           prUrl
         });
-        tryPostPr6(
+        tryPostPr7(
           prNumber,
           `\u{1F6D1} kody waitForCi: giving up after ${fixCiAttempts} fix-ci attempts. Failed: ${detail}`,
           ctx.cwd
@@ -6020,7 +6148,7 @@ var waitForCi = async (ctx, _profile, _agentResult, args) => {
           maxAttempts: maxFixCiAttempts,
           prUrl
         });
-        tryPostPr6(
+        tryPostPr7(
           prNumber,
           `\u274C kody waitForCi: CI failed (attempt ${fixCiAttempts + 1}/${maxFixCiAttempts}). Dispatching fix-ci. Failed: ${detail}`,
           ctx.cwd
@@ -6030,7 +6158,7 @@ var waitForCi = async (ctx, _profile, _agentResult, args) => {
     }
     if (pending.length === 0) {
       ctx.data.action = mkAction("CI_PASSED", { checks: rows.length, prUrl });
-      tryPostPr6(prNumber, `\u2705 kody waitForCi: all ${rows.length} checks green on PR #${prNumber}`, ctx.cwd);
+      tryPostPr7(prNumber, `\u2705 kody waitForCi: all ${rows.length} checks green on PR #${prNumber}`, ctx.cwd);
       return;
     }
     await sleep(pollSeconds * 1e3);
@@ -6039,11 +6167,11 @@ var waitForCi = async (ctx, _profile, _agentResult, args) => {
     reason: `CI did not complete within ${timeoutMinutes} minutes`,
     prUrl
   });
-  tryPostPr6(prNumber, `\u231B kody waitForCi: timed out after ${timeoutMinutes} minutes`, ctx.cwd);
+  tryPostPr7(prNumber, `\u231B kody waitForCi: timed out after ${timeoutMinutes} minutes`, ctx.cwd);
 };
 function fetchChecks(prNumber, cwd) {
   try {
-    const raw = execFileSync22("gh", ["pr", "checks", String(prNumber), "--json", "bucket,state,name,workflow,link"], {
+    const raw = execFileSync23("gh", ["pr", "checks", String(prNumber), "--json", "bucket,state,name,workflow,link"], {
       encoding: "utf-8",
       timeout: API_TIMEOUT_MS10,
       cwd,
@@ -6079,7 +6207,7 @@ function numArg(args, key, fallback) {
   }
   return fallback;
 }
-function tryPostPr6(prNumber, body, cwd) {
+function tryPostPr7(prNumber, body, cwd) {
   try {
     postPrReviewComment(prNumber, body, cwd);
   } catch {
@@ -6252,6 +6380,7 @@ var preflightScripts = {
   fixFlow,
   fixCiFlow,
   resolveFlow,
+  revertFlow,
   reviewFlow,
   syncFlow,
   initFlow,
@@ -6312,7 +6441,8 @@ var postflightScripts = {
   notifyTerminal,
   recordOutcome,
   mergeReleasePr,
-  waitForCi
+  waitForCi,
+  markFlowSuccess
 };
 var allScriptNames = /* @__PURE__ */ new Set([
   ...Object.keys(preflightScripts),
@@ -6320,7 +6450,7 @@ var allScriptNames = /* @__PURE__ */ new Set([
 ]);
 
 // src/tools.ts
-import { execFileSync as execFileSync23 } from "child_process";
+import { execFileSync as execFileSync24 } from "child_process";
 function verifyCliTools(tools, cwd) {
   const out = [];
   for (const t of tools) out.push(verifyOne(t, cwd));
@@ -6353,7 +6483,7 @@ function verifyOne(tool, cwd) {
 }
 function runShell(cmd, cwd, timeoutMs = 3e4) {
   try {
-    execFileSync23("sh", ["-c", cmd], { cwd, stdio: "pipe", timeout: timeoutMs });
+    execFileSync24("sh", ["-c", cmd], { cwd, stdio: "pipe", timeout: timeoutMs });
     return true;
   } catch {
     return false;
@@ -6601,7 +6731,17 @@ function finish(out) {
 `);
   return out;
 }
-var SHELL_TIMEOUT_MS = 3e5;
+var DEFAULT_SHELL_TIMEOUT_MS = 3e5;
+function resolveShellTimeoutMs(entry) {
+  if (typeof entry.timeoutSec === "number" && entry.timeoutSec > 0) {
+    return Math.floor(entry.timeoutSec * 1e3);
+  }
+  const envSec = Number(process.env.KODY_SHELL_TIMEOUT_SEC);
+  if (Number.isFinite(envSec) && envSec > 0) {
+    return Math.floor(envSec * 1e3);
+  }
+  return DEFAULT_SHELL_TIMEOUT_MS;
+}
 function runShellEntry(entry, ctx, profile) {
   const shellName = entry.shell;
   const shellPath = path21.join(profile.dir, shellName);
@@ -6620,12 +6760,13 @@ function runShellEntry(entry, ctx, profile) {
   for (const [k, v] of flattenConfig(ctx.config)) {
     env[`KODY_CFG_${k}`] = v;
   }
+  const timeoutMs = resolveShellTimeoutMs(entry);
   const r = spawnSync("bash", [shellPath, ...positional], {
     cwd: ctx.cwd,
     encoding: "utf-8",
     env,
     stdio: ["pipe", "pipe", "pipe"],
-    timeout: SHELL_TIMEOUT_MS
+    timeout: timeoutMs
   });
   const stdout = r.stdout ?? "";
   const stderr = r.stderr ?? "";
@@ -6639,6 +6780,18 @@ function runShellEntry(entry, ctx, profile) {
   if (prUrlMatch?.[1]) ctx.output.prUrl = prUrlMatch[1].trim();
   const reasonMatch = stdout.match(/^KODY_REASON=(.+)$/m);
   if (reasonMatch?.[1]) ctx.output.reason = reasonMatch[1].trim();
+  const timedOut = r.status === null && r.signal !== null;
+  if (timedOut) {
+    ctx.skipAgent = true;
+    const seconds = Math.round(timeoutMs / 1e3);
+    if (ctx.output.exitCode === void 0 || ctx.output.exitCode === 0) {
+      ctx.output.exitCode = 124;
+    }
+    if (!ctx.output.reason) {
+      ctx.output.reason = `shell '${shellName}' timed out after ${seconds}s (signal=${r.signal})`;
+    }
+    return;
+  }
   const exit = r.status ?? -1;
   if (exit !== 0) {
     ctx.skipAgent = true;
@@ -6762,7 +6915,7 @@ function detectPackageManager2(cwd) {
 }
 function shellOut(cmd, args, cwd, stream = true) {
   try {
-    execFileSync24(cmd, args, {
+    execFileSync25(cmd, args, {
       cwd,
       stdio: stream ? "inherit" : "pipe",
       env: { ...process.env, HUSKY: "0", SKIP_HOOKS: "1", CI: process.env.CI ?? "1" }
@@ -6775,7 +6928,7 @@ function shellOut(cmd, args, cwd, stream = true) {
 }
 function isOnPath(bin) {
   try {
-    execFileSync24("which", [bin], { stdio: "pipe" });
+    execFileSync25("which", [bin], { stdio: "pipe" });
     return true;
   } catch {
     return false;
@@ -6809,7 +6962,7 @@ function installLitellmIfNeeded(cwd) {
   } catch {
   }
   try {
-    execFileSync24("python3", ["-c", "import litellm"], { stdio: "pipe" });
+    execFileSync25("python3", ["-c", "import litellm"], { stdio: "pipe" });
     process.stdout.write("\u2192 kody: litellm already installed\n");
     return 0;
   } catch {
@@ -6819,16 +6972,16 @@ function installLitellmIfNeeded(cwd) {
 }
 function configureGitIdentity(cwd) {
   try {
-    const name = execFileSync24("git", ["config", "user.name"], { cwd, stdio: "pipe", encoding: "utf-8" }).trim();
+    const name = execFileSync25("git", ["config", "user.name"], { cwd, stdio: "pipe", encoding: "utf-8" }).trim();
     if (name) return;
   } catch {
   }
   try {
-    execFileSync24("git", ["config", "user.name", "github-actions[bot]"], { cwd, stdio: "pipe" });
+    execFileSync25("git", ["config", "user.name", "github-actions[bot]"], { cwd, stdio: "pipe" });
   } catch {
   }
   try {
-    execFileSync24("git", ["config", "user.email", "41898282+github-actions[bot]@users.noreply.github.com"], {
+    execFileSync25("git", ["config", "user.email", "41898282+github-actions[bot]@users.noreply.github.com"], {
       cwd,
       stdio: "pipe"
     });
@@ -7099,9 +7252,9 @@ function commitChatFiles(cwd, sessionId, verbose) {
   if (paths.length === 0) return;
   const opts = { cwd, stdio: verbose ? "inherit" : "pipe" };
   try {
-    execFileSync25("git", ["add", ...paths], opts);
-    execFileSync25("git", ["commit", "--quiet", "-m", `chat: reply for ${sessionId}`], opts);
-    execFileSync25("git", ["push", "--quiet", "origin", "HEAD"], opts);
+    execFileSync26("git", ["add", ...paths], opts);
+    execFileSync26("git", ["commit", "--quiet", "-m", `chat: reply for ${sessionId}`], opts);
+    execFileSync26("git", ["push", "--quiet", "origin", "HEAD"], opts);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     process.stderr.write(`[kody:chat] commit/push skipped: ${msg}

package/dist/executables/revert/profile.json

@@ -0,0 +1,64 @@
+{
+  "name": "revert",
+  "role": "primitive",
+  "describe": "Revert one or more commits on an existing PR branch via `git revert`. No agent — fully mechanical.",
+  "inputs": [
+    {
+      "name": "pr",
+      "flag": "--pr",
+      "type": "int",
+      "required": true,
+      "describe": "GitHub PR number whose branch to revert commits on."
+    },
+    {
+      "name": "shas",
+      "flag": "--shas",
+      "type": "string",
+      "required": true,
+      "bindsCommentRest": true,
+      "describe": "One or more commit SHAs (whitespace-separated) to revert. Each must exist in the PR branch's history."
+    }
+  ],
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "acceptEdits",
+    "maxTurns": 0,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "tools": [],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [],
+  "scripts": {
+    "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody:reverting",
+          "color": "cccccc",
+          "description": "kody: reverting commits"
+        }
+      },
+      { "script": "revertFlow" },
+      { "shell": "revert.sh" }
+    ],
+    "postflight": [
+      { "script": "markFlowSuccess" },
+      { "script": "commitAndPush" },
+      { "script": "ensurePr" },
+      { "script": "postIssueComment" },
+      { "script": "writeRunSummary" }
+    ]
+  },
+  "output": {
+    "actionTypes": [
+      "REVERT_COMPLETED",
+      "REVERT_FAILED"
+    ]
+  }
+}

package/dist/executables/revert/revert.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+#
+# revert: stage `git revert` of one or more commits on the PR branch.
+#
+# Runs as a preflight shell entry after revertFlow has validated inputs and
+# checked out the branch. revertFlow:
+#   - Resolved every requested SHA to its full form and re-set
+#     ctx.args.shas to a whitespace-separated list (we read it via
+#     KODY_ARG_SHAS).
+#   - Set ctx.skipAgent=true and ctx.data.commitMessage already, so the
+#     agent never runs and commitAndPush will use that message.
+#
+# This script does only the staging — `--no-commit` so commitAndPush
+# (postflight) makes the actual commit. That keeps kody's invariant
+# intact (only commitAndPush commits) and means the message comes from
+# revertFlow, not from git's auto-generated revert subject.
+#
+# Exits:
+#   0   — staged successfully
+#   1+  — git revert failed (executor surfaces stderr; postflight bails)
+
+set -euo pipefail
+
+shas="${KODY_ARG_SHAS:-}"
+if [[ -z "$shas" ]]; then
+  echo "revert.sh: KODY_ARG_SHAS is empty (revertFlow should have set it)" >&2
+  exit 64
+fi
+
+# shellcheck disable=SC2086 # Intentional word-splitting on whitespace-separated SHAs.
+git revert --no-commit --no-edit $shas
+
+echo "revert.sh: staged revert of: $shas"

package/dist/executables/types.ts

@@ -185,6 +185,14 @@ export interface ScriptEntry {
    * dispatcher script can be reused with different `next` targets.
    */
   with?: Record<string, string | number | boolean>
+  /**
+   * Optional shell-script timeout in seconds. Only honored on `shell` entries.
+   * Falls back to `KODY_SHELL_TIMEOUT_SEC` env var, then the 300s default.
+   * Long-running shells (release publish, large repo verify) should declare
+   * a higher value rather than relying on the default and getting SIGKILLed
+   * with an opaque "exited -1".
+   */
+  timeoutSec?: number
 }
 
 export interface OutputContract {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine",
-  "version": "0.3.50",
+  "version": "0.3.52",
   "description": "kody — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   "license": "MIT",
   "type": "module",