@kody-ade/kody-engine 0.2.44 → 0.2.46

package/dist/bin/kody2.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.2.44",
+  version: "0.2.46",
   description: "kody2 \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 execFileSync16 } from "child_process";
+import { execFileSync as execFileSync20 } from "child_process";
 import * as fs19 from "fs";
 import * as path16 from "path";
 
@@ -528,7 +528,7 @@ async function emit(sink, type, sessionId, suffix, payload) {
 }
 
 // src/kody2-cli.ts
-import { execFileSync as execFileSync15 } from "child_process";
+import { execFileSync as execFileSync19 } from "child_process";
 import * as fs18 from "fs";
 import * as path15 from "path";
 
@@ -953,6 +953,248 @@ function parseScriptList(p, key, raw) {
   return out;
 }
 
+// src/scripts/advanceFlow.ts
+import { execFileSync as execFileSync3 } from "child_process";
+
+// src/state.ts
+import { execFileSync as execFileSync2 } from "child_process";
+var STATE_BEGIN = "<!-- kody2:state:v1:begin -->";
+var STATE_END = "<!-- kody2:state:v1:end -->";
+var HISTORY_MAX_ENTRIES = 20;
+var API_TIMEOUT_MS = 3e4;
+function emptyState() {
+  return {
+    schemaVersion: 1,
+    core: {
+      phase: "idle",
+      status: "pending",
+      currentExecutable: null,
+      lastOutcome: null,
+      attempts: {}
+    },
+    executables: {},
+    artifacts: {},
+    history: []
+  };
+}
+function ghToken() {
+  return process.env.GH_PAT?.trim() || process.env.GH_TOKEN;
+}
+function gh(args, input, cwd) {
+  const token = ghToken();
+  const env = token ? { ...process.env, GH_TOKEN: token } : { ...process.env };
+  return execFileSync2("gh", args, {
+    encoding: "utf-8",
+    timeout: API_TIMEOUT_MS,
+    cwd,
+    env,
+    input,
+    stdio: input ? ["pipe", "pipe", "pipe"] : ["ignore", "pipe", "pipe"]
+  }).trim();
+}
+function findStateComment(target, number, cwd) {
+  const apiPath = target === "issue" ? `repos/{owner}/{repo}/issues/${number}/comments` : `repos/{owner}/{repo}/issues/${number}/comments`;
+  try {
+    const raw = gh(["api", "--paginate", apiPath], void 0, cwd);
+    const list = JSON.parse(raw);
+    for (const c of list) {
+      if (c.body?.includes(STATE_BEGIN)) {
+        return { id: String(c.id), body: c.body };
+      }
+    }
+  } catch {
+  }
+  return null;
+}
+function parseStateComment(body) {
+  const beginIdx = body.indexOf(STATE_BEGIN);
+  const endIdx = body.indexOf(STATE_END, beginIdx + 1);
+  if (beginIdx < 0 || endIdx < 0) return emptyState();
+  const between = body.slice(beginIdx + STATE_BEGIN.length, endIdx).trim();
+  const OPEN = "```json";
+  const CLOSE = "```";
+  if (!between.startsWith(OPEN) || !between.endsWith(CLOSE)) return emptyState();
+  const jsonStr = between.slice(OPEN.length, between.length - CLOSE.length).trim();
+  try {
+    const parsed = JSON.parse(jsonStr);
+    if (parsed?.schemaVersion !== 1) return emptyState();
+    return {
+      schemaVersion: 1,
+      core: { ...emptyState().core, ...parsed.core },
+      executables: parsed.executables ?? {},
+      artifacts: parsed.artifacts && typeof parsed.artifacts === "object" ? parsed.artifacts : {},
+      history: Array.isArray(parsed.history) ? parsed.history : [],
+      flow: parsed.flow
+    };
+  } catch {
+    return emptyState();
+  }
+}
+function reduce(state, executable, action) {
+  if (!action) return state;
+  const newAttempts = { ...state.core.attempts, [executable]: (state.core.attempts[executable] ?? 0) + 1 };
+  const newExecutables = {
+    ...state.executables,
+    [executable]: { ...state.executables[executable] ?? { lastAction: null }, lastAction: action }
+  };
+  const newHistory = [
+    ...state.history,
+    { timestamp: action.timestamp, executable, action: action.type, note: noteFromAction(action) }
+  ].slice(-HISTORY_MAX_ENTRIES);
+  return {
+    schemaVersion: 1,
+    core: {
+      ...state.core,
+      attempts: newAttempts,
+      lastOutcome: action,
+      currentExecutable: executable,
+      status: statusFromAction(action),
+      phase: phaseFromAction(executable, action)
+    },
+    executables: newExecutables,
+    artifacts: { ...state.artifacts ?? {} },
+    history: newHistory,
+    flow: state.flow
+  };
+}
+function statusFromAction(action) {
+  if (/FAILED$|ERROR$|MISSING$|REJECTED$/i.test(action.type)) return "failed";
+  if (/COMPLETED$|SHIPPED$|MERGED$|SUCCESS$/i.test(action.type)) return "succeeded";
+  return "running";
+}
+function phaseFromAction(executable, action) {
+  if (/FAILED$|ERROR$|REJECTED$/i.test(action.type)) return "failed";
+  if (executable === "build") return statusFromAction(action) === "succeeded" ? "implementing" : "implementing";
+  if (executable === "review") return "reviewing";
+  if (executable === "release") return "shipped";
+  return "idle";
+}
+function noteFromAction(action) {
+  const p = action.payload;
+  if (typeof p?.prUrl === "string") return p.prUrl;
+  if (typeof p?.reason === "string") return p.reason.slice(0, 120);
+  if (typeof p?.commitMessage === "string") return p.commitMessage.slice(0, 120);
+  return void 0;
+}
+function renderStateComment(state) {
+  const lines = [];
+  lines.push(STATE_BEGIN);
+  lines.push("");
+  lines.push("```json");
+  lines.push(
+    JSON.stringify(
+      {
+        schemaVersion: state.schemaVersion,
+        core: state.core,
+        artifacts: state.artifacts ?? {},
+        executables: state.executables,
+        history: state.history,
+        ...state.flow ? { flow: state.flow } : {}
+      },
+      null,
+      2
+    )
+  );
+  lines.push("```");
+  lines.push("");
+  lines.push(STATE_END);
+  lines.push("");
+  lines.push("## kody2 task state");
+  lines.push("");
+  lines.push(`- **Phase:** \`${state.core.phase}\`  **Status:** \`${state.core.status}\``);
+  if (state.core.currentExecutable) {
+    lines.push(`- **Last executable:** \`${state.core.currentExecutable}\``);
+  }
+  if (state.core.lastOutcome) {
+    lines.push(`- **Last action:** \`${state.core.lastOutcome.type}\``);
+  }
+  const attempts = Object.entries(state.core.attempts).map(([k, v]) => `${k}:${v}`).join(", ");
+  if (attempts) lines.push(`- **Attempts:** ${attempts}`);
+  if (state.core.prUrl) lines.push(`- **PR:** ${state.core.prUrl}`);
+  if (state.core.runUrl) lines.push(`- **Run:** ${state.core.runUrl}`);
+  const artifactNames = Object.keys(state.artifacts ?? {});
+  if (artifactNames.length > 0) {
+    lines.push(`- **Artifacts:** ${artifactNames.map((n) => `\`${n}\``).join(", ")}`);
+  }
+  lines.push("");
+  if (state.history.length > 0) {
+    lines.push("### Recent history");
+    lines.push("");
+    const recent = state.history.slice(-10).reverse();
+    for (const h of recent) {
+      const note = h.note ? ` \u2014 ${h.note}` : "";
+      lines.push(`- \`${h.timestamp}\` **${h.executable}** \u2192 \`${h.action}\`${note}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function readTaskState(target, number, cwd) {
+  const existing = findStateComment(target, number, cwd);
+  return existing ? parseStateComment(existing.body) : emptyState();
+}
+function setArtifact(state, name, artifact) {
+  return {
+    ...state,
+    artifacts: { ...state.artifacts ?? {}, [name]: artifact }
+  };
+}
+function writeTaskState(target, number, state, cwd) {
+  const body = renderStateComment(state);
+  const existing = findStateComment(target, number, cwd);
+  try {
+    if (existing) {
+      gh(["api", `repos/{owner}/{repo}/issues/comments/${existing.id}`, "-X", "PATCH", "-F", "body=@-"], body, cwd);
+    } else {
+      const sub = target === "issue" ? "issue" : "pr";
+      gh([sub, "comment", String(number), "--body-file", "-"], body, cwd);
+    }
+  } catch (err) {
+    process.stderr.write(
+      `[kody2 state] failed to write state on ${target} #${number}: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+  }
+}
+
+// src/scripts/advanceFlow.ts
+var API_TIMEOUT_MS2 = 3e4;
+var advanceFlow = async (ctx, profile) => {
+  const state = ctx.data.taskState;
+  const flow = state?.flow;
+  if (!flow?.issueNumber) return;
+  const targetType = ctx.data.commentTargetType;
+  const action = ctx.data.action;
+  if (targetType === "pr" && action) {
+    try {
+      const issueState = readTaskState("issue", flow.issueNumber, ctx.cwd);
+      issueState.flow = flow;
+      const next = reduce(issueState, profile.name, action);
+      if (state?.core.prUrl && !next.core.prUrl) next.core.prUrl = state.core.prUrl;
+      next.flow = flow;
+      writeTaskState("issue", flow.issueNumber, next, ctx.cwd);
+    } catch (err) {
+      process.stderr.write(
+        `[kody2 advanceFlow] failed to mirror action to issue #${flow.issueNumber}: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+    }
+  }
+  const body = `@kody2 orchestrate --flow ${flow.name}`;
+  try {
+    execFileSync3("gh", ["issue", "comment", String(flow.issueNumber), "--body", body], {
+      timeout: API_TIMEOUT_MS2,
+      cwd: ctx.cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } catch (err) {
+    process.stderr.write(
+      `[kody2 advanceFlow] failed to re-trigger orchestrator on issue #${flow.issueNumber}: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+  }
+};
+
 // src/scripts/buildSyntheticPlugin.ts
 import * as fs8 from "fs";
 import * as os2 from "os";
@@ -1047,7 +1289,7 @@ function copyDir(src, dst) {
 }
 
 // src/coverage.ts
-import { execFileSync as execFileSync2 } from "child_process";
+import { execFileSync as execFileSync4 } from "child_process";
 function patternToRegex(pattern) {
   let s = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
   s = s.replace(/\*\*\//g, "\xA7S").replace(/\*\*/g, "\xA7A").replace(/\*/g, "[^/]*");
@@ -1065,7 +1307,7 @@ function renderSiblingPath(file, requireSibling) {
 }
 function safeGit(args, cwd) {
   try {
-    return execFileSync2("git", args, { encoding: "utf-8", cwd, env: { ...process.env, HUSKY: "0" } }).trim();
+    return execFileSync4("git", args, { encoding: "utf-8", cwd, env: { ...process.env, HUSKY: "0" } }).trim();
   } catch {
     return "";
   }
@@ -1236,10 +1478,10 @@ ${formatMissesForFeedback(misses)}`;
 };
 
 // src/scripts/commitAndPush.ts
-import { execFileSync as execFileSync4 } from "child_process";
+import { execFileSync as execFileSync6 } from "child_process";
 
 // src/commit.ts
-import { execFileSync as execFileSync3 } from "child_process";
+import { execFileSync as execFileSync5 } from "child_process";
 import * as fs10 from "fs";
 import * as path9 from "path";
 var FORBIDDEN_PATH_PREFIXES = [
@@ -1269,7 +1511,7 @@ var CONVENTIONAL_PREFIXES = [
 ];
 function git(args, cwd) {
   try {
-    return execFileSync3("git", args, {
+    return execFileSync5("git", args, {
       encoding: "utf-8",
       timeout: 12e4,
       cwd,
@@ -1327,7 +1569,7 @@ function isForbiddenPath(p) {
   return false;
 }
 function listChangedFiles(cwd) {
-  const raw = execFileSync3("git", ["status", "--porcelain=v1", "-z"], {
+  const raw = execFileSync5("git", ["status", "--porcelain=v1", "-z"], {
     encoding: "utf-8",
     cwd,
     env: { ...process.env, HUSKY: "0", SKIP_HOOKS: "1" },
@@ -1339,7 +1581,7 @@ function listChangedFiles(cwd) {
 }
 function listFilesInCommit(ref = "HEAD", cwd) {
   try {
-    const raw = execFileSync3("git", ["show", "--name-only", "--pretty=format:", "-z", ref], {
+    const raw = execFileSync5("git", ["show", "--name-only", "--pretty=format:", "-z", ref], {
       encoding: "utf-8",
       cwd,
       env: { ...process.env, HUSKY: "0", SKIP_HOOKS: "1" },
@@ -1419,7 +1661,7 @@ var commitAndPush2 = async (ctx, profile) => {
   const kind = profile.name;
   if (kind === "resolve") {
     try {
-      execFileSync4("git", ["add", "-A"], { cwd: ctx.cwd, env: { ...process.env, HUSKY: "0" }, stdio: "pipe" });
+      execFileSync6("git", ["add", "-A"], { cwd: ctx.cwd, env: { ...process.env, HUSKY: "0" }, stdio: "pipe" });
     } catch {
     }
   } else {
@@ -1555,18 +1797,61 @@ function formatToolsUsage(profile) {
   return lines.join("\n");
 }
 
+// src/scripts/dispatch.ts
+import { execFileSync as execFileSync7 } from "child_process";
+var API_TIMEOUT_MS3 = 3e4;
+var dispatch = async (ctx, _profile, _agentResult, args) => {
+  const next = args?.next;
+  if (!next) {
+    process.stderr.write("[kody2 dispatch] missing `with.next` \u2014 skipping\n");
+    return;
+  }
+  const target = args?.target ?? "issue";
+  const issueNumber = ctx.args.issue;
+  if (!issueNumber) {
+    process.stderr.write("[kody2 dispatch] no --issue arg \u2014 skipping\n");
+    return;
+  }
+  const state = ctx.data.taskState;
+  if (state?.flow) {
+    state.flow.step = next;
+  }
+  const usePr = target === "pr" && state?.core.prUrl;
+  const targetNumber = usePr ? parsePr(state.core.prUrl) ?? issueNumber : issueNumber;
+  const sub = usePr ? "pr" : "issue";
+  const body = `@kody2 ${next}`;
+  try {
+    execFileSync7("gh", [sub, "comment", String(targetNumber), "--body", body], {
+      timeout: API_TIMEOUT_MS3,
+      cwd: ctx.cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } catch (err) {
+    process.stderr.write(
+      `[kody2 dispatch] failed to post @kody2 ${next} on ${sub} #${targetNumber}: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+  }
+};
+function parsePr(url) {
+  const m = url.match(/\/pull\/(\d+)(?:[/?#]|$)/);
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  return Number.isFinite(n) ? n : null;
+}
+
 // src/issue.ts
-import { execFileSync as execFileSync5 } from "child_process";
-var API_TIMEOUT_MS = 3e4;
-function ghToken() {
+import { execFileSync as execFileSync8 } from "child_process";
+var API_TIMEOUT_MS4 = 3e4;
+function ghToken2() {
   return process.env.GH_PAT?.trim() || process.env.GH_TOKEN;
 }
-function gh(args, options) {
-  const token = ghToken();
+function gh2(args, options) {
+  const token = ghToken2();
   const env = token ? { ...process.env, GH_TOKEN: token } : { ...process.env };
-  return execFileSync5("gh", args, {
+  return execFileSync8("gh", args, {
     encoding: "utf-8",
-    timeout: API_TIMEOUT_MS,
+    timeout: API_TIMEOUT_MS4,
     cwd: options?.cwd,
     env,
     input: options?.input,
@@ -1574,7 +1859,7 @@ function gh(args, options) {
   }).trim();
 }
 function getIssue(issueNumber, cwd) {
-  const output = gh(["issue", "view", String(issueNumber), "--json", "number,title,body,comments"], { cwd });
+  const output = gh2(["issue", "view", String(issueNumber), "--json", "number,title,body,comments"], { cwd });
   const parsed = JSON.parse(output);
   if (typeof parsed?.title !== "string") {
     throw new Error(`Issue #${issueNumber}: unexpected response shape`);
@@ -1592,7 +1877,7 @@ function getIssue(issueNumber, cwd) {
 }
 function postIssueComment(issueNumber, body, cwd) {
   try {
-    gh(["issue", "comment", String(issueNumber), "--body-file", "-"], { input: body, cwd });
+    gh2(["issue", "comment", String(issueNumber), "--body-file", "-"], { input: body, cwd });
   } catch (err) {
     process.stderr.write(
       `[kody2] failed to post comment on #${issueNumber}: ${err instanceof Error ? err.message : String(err)}
@@ -1605,7 +1890,7 @@ function truncate2(s, maxBytes) {
   return `${s.slice(0, maxBytes)}\u2026 (+${s.length - maxBytes} chars)`;
 }
 function getPr(prNumber, cwd) {
-  const output = gh(["pr", "view", String(prNumber), "--json", "number,title,body,headRefName,baseRefName,state"], {
+  const output = gh2(["pr", "view", String(prNumber), "--json", "number,title,body,headRefName,baseRefName,state"], {
     cwd
   });
   const parsed = JSON.parse(output);
@@ -1623,7 +1908,7 @@ function getPr(prNumber, cwd) {
 }
 function getPrDiff(prNumber, cwd) {
   try {
-    return gh(["pr", "diff", String(prNumber)], { cwd });
+    return gh2(["pr", "diff", String(prNumber)], { cwd });
   } catch (err) {
     process.stderr.write(
       `[kody2] failed to fetch diff for PR #${prNumber}: ${err instanceof Error ? err.message : String(err)}
@@ -1634,7 +1919,7 @@ function getPrDiff(prNumber, cwd) {
 }
 function getPrReviews(prNumber, cwd) {
   try {
-    const output = gh(["pr", "view", String(prNumber), "--json", "reviews"], { cwd });
+    const output = gh2(["pr", "view", String(prNumber), "--json", "reviews"], { cwd });
     const parsed = JSON.parse(output);
     if (!Array.isArray(parsed?.reviews)) return [];
     return parsed.reviews.map(
@@ -1651,7 +1936,7 @@ function getPrReviews(prNumber, cwd) {
 }
 function getPrComments(prNumber, cwd) {
   try {
-    const output = gh(["pr", "view", String(prNumber), "--json", "comments"], { cwd });
+    const output = gh2(["pr", "view", String(prNumber), "--json", "comments"], { cwd });
     const parsed = JSON.parse(output);
     if (!Array.isArray(parsed?.comments)) return [];
     return parsed.comments.map((c) => ({
@@ -1677,7 +1962,7 @@ function getPrLatestReviewBody(prNumber, cwd) {
 }
 function postPrReviewComment(prNumber, body, cwd) {
   try {
-    gh(["pr", "comment", String(prNumber), "--body-file", "-"], { input: body, cwd });
+    gh2(["pr", "comment", String(prNumber), "--body-file", "-"], { input: body, cwd });
   } catch (err) {
     process.stderr.write(
       `[kody2] failed to post review comment on PR #${prNumber}: ${err instanceof Error ? err.message : String(err)}
@@ -1754,7 +2039,7 @@ function firstLine(s) {
 }
 function findExistingPr(branch, cwd) {
   try {
-    const output = gh(["pr", "view", branch, "--json", "number,url"], { cwd });
+    const output = gh2(["pr", "view", branch, "--json", "number,url"], { cwd });
     const parsed = JSON.parse(output);
     if (typeof parsed?.number === "number" && typeof parsed?.url === "string") {
       return { number: parsed.number, url: parsed.url };
@@ -1770,7 +2055,7 @@ function ensurePr(opts) {
   const existing = findExistingPr(opts.branch, opts.cwd);
   if (existing) {
     try {
-      gh(["pr", "edit", String(existing.number), "--body-file", "-"], { input: body, cwd: opts.cwd });
+      gh2(["pr", "edit", String(existing.number), "--body-file", "-"], { input: body, cwd: opts.cwd });
     } catch (err) {
       process.stderr.write(
         `[kody2] failed to update PR #${existing.number}: ${err instanceof Error ? err.message : String(err)}
@@ -1792,7 +2077,7 @@ function ensurePr(opts) {
     "-"
   ];
   if (opts.draft) args.push("--draft");
-  const output = gh(args, { input: body, cwd: opts.cwd });
+  const output = gh2(args, { input: body, cwd: opts.cwd });
   const url = output.trim();
   const match = url.match(/\/pull\/(\d+)$/);
   const number = match ? parseInt(match[1], 10) : 0;
@@ -1850,8 +2135,43 @@ function computeFailureReason(ctx) {
   return "";
 }
 
+// src/scripts/finishFlow.ts
+import { execFileSync as execFileSync9 } from "child_process";
+var API_TIMEOUT_MS5 = 3e4;
+var STATUS_ICON = {
+  "review-passed": "\u2705",
+  "fix-applied": "\u2705",
+  "review-failed": "\u26A0\uFE0F",
+  aborted: "\u26A0\uFE0F"
+};
+var finishFlow = async (ctx, _profile, _agentResult, args) => {
+  const reason = args?.reason ?? "completed";
+  const issueNumber = ctx.args.issue;
+  const state = ctx.data.taskState;
+  const flowName = state?.flow?.name ?? "(unknown flow)";
+  if (state) state.flow = void 0;
+  if (!issueNumber) return;
+  const icon = STATUS_ICON[reason] ?? "\u2139\uFE0F";
+  const prSuffix = state?.core.prUrl ? `
+
+**PR:** ${state.core.prUrl}` : "";
+  const body = `${icon} kody2 flow \`${flowName}\` finished \u2014 \`${reason}\`${prSuffix}`;
+  try {
+    execFileSync9("gh", ["issue", "comment", String(issueNumber), "--body", body], {
+      timeout: API_TIMEOUT_MS5,
+      cwd: ctx.cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } catch (err) {
+    process.stderr.write(
+      `[kody2 finishFlow] failed to post final summary on issue #${issueNumber}: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+  }
+};
+
 // src/branch.ts
-import { execFileSync as execFileSync6 } from "child_process";
+import { execFileSync as execFileSync10 } from "child_process";
 var UncommittedChangesError = class extends Error {
   constructor(branch) {
     super(`Uncommitted changes on branch '${branch}' \u2014 refusing to run to protect work in progress`);
@@ -1861,7 +2181,7 @@ var UncommittedChangesError = class extends Error {
   branch;
 };
 function git2(args, cwd) {
-  return execFileSync6("git", args, {
+  return execFileSync10("git", args, {
     encoding: "utf-8",
     timeout: 3e4,
     cwd,
@@ -1886,7 +2206,7 @@ function checkoutPrBranch(prNumber, cwd) {
     SKIP_HOOKS: "1",
     GH_TOKEN: process.env.GH_PAT?.trim() || process.env.GH_TOKEN || ""
   };
-  execFileSync6("gh", ["pr", "checkout", String(prNumber)], {
+  execFileSync10("gh", ["pr", "checkout", String(prNumber)], {
     cwd,
     env,
     stdio: ["ignore", "pipe", "pipe"],
@@ -1953,7 +2273,7 @@ function ensureFeatureBranch(issueNumber, title, defaultBranch, cwd) {
 }
 
 // src/gha.ts
-import { execFileSync as execFileSync7 } from "child_process";
+import { execFileSync as execFileSync11 } from "child_process";
 import * as fs12 from "fs";
 function getRunUrl() {
   const server = process.env.GITHUB_SERVER_URL;
@@ -1977,7 +2297,7 @@ function reactToTriggerComment(cwd) {
   if (!commentId || !repo) return;
   const token = process.env.KODY_TOKEN?.trim() || process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
   try {
-    execFileSync7(
+    execFileSync11(
       "gh",
       [
         "api",
@@ -2001,15 +2321,15 @@ function reactToTriggerComment(cwd) {
 }
 
 // src/workflow.ts
-import { execFileSync as execFileSync8 } from "child_process";
+import { execFileSync as execFileSync12 } from "child_process";
 var GH_TIMEOUT_MS = 3e4;
-function ghToken2() {
+function ghToken3() {
   return process.env.GH_PAT?.trim() || process.env.GH_TOKEN;
 }
-function gh2(args, cwd) {
-  const token = ghToken2();
+function gh3(args, cwd) {
+  const token = ghToken3();
   const env = token ? { ...process.env, GH_TOKEN: token } : { ...process.env };
-  return execFileSync8("gh", args, {
+  return execFileSync12("gh", args, {
     encoding: "utf-8",
     timeout: GH_TIMEOUT_MS,
     cwd,
@@ -2020,14 +2340,14 @@ function gh2(args, cwd) {
 function getRecentFailedRunsForPr(prNumber, limit, cwd) {
   let headBranch;
   try {
-    const out = gh2(["pr", "view", String(prNumber), "--json", "headRefName"], cwd);
+    const out = gh3(["pr", "view", String(prNumber), "--json", "headRefName"], cwd);
     headBranch = JSON.parse(out).headRefName;
   } catch {
     return [];
   }
   if (!headBranch) return [];
   try {
-    const out = gh2(
+    const out = gh3(
       [
         "run",
         "list",
@@ -2058,7 +2378,7 @@ function getRecentFailedRunsForPr(prNumber, limit, cwd) {
 }
 function getFailedRunLogTail(runId, maxBytes, cwd) {
   try {
-    const raw = gh2(["run", "view", String(runId), "--log-failed"], cwd);
+    const raw = gh3(["run", "view", String(runId), "--log-failed"], cwd);
     if (raw.length <= maxBytes) return raw;
     return raw.slice(-maxBytes);
   } catch {
@@ -2193,7 +2513,7 @@ function tryPostPr2(prNumber, body, cwd) {
 }
 
 // src/scripts/initFlow.ts
-import { execFileSync as execFileSync9 } from "child_process";
+import { execFileSync as execFileSync13 } from "child_process";
 import * as fs14 from "fs";
 import * as path12 from "path";
 
@@ -2275,7 +2595,7 @@ function qualityCommandsFor(pm) {
 function detectOwnerRepo(cwd) {
   let url;
   try {
-    url = execFileSync9("git", ["remote", "get-url", "origin"], {
+    url = execFileSync13("git", ["remote", "get-url", "origin"], {
       cwd,
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "pipe"]
@@ -2359,7 +2679,7 @@ jobs:
 `;
 function defaultBranchFromGit(cwd) {
   try {
-    const ref = execFileSync9("git", ["symbolic-ref", "refs/remotes/origin/HEAD"], {
+    const ref = execFileSync13("git", ["symbolic-ref", "refs/remotes/origin/HEAD"], {
       cwd,
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "pipe"]
@@ -2367,7 +2687,7 @@ function defaultBranchFromGit(cwd) {
     return ref.replace("refs/remotes/origin/", "");
   } catch {
     try {
-      return execFileSync9("git", ["branch", "--show-current"], {
+      return execFileSync13("git", ["branch", "--show-current"], {
         cwd,
         encoding: "utf-8",
         stdio: ["ignore", "pipe", "pipe"]
@@ -2507,214 +2827,48 @@ var loadIssueContext = async (ctx) => {
   ctx.data.commentTargetNumber = issueNumber;
 };
 
-// src/state.ts
-import { execFileSync as execFileSync10 } from "child_process";
-var STATE_BEGIN = "<!-- kody2:state:v1:begin -->";
-var STATE_END = "<!-- kody2:state:v1:end -->";
-var HISTORY_MAX_ENTRIES = 20;
-var API_TIMEOUT_MS2 = 3e4;
-function emptyState() {
-  return {
-    schemaVersion: 1,
-    core: {
-      phase: "idle",
-      status: "pending",
-      currentExecutable: null,
-      lastOutcome: null,
-      attempts: {}
-    },
-    executables: {},
-    artifacts: {},
-    history: []
-  };
-}
-function ghToken3() {
-  return process.env.GH_PAT?.trim() || process.env.GH_TOKEN;
-}
-function gh3(args, input, cwd) {
-  const token = ghToken3();
-  const env = token ? { ...process.env, GH_TOKEN: token } : { ...process.env };
-  return execFileSync10("gh", args, {
-    encoding: "utf-8",
-    timeout: API_TIMEOUT_MS2,
-    cwd,
-    env,
-    input,
-    stdio: input ? ["pipe", "pipe", "pipe"] : ["ignore", "pipe", "pipe"]
-  }).trim();
-}
-function findStateComment(target, number, cwd) {
-  const apiPath = target === "issue" ? `repos/{owner}/{repo}/issues/${number}/comments` : `repos/{owner}/{repo}/issues/${number}/comments`;
-  try {
-    const raw = gh3(["api", "--paginate", apiPath], void 0, cwd);
-    const list = JSON.parse(raw);
-    for (const c of list) {
-      if (c.body?.includes(STATE_BEGIN)) {
-        return { id: String(c.id), body: c.body };
-      }
-    }
-  } catch {
+// src/scripts/loadTaskState.ts
+var loadTaskState = async (ctx) => {
+  const target = ctx.data.commentTargetType;
+  const number = ctx.data.commentTargetNumber;
+  if (!target || !number) {
+    ctx.data.taskState = emptyState();
+    return;
   }
-  return null;
-}
-function parseStateComment(body) {
-  const beginIdx = body.indexOf(STATE_BEGIN);
-  const endIdx = body.indexOf(STATE_END, beginIdx + 1);
-  if (beginIdx < 0 || endIdx < 0) return emptyState();
-  const between = body.slice(beginIdx + STATE_BEGIN.length, endIdx).trim();
-  const OPEN = "```json";
-  const CLOSE = "```";
-  if (!between.startsWith(OPEN) || !between.endsWith(CLOSE)) return emptyState();
-  const jsonStr = between.slice(OPEN.length, between.length - CLOSE.length).trim();
+  ctx.data.taskState = readTaskState(target, number, ctx.cwd);
+};
+
+// src/scripts/mirrorStateToPr.ts
+var mirrorStateToPr = async (ctx) => {
+  const issueNumber = ctx.data.commentTargetNumber;
+  const issueTarget = ctx.data.commentTargetType;
+  if (!issueNumber || issueTarget !== "issue") return;
+  const prUrl = ctx.output.prUrl ?? ctx.data.prResult?.url;
+  if (!prUrl) return;
+  const prNumber = parsePrNumber(prUrl);
+  if (!prNumber) return;
+  let state;
   try {
-    const parsed = JSON.parse(jsonStr);
-    if (parsed?.schemaVersion !== 1) return emptyState();
-    return {
-      schemaVersion: 1,
-      core: { ...emptyState().core, ...parsed.core },
-      executables: parsed.executables ?? {},
-      artifacts: parsed.artifacts && typeof parsed.artifacts === "object" ? parsed.artifacts : {},
-      history: Array.isArray(parsed.history) ? parsed.history : []
-    };
+    state = readTaskState("issue", issueNumber, ctx.cwd);
   } catch {
-    return emptyState();
-  }
-}
-function reduce(state, executable, action) {
-  if (!action) return state;
-  const newAttempts = { ...state.core.attempts, [executable]: (state.core.attempts[executable] ?? 0) + 1 };
-  const newExecutables = {
-    ...state.executables,
-    [executable]: { ...state.executables[executable] ?? { lastAction: null }, lastAction: action }
-  };
-  const newHistory = [
-    ...state.history,
-    { timestamp: action.timestamp, executable, action: action.type, note: noteFromAction(action) }
-  ].slice(-HISTORY_MAX_ENTRIES);
-  return {
-    schemaVersion: 1,
-    core: {
-      ...state.core,
-      attempts: newAttempts,
-      lastOutcome: action,
-      currentExecutable: executable,
-      status: statusFromAction(action),
-      phase: phaseFromAction(executable, action)
-    },
-    executables: newExecutables,
-    artifacts: { ...state.artifacts ?? {} },
-    history: newHistory
-  };
-}
-function statusFromAction(action) {
-  if (/FAILED$|ERROR$|MISSING$|REJECTED$/i.test(action.type)) return "failed";
-  if (/COMPLETED$|SHIPPED$|MERGED$|SUCCESS$/i.test(action.type)) return "succeeded";
-  return "running";
-}
-function phaseFromAction(executable, action) {
-  if (/FAILED$|ERROR$|REJECTED$/i.test(action.type)) return "failed";
-  if (executable === "build") return statusFromAction(action) === "succeeded" ? "implementing" : "implementing";
-  if (executable === "review") return "reviewing";
-  if (executable === "release") return "shipped";
-  return "idle";
-}
-function noteFromAction(action) {
-  const p = action.payload;
-  if (typeof p?.prUrl === "string") return p.prUrl;
-  if (typeof p?.reason === "string") return p.reason.slice(0, 120);
-  if (typeof p?.commitMessage === "string") return p.commitMessage.slice(0, 120);
-  return void 0;
-}
-function renderStateComment(state) {
-  const lines = [];
-  lines.push(STATE_BEGIN);
-  lines.push("");
-  lines.push("```json");
-  lines.push(
-    JSON.stringify(
-      {
-        schemaVersion: state.schemaVersion,
-        core: state.core,
-        artifacts: state.artifacts ?? {},
-        executables: state.executables,
-        history: state.history
-      },
-      null,
-      2
-    )
-  );
-  lines.push("```");
-  lines.push("");
-  lines.push(STATE_END);
-  lines.push("");
-  lines.push("## kody2 task state");
-  lines.push("");
-  lines.push(`- **Phase:** \`${state.core.phase}\`  **Status:** \`${state.core.status}\``);
-  if (state.core.currentExecutable) {
-    lines.push(`- **Last executable:** \`${state.core.currentExecutable}\``);
-  }
-  if (state.core.lastOutcome) {
-    lines.push(`- **Last action:** \`${state.core.lastOutcome.type}\``);
-  }
-  const attempts = Object.entries(state.core.attempts).map(([k, v]) => `${k}:${v}`).join(", ");
-  if (attempts) lines.push(`- **Attempts:** ${attempts}`);
-  if (state.core.prUrl) lines.push(`- **PR:** ${state.core.prUrl}`);
-  if (state.core.runUrl) lines.push(`- **Run:** ${state.core.runUrl}`);
-  const artifactNames = Object.keys(state.artifacts ?? {});
-  if (artifactNames.length > 0) {
-    lines.push(`- **Artifacts:** ${artifactNames.map((n) => `\`${n}\``).join(", ")}`);
-  }
-  lines.push("");
-  if (state.history.length > 0) {
-    lines.push("### Recent history");
-    lines.push("");
-    const recent = state.history.slice(-10).reverse();
-    for (const h of recent) {
-      const note = h.note ? ` \u2014 ${h.note}` : "";
-      lines.push(`- \`${h.timestamp}\` **${h.executable}** \u2192 \`${h.action}\`${note}`);
-    }
-    lines.push("");
+    return;
   }
-  return lines.join("\n");
-}
-function readTaskState(target, number, cwd) {
-  const existing = findStateComment(target, number, cwd);
-  return existing ? parseStateComment(existing.body) : emptyState();
-}
-function setArtifact(state, name, artifact) {
-  return {
-    ...state,
-    artifacts: { ...state.artifacts ?? {}, [name]: artifact }
-  };
-}
-function writeTaskState(target, number, state, cwd) {
-  const body = renderStateComment(state);
-  const existing = findStateComment(target, number, cwd);
+  if (prUrl && !state.core.prUrl) state.core.prUrl = prUrl;
   try {
-    if (existing) {
-      gh3(["api", `repos/{owner}/{repo}/issues/comments/${existing.id}`, "-X", "PATCH", "-F", "body=@-"], body, cwd);
-    } else {
-      const sub = target === "issue" ? "issue" : "pr";
-      gh3([sub, "comment", String(number), "--body-file", "-"], body, cwd);
-    }
+    writeTaskState("pr", prNumber, state, ctx.cwd);
   } catch (err) {
     process.stderr.write(
-      `[kody2 state] failed to write state on ${target} #${number}: ${err instanceof Error ? err.message : String(err)}
+      `[kody2 mirrorStateToPr] failed to mirror state to PR #${prNumber}: ${err instanceof Error ? err.message : String(err)}
 `
     );
   }
-}
-
-// src/scripts/loadTaskState.ts
-var loadTaskState = async (ctx) => {
-  const target = ctx.data.commentTargetType;
-  const number = ctx.data.commentTargetNumber;
-  if (!target || !number) {
-    ctx.data.taskState = emptyState();
-    return;
-  }
-  ctx.data.taskState = readTaskState(target, number, ctx.cwd);
 };
+function parsePrNumber(prUrl) {
+  const m = prUrl.match(/\/pull\/(\d+)(?:[/?#]|$)/);
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  return Number.isFinite(n) ? n : null;
+}
 
 // src/scripts/parseAgentResult.ts
 var parseAgentResult2 = async (ctx, profile, agentResult) => {
@@ -2938,7 +3092,7 @@ REVIEW_POSTED=https://github.com/${ctx.config.github.owner}/${ctx.config.github.
 };
 
 // src/scripts/releaseFlow.ts
-import { execFileSync as execFileSync11, spawnSync } from "child_process";
+import { execFileSync as execFileSync14, spawnSync } from "child_process";
 import * as fs15 from "fs";
 import * as path13 from "path";
 function bumpVersion(current, bump) {
@@ -2968,7 +3122,7 @@ function generateChangelog(cwd, newVersion, lastTag) {
   const range = lastTag ? `${lastTag}..HEAD` : "HEAD";
   let log = "";
   try {
-    log = execFileSync11("git", ["log", range, "--pretty=format:%s||%h", "--no-merges"], {
+    log = execFileSync14("git", ["log", range, "--pretty=format:%s||%h", "--no-merges"], {
       cwd,
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "pipe"]
@@ -3025,7 +3179,7 @@ ${entry}${prior.slice(idx + 1)}`);
   }
 }
 function git3(args, cwd, timeout = 6e4) {
-  return execFileSync11("git", args, {
+  return execFileSync14("git", args, {
     encoding: "utf-8",
     timeout,
     cwd,
@@ -3132,7 +3286,7 @@ ${entry}
 Merge this and then run \`kody2 release --mode finalize\`.`;
   let prUrl = "";
   try {
-    prUrl = gh(["pr", "create", "--head", releaseBranch, "--base", base, "--title", title, "--body-file", "-"], {
+    prUrl = gh2(["pr", "create", "--head", releaseBranch, "--base", base, "--title", title, "--body-file", "-"], {
       input: body,
       cwd
     }).trim();
@@ -3209,7 +3363,7 @@ ${truncate2(r.stderr, 2e3)}
   try {
     const releaseArgs = ["release", "create", tag, "--title", tag, "--notes", `Release ${tag} \u2014 automated by kody2.`];
     if (releaseCfg.draftRelease) releaseArgs.push("--draft");
-    releaseUrl = gh(releaseArgs, { cwd }).trim();
+    releaseUrl = gh2(releaseArgs, { cwd }).trim();
   } catch (err) {
     process.stderr.write(
       `[kody2 release] gh release create failed: ${err instanceof Error ? err.message : String(err)}
@@ -3328,7 +3482,7 @@ var resolveArtifacts = async (ctx, profile) => {
 };
 
 // src/scripts/resolveFlow.ts
-import { execFileSync as execFileSync12 } from "child_process";
+import { execFileSync as execFileSync15 } from "child_process";
 var CONFLICT_DIFF_MAX_BYTES = 4e4;
 var resolveFlow = async (ctx) => {
   const prNumber = ctx.args.pr;
@@ -3380,7 +3534,7 @@ var resolveFlow = async (ctx) => {
 };
 function getConflictedFiles(cwd) {
   try {
-    const out = execFileSync12("git", ["diff", "--name-only", "--diff-filter=U"], {
+    const out = execFileSync15("git", ["diff", "--name-only", "--diff-filter=U"], {
       encoding: "utf-8",
       cwd,
       env: { ...process.env, HUSKY: "0" }
@@ -3395,7 +3549,7 @@ function getConflictMarkersPreview(files, cwd, maxBytes = CONFLICT_DIFF_MAX_BYTE
   let total = 0;
   for (const f of files) {
     try {
-      const content = execFileSync12("cat", [f], { encoding: "utf-8", cwd }).toString();
+      const content = execFileSync15("cat", [f], { encoding: "utf-8", cwd }).toString();
       const snippet = `### ${f}
 
 \`\`\`
@@ -3504,8 +3658,67 @@ function synthesizeAction(ctx) {
   };
 }
 
+// src/scripts/skipAgent.ts
+var skipAgent = async (ctx) => {
+  ctx.skipAgent = true;
+};
+
+// src/scripts/startFlow.ts
+import { execFileSync as execFileSync16 } from "child_process";
+var API_TIMEOUT_MS6 = 3e4;
+var startFlow = async (ctx, _profile, _agentResult, args) => {
+  const entry = args?.entry;
+  if (!entry) {
+    process.stderr.write("[kody2 startFlow] missing `with.entry` \u2014 skipping\n");
+    return;
+  }
+  const target = args?.target ?? "issue";
+  const flowName = ctx.args.flow ?? "default";
+  const issueNumber = ctx.args.issue;
+  if (!issueNumber) {
+    process.stderr.write("[kody2 startFlow] no --issue arg \u2014 skipping\n");
+    return;
+  }
+  const state = ctx.data.taskState;
+  if (state?.flow) {
+    return;
+  }
+  if (state) {
+    state.flow = {
+      name: flowName,
+      step: entry,
+      issueNumber,
+      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  postKody2Comment(target, issueNumber, state, entry, ctx.cwd);
+};
+function postKody2Comment(target, issueNumber, state, next, cwd) {
+  const targetNumber = target === "pr" && state?.core.prUrl ? parsePr2(state.core.prUrl) ?? issueNumber : issueNumber;
+  const sub = target === "pr" && state?.core.prUrl ? "pr" : "issue";
+  const body = `@kody2 ${next}`;
+  try {
+    execFileSync16("gh", [sub, "comment", String(targetNumber), "--body", body], {
+      timeout: API_TIMEOUT_MS6,
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } catch (err) {
+    process.stderr.write(
+      `[kody2 startFlow] failed to post @kody2 ${next} on ${sub} #${targetNumber}: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+  }
+}
+function parsePr2(url) {
+  const m = url.match(/\/pull\/(\d+)(?:[/?#]|$)/);
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  return Number.isFinite(n) ? n : null;
+}
+
 // src/scripts/syncFlow.ts
-import { execFileSync as execFileSync13 } from "child_process";
+import { execFileSync as execFileSync17 } from "child_process";
 var syncFlow = async (ctx) => {
   ctx.skipAgent = true;
   const prNumber = ctx.args.pr;
@@ -3564,7 +3777,7 @@ function bail2(ctx, prNumber, reason) {
 }
 function revParseHead(cwd) {
   try {
-    return execFileSync13("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).toString().trim();
+    return execFileSync17("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).toString().trim();
   } catch {
     return "";
   }
@@ -3572,9 +3785,9 @@ function revParseHead(cwd) {
 function pushBranch(branch, cwd) {
   const env = { ...process.env, HUSKY: "0", SKIP_HOOKS: "1" };
   try {
-    execFileSync13("git", ["push", "-u", "origin", branch], { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    execFileSync17("git", ["push", "-u", "origin", branch], { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
   } catch {
-    execFileSync13("git", ["push", "--force-with-lease", "-u", "origin", branch], {
+    execFileSync17("git", ["push", "--force-with-lease", "-u", "origin", branch], {
       cwd,
       env,
       stdio: ["ignore", "pipe", "pipe"]
@@ -3685,7 +3898,7 @@ function readWatchConfig(ctx) {
 function findStalePrs(cwd, staleDays, now = /* @__PURE__ */ new Date()) {
   let raw = "";
   try {
-    raw = gh(["pr", "list", "--state", "open", "--limit", "100", "--json", "number,title,url,updatedAt"], { cwd });
+    raw = gh2(["pr", "list", "--state", "open", "--limit", "100", "--json", "number,title,url,updatedAt"], { cwd });
   } catch {
     return [];
   }
@@ -3787,7 +4000,8 @@ var preflightScripts = {
   loadCoverageRules,
   buildSyntheticPlugin,
   resolveArtifacts,
-  composePrompt
+  composePrompt,
+  skipAgent
 };
 var postflightScripts = {
   parseAgentResult: parseAgentResult2,
@@ -3803,7 +4017,12 @@ var postflightScripts = {
   postReviewResult,
   persistArtifacts,
   writeRunSummary,
-  saveTaskState
+  saveTaskState,
+  mirrorStateToPr,
+  startFlow,
+  dispatch,
+  finishFlow,
+  advanceFlow
 };
 var allScriptNames = /* @__PURE__ */ new Set([
   ...Object.keys(preflightScripts),
@@ -3811,7 +4030,7 @@ var allScriptNames = /* @__PURE__ */ new Set([
 ]);
 
 // src/tools.ts
-import { execFileSync as execFileSync14 } from "child_process";
+import { execFileSync as execFileSync18 } from "child_process";
 function verifyCliTools(tools, cwd) {
   const out = [];
   for (const t of tools) out.push(verifyOne(t, cwd));
@@ -3844,7 +4063,7 @@ function verifyOne(tool, cwd) {
 }
 function runShell2(cmd, cwd, timeoutMs = 3e4) {
   try {
-    execFileSync14("sh", ["-c", cmd], { cwd, stdio: "pipe", timeout: timeoutMs });
+    execFileSync18("sh", ["-c", cmd], { cwd, stdio: "pipe", timeout: timeoutMs });
     return true;
   } catch {
     return false;
@@ -3941,7 +4160,7 @@ async function runExecutable(profileName, input) {
       if (!shouldRun(entry, ctx)) continue;
       const fn = preflightScripts[entry.script];
       if (!fn) return finish({ exitCode: 99, reason: `preflight script not registered: ${entry.script}` });
-      await fn(ctx, profile);
+      await fn(ctx, profile, entry.with);
       if (ctx.skipAgent && ctx.output.exitCode !== void 0 && ctx.output.exitCode !== 0) {
         return finish(ctx.output);
       }
@@ -3959,7 +4178,7 @@ async function runExecutable(profileName, input) {
       const fn = postflightScripts[entry.script];
       if (!fn) return finish({ exitCode: 99, reason: `postflight script not registered: ${entry.script}` });
       try {
-        await fn(ctx, profile, agentResult);
+        await fn(ctx, profile, agentResult, entry.with);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         process.stderr.write(`[kody2] postflight script "${entry.script}" crashed: ${msg}
@@ -4174,7 +4393,7 @@ function detectPackageManager2(cwd) {
 }
 function shellOut(cmd, args, cwd, stream = true) {
   try {
-    execFileSync15(cmd, args, {
+    execFileSync19(cmd, args, {
       cwd,
       stdio: stream ? "inherit" : "pipe",
       env: { ...process.env, HUSKY: "0", SKIP_HOOKS: "1", CI: process.env.CI ?? "1" }
@@ -4187,7 +4406,7 @@ function shellOut(cmd, args, cwd, stream = true) {
 }
 function isOnPath(bin) {
   try {
-    execFileSync15("which", [bin], { stdio: "pipe" });
+    execFileSync19("which", [bin], { stdio: "pipe" });
     return true;
   } catch {
     return false;
@@ -4221,7 +4440,7 @@ function installLitellmIfNeeded(cwd) {
   } catch {
   }
   try {
-    execFileSync15("python3", ["-c", "import litellm"], { stdio: "pipe" });
+    execFileSync19("python3", ["-c", "import litellm"], { stdio: "pipe" });
     process.stdout.write("\u2192 kody2: litellm already installed\n");
     return 0;
   } catch {
@@ -4231,16 +4450,16 @@ function installLitellmIfNeeded(cwd) {
 }
 function configureGitIdentity(cwd) {
   try {
-    const name = execFileSync15("git", ["config", "user.name"], { cwd, stdio: "pipe", encoding: "utf-8" }).trim();
+    const name = execFileSync19("git", ["config", "user.name"], { cwd, stdio: "pipe", encoding: "utf-8" }).trim();
     if (name) return;
   } catch {
   }
   try {
-    execFileSync15("git", ["config", "user.name", "github-actions[bot]"], { cwd, stdio: "pipe" });
+    execFileSync19("git", ["config", "user.name", "github-actions[bot]"], { cwd, stdio: "pipe" });
   } catch {
   }
   try {
-    execFileSync15("git", ["config", "user.email", "41898282+github-actions[bot]@users.noreply.github.com"], {
+    execFileSync19("git", ["config", "user.email", "41898282+github-actions[bot]@users.noreply.github.com"], {
       cwd,
       stdio: "pipe"
     });
@@ -4296,13 +4515,13 @@ async function runCi(argv) {
 ${CI_HELP}`);
     return 64;
   }
-  const dispatch = autoFallback ?? {
+  const dispatch2 = autoFallback ?? {
     executable: "run",
     cliArgs: { issue: args.issueNumber },
     target: args.issueNumber
   };
-  const issueNumber = dispatch.target;
-  process.stdout.write(`\u2192 kody2 preflight (cwd=${cwd}, executable=${dispatch.executable}, target=${issueNumber})
+  const issueNumber = dispatch2.target;
+  process.stdout.write(`\u2192 kody2 preflight (cwd=${cwd}, executable=${dispatch2.executable}, target=${issueNumber})
 `);
   try {
     const n = unpackAllSecrets();
@@ -4339,13 +4558,13 @@ ${CI_HELP}`);
     postFailureTail(issueNumber, cwd, `preflight crashed: ${msg}`);
     return 99;
   }
-  process.stdout.write(`\u2192 kody2: preflight done, handing off to kody2 ${dispatch.executable}
+  process.stdout.write(`\u2192 kody2: preflight done, handing off to kody2 ${dispatch2.executable}
 
 `);
   try {
     const config = earlyConfig ?? loadConfig(cwd);
-    const result = await runExecutable(dispatch.executable, {
-      cliArgs: dispatch.cliArgs,
+    const result = await runExecutable(dispatch2.executable, {
+      cliArgs: dispatch2.cliArgs,
       cwd,
       config,
       verbose: args.verbose,
@@ -4417,9 +4636,9 @@ function commitChatFiles(cwd, sessionId, verbose) {
   if (paths.length === 0) return;
   const opts = { cwd, stdio: verbose ? "inherit" : "pipe" };
   try {
-    execFileSync16("git", ["add", ...paths], opts);
-    execFileSync16("git", ["commit", "--quiet", "-m", `chat: reply for ${sessionId}`], opts);
-    execFileSync16("git", ["push", "--quiet", "origin", "HEAD"], opts);
+    execFileSync20("git", ["add", ...paths], opts);
+    execFileSync20("git", ["commit", "--quiet", "-m", `chat: reply for ${sessionId}`], opts);
+    execFileSync20("git", ["push", "--quiet", "origin", "HEAD"], opts);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     process.stderr.write(`[kody2:chat] commit/push skipped: ${msg}

package/dist/executables/fix/profile.json

@@ -83,6 +83,9 @@
       },
       {
         "script": "saveTaskState"
+      },
+      {
+        "script": "advanceFlow"
       }
     ]
   },

package/dist/executables/plan/profile.json

@@ -59,6 +59,9 @@
       },
       {
         "script": "saveTaskState"
+      },
+      {
+        "script": "advanceFlow"
       }
     ]
   },

package/dist/executables/review/profile.json

@@ -50,6 +50,9 @@
       },
       {
         "script": "saveTaskState"
+      },
+      {
+        "script": "advanceFlow"
       }
     ]
   }

package/dist/executables/run/profile.json

@@ -79,6 +79,12 @@
       },
       {
         "script": "saveTaskState"
+      },
+      {
+        "script": "mirrorStateToPr"
+      },
+      {
+        "script": "advanceFlow"
       }
     ]
   },

package/dist/executables/types.ts

@@ -140,6 +140,12 @@ export interface ScriptEntry {
    * The script runs only when every key matches. Missing `runWhen` = always.
    */
   runWhen?: Record<string, string | number | boolean | Array<string | number | boolean>>
+  /**
+   * Optional per-call arguments passed to the script as the last positional
+   * parameter. Used by the orchestrator's transition table so the same
+   * dispatcher script can be reused with different `next` targets.
+   */
+  with?: Record<string, string | number | boolean>
 }
 
 export interface OutputContract {
@@ -183,9 +189,16 @@ export interface Context {
 // Script signatures. Two phases, two contracts.
 // ────────────────────────────────────────────────────────────────────────────
 
-export type PreflightScript = (ctx: Context, profile: Profile) => Promise<void>
+export type ScriptArgs = Record<string, string | number | boolean>
+
+export type PreflightScript = (ctx: Context, profile: Profile, args?: ScriptArgs) => Promise<void>
 
-export type PostflightScript = (ctx: Context, profile: Profile, agentResult: AgentResult | null) => Promise<void>
+export type PostflightScript = (
+  ctx: Context,
+  profile: Profile,
+  agentResult: AgentResult | null,
+  args?: ScriptArgs,
+) => Promise<void>
 
 /** A registered script may be either phase; registry looks it up by name. */
 export type AnyScript = PreflightScript | PostflightScript

package/package.json

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