@kody-ade/kody-engine 0.4.10 → 0.4.13

package/dist/bin/kody.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.4.10",
+  version: "0.4.13",
   description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -388,7 +388,15 @@ async function runAgent(opts) {
     ...process.env,
     SKIP_HOOKS: "1",
     HUSKY: "0",
-    CI: process.env.CI ?? "1"
+    CI: process.env.CI ?? "1",
+    // MCP servers are spawned asynchronously by the SDK. With the default
+    // non-blocking behavior, the SDK announces its tool list at session
+    // init while servers are still in `pending`, so their tools never
+    // reach the model. Block until each MCP completes its handshake (or
+    // the timeout below elapses) so the tool list is complete on first
+    // turn.
+    MCP_CONNECTION_NONBLOCKING: process.env.MCP_CONNECTION_NONBLOCKING ?? "false",
+    MCP_TIMEOUT: process.env.MCP_TIMEOUT ?? "60000"
   };
   if (opts.litellmUrl) {
     env.ANTHROPIC_BASE_URL = opts.litellmUrl;
@@ -1253,7 +1261,7 @@ function coerceBare(spec, value) {
 }
 
 // src/executor.ts
-import { execFileSync as execFileSync27, spawn as spawn4 } from "child_process";
+import { execFileSync as execFileSync27, spawn as spawn5 } from "child_process";
 import * as fs26 from "fs";
 import * as path23 from "path";
 
@@ -3904,10 +3912,14 @@ function ensurePr(opts) {
   const title = buildPrTitle(effectiveOpts.issueNumber, effectiveOpts.issueTitle, effectiveOpts.draft);
   const body = buildPrBody(effectiveOpts);
   if (existing) {
+    const stripped = existing.url.replace(/^https:\/\/github\.com\//, "");
+    const [owner, repo] = stripped.split("/");
     try {
-      gh2(["pr", "edit", String(existing.number), "--body-file", "-"], { input: body, cwd: opts.cwd });
+      gh2(["api", "--method", "PATCH", `repos/${owner}/${repo}/pulls/${existing.number}`, "-f", `body=${body}`], {
+        cwd: opts.cwd
+      });
     } catch (err) {
-      throw new Error(`gh pr edit #${existing.number} failed: ${err instanceof Error ? err.message : String(err)}`);
+      throw new Error(`gh api PATCH #${existing.number} failed: ${err instanceof Error ? err.message : String(err)}`);
     }
     return { url: existing.url, number: existing.number, draft: opts.draft, action: "updated" };
   }
@@ -3966,15 +3978,19 @@ var ensureMemorizePr = async (ctx) => {
   const body = buildBody(ctx, branch, datestamp);
   const existing = findExistingPr(branch, ctx.cwd);
   if (existing) {
+    const stripped = existing.url.replace(/^https:\/\/github\.com\//, "");
+    const [owner, repo] = stripped.split("/");
     try {
-      gh2(["pr", "edit", String(existing.number), "--body-file", "-"], { input: body, cwd: ctx.cwd });
+      gh2(["api", "--method", "PATCH", `repos/${owner}/${repo}/pulls/${existing.number}`, "-f", `body=${body}`], {
+        cwd: ctx.cwd
+      });
       ctx.output.prUrl = existing.url;
       ctx.data.prResult = { url: existing.url, number: existing.number, action: "updated" };
       process.stdout.write(`[kody memorize] updated PR ${existing.url}
 `);
     } catch (err) {
       ctx.output.exitCode = 4;
-      ctx.output.reason = `gh pr edit #${existing.number} failed: ${err instanceof Error ? err.message : String(err)}`;
+      ctx.output.reason = `gh api PATCH #${existing.number} failed: ${err instanceof Error ? err.message : String(err)}`;
     }
     return;
   }
@@ -4347,15 +4363,54 @@ function ensureFeatureBranch(issueNumber, title, defaultBranch, cwd, baseBranch)
     git2(["fetch", "origin"], cwd);
   } catch {
   }
+  let originBranchExists = false;
   try {
     git2(["rev-parse", "--verify", `origin/${branchName}`], cwd);
+    originBranchExists = true;
+  } catch {
+  }
+  if (originBranchExists && baseBranch && baseBranch !== defaultBranch) {
+    let baseExists = false;
+    try {
+      git2(["rev-parse", "--verify", `origin/${baseBranch}`], cwd);
+      baseExists = true;
+    } catch {
+    }
+    if (baseExists) {
+      let descendsFromBase = false;
+      try {
+        git2(["merge-base", "--is-ancestor", `origin/${baseBranch}`, `origin/${branchName}`], cwd);
+        descendsFromBase = true;
+      } catch {
+      }
+      if (!descendsFromBase) {
+        process.stderr.write(
+          `[kody branch] origin/${branchName} does not descend from origin/${baseBranch} \u2014 recreating from base
+`
+        );
+        try {
+          git2(["push", "origin", "--delete", branchName], cwd);
+        } catch {
+        }
+        try {
+          git2(["update-ref", "-d", `refs/remotes/origin/${branchName}`], cwd);
+        } catch {
+        }
+        try {
+          git2(["branch", "-D", branchName], cwd);
+        } catch {
+        }
+        originBranchExists = false;
+      }
+    }
+  }
+  if (originBranchExists) {
     git2(["checkout", branchName], cwd);
     try {
       git2(["pull", "origin", branchName], cwd);
     } catch {
     }
     return { branch: branchName, created: false };
-  } catch {
   }
   try {
     git2(["rev-parse", "--verify", branchName], cwd);
@@ -5571,6 +5626,171 @@ function composeBody({ label, exit, prUrl, reason, dryRun }) {
   return `\u2705 kody ${label} complete`;
 }
 
+// src/scripts/postReviewResult.ts
+function detectVerdict(body) {
+  const m = body.match(/##\s*Verdict\s*:\s*(PASS|CONCERNS|FAIL)\b/i);
+  if (!m) return "UNKNOWN";
+  return m[1].toUpperCase();
+}
+function reviewAction(verdict, payload) {
+  const type = verdict === "PASS" ? "REVIEW_PASS" : verdict === "CONCERNS" ? "REVIEW_CONCERNS" : verdict === "FAIL" ? "REVIEW_FAIL" : "REVIEW_COMPLETED";
+  return { type, payload: { verdict, ...payload }, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+}
+function failedAction2(reason) {
+  return { type: "REVIEW_FAILED", payload: { reason }, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+}
+var postReviewResult = async (ctx, _profile, agentResult) => {
+  const prNumber = ctx.data.commentTargetNumber;
+  if (!prNumber) {
+    ctx.output.exitCode = 99;
+    ctx.output.reason = "review postflight: no PR number in context";
+    ctx.data.action = failedAction2(ctx.output.reason);
+    return;
+  }
+  if (!agentResult || agentResult.outcome !== "completed") {
+    const reason = agentResult?.error ?? "agent did not complete";
+    try {
+      postPrReviewComment(prNumber, `\u26A0\uFE0F kody review FAILED: ${truncate2(reason, 1e3)}`, ctx.cwd);
+    } catch {
+    }
+    ctx.output.exitCode = 1;
+    ctx.output.reason = reason;
+    ctx.data.action = failedAction2(reason);
+    return;
+  }
+  const reviewBody = agentResult.finalText.trim();
+  if (!reviewBody) {
+    try {
+      postPrReviewComment(prNumber, `\u26A0\uFE0F kody review FAILED: agent produced no review body`, ctx.cwd);
+    } catch {
+    }
+    ctx.output.exitCode = 1;
+    ctx.output.reason = "empty review body";
+    ctx.data.action = failedAction2("empty review body");
+    return;
+  }
+  try {
+    postPrReviewComment(prNumber, reviewBody, ctx.cwd);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.output.exitCode = 4;
+    ctx.output.reason = `failed to post review comment: ${msg}`;
+    ctx.data.action = failedAction2(ctx.output.reason);
+    return;
+  }
+  const verdict = detectVerdict(reviewBody);
+  ctx.data.reviewVerdict = verdict;
+  ctx.data.reviewBody = reviewBody;
+  ctx.data.action = reviewAction(verdict, { bodyPreview: truncate2(reviewBody, 500) });
+  ctx.output.exitCode = verdict === "FAIL" ? 1 : 0;
+  process.stdout.write(
+    `
+REVIEW_POSTED=https://github.com/${ctx.config.github.owner}/${ctx.config.github.repo}/pull/${prNumber} (verdict: ${verdict})
+`
+  );
+};
+
+// src/scripts/openQaIssue.ts
+var QA_LABEL = "kody:qa-report";
+function qaAction(verdict, payload) {
+  const type = verdict === "PASS" ? "QA_PASS" : verdict === "CONCERNS" ? "QA_CONCERNS" : verdict === "FAIL" ? "QA_FAIL" : "QA_COMPLETED";
+  return { type, payload: { verdict, ...payload }, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+}
+function failedAction3(reason) {
+  return { type: "QA_FAILED", payload: { reason }, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+}
+function slugifyScope(scope) {
+  return scope.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60);
+}
+function buildIssueTitle(scope, verdict) {
+  const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const focus = scope?.trim() ? scope.trim() : "smoke";
+  const verdictTag = verdict === "UNKNOWN" ? "REPORT" : verdict;
+  return `QA [${verdictTag}]: ${focus} \u2014 ${date}`.slice(0, 240);
+}
+function ensureLabel(cwd) {
+  try {
+    gh2(["label", "create", QA_LABEL, "--color", "8b5cf6", "--description", "kody: QA report", "--force"], { cwd });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function createQaIssue(title, body, hasLabel, cwd) {
+  const args = ["issue", "create", "--title", title, "--body-file", "-"];
+  if (hasLabel) args.push("--label", QA_LABEL);
+  const out = gh2(args, { input: body, cwd });
+  const url = out.split("\n").map((l) => l.trim()).filter(Boolean).pop() ?? "";
+  const m = url.match(/\/issues\/(\d+)\b/);
+  if (!m) throw new Error(`gh issue create returned unexpected output: ${out}`);
+  return { number: Number(m[1]), url };
+}
+var openQaIssue = async (ctx, _profile, agentResult) => {
+  if (!agentResult || agentResult.outcome !== "completed") {
+    const reason = agentResult?.error ?? "agent did not complete";
+    process.stderr.write(`qa-engineer: ${reason}
+`);
+    ctx.output.exitCode = 1;
+    ctx.output.reason = reason;
+    ctx.data.action = failedAction3(reason);
+    return;
+  }
+  const reportBody = agentResult.finalText.trim();
+  if (!reportBody) {
+    process.stderr.write("qa-engineer: agent produced no report body\n");
+    ctx.output.exitCode = 1;
+    ctx.output.reason = "empty report body";
+    ctx.data.action = failedAction3("empty report body");
+    return;
+  }
+  const verdict = detectVerdict(reportBody);
+  ctx.data.qaVerdict = verdict;
+  ctx.data.qaReport = reportBody;
+  const existingIssue = ctx.args.issue;
+  if (typeof existingIssue === "number" && Number.isFinite(existingIssue) && existingIssue > 0) {
+    try {
+      postIssueComment(existingIssue, reportBody, ctx.cwd);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      ctx.output.exitCode = 4;
+      ctx.output.reason = `failed to comment on issue #${existingIssue}: ${msg}`;
+      ctx.data.action = failedAction3(ctx.output.reason);
+      return;
+    }
+    process.stdout.write(
+      `
+QA_REPORT_POSTED=https://github.com/${ctx.config.github.owner}/${ctx.config.github.repo}/issues/${existingIssue} (verdict: ${verdict})
+`
+    );
+    ctx.data.action = qaAction(verdict, { issueNumber: existingIssue, mode: "comment" });
+    ctx.output.exitCode = verdict === "FAIL" ? 1 : 0;
+    return;
+  }
+  const scope = ctx.args.scope;
+  const title = buildIssueTitle(scope, verdict);
+  const hasLabel = ensureLabel(ctx.cwd);
+  let created;
+  try {
+    created = createQaIssue(title, reportBody, hasLabel, ctx.cwd);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.output.exitCode = 4;
+    ctx.output.reason = `failed to open QA issue: ${truncate2(msg, 1e3)}`;
+    ctx.data.action = failedAction3(ctx.output.reason);
+    return;
+  }
+  process.stdout.write(`
+QA_REPORT_POSTED=${created.url} (verdict: ${verdict})
+`);
+  ctx.data.action = qaAction(verdict, {
+    issueNumber: created.number,
+    issueUrl: created.url,
+    titleSlug: scope ? slugifyScope(scope) : "smoke",
+    mode: "create"
+  });
+  ctx.output.exitCode = verdict === "FAIL" ? 1 : 0;
+};
+
 // src/scripts/parseAgentResult.ts
 var parseAgentResult2 = async (ctx, profile, agentResult) => {
   if (!agentResult) {
@@ -5945,70 +6165,6 @@ function renderResearchComment(issueNumber, body) {
 ${body}`;
 }
 
-// src/scripts/postReviewResult.ts
-function detectVerdict(body) {
-  const m = body.match(/##\s*Verdict\s*:\s*(PASS|CONCERNS|FAIL)\b/i);
-  if (!m) return "UNKNOWN";
-  return m[1].toUpperCase();
-}
-function reviewAction(verdict, payload) {
-  const type = verdict === "PASS" ? "REVIEW_PASS" : verdict === "CONCERNS" ? "REVIEW_CONCERNS" : verdict === "FAIL" ? "REVIEW_FAIL" : "REVIEW_COMPLETED";
-  return { type, payload: { verdict, ...payload }, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
-}
-function failedAction2(reason) {
-  return { type: "REVIEW_FAILED", payload: { reason }, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
-}
-var postReviewResult = async (ctx, _profile, agentResult) => {
-  const prNumber = ctx.data.commentTargetNumber;
-  if (!prNumber) {
-    ctx.output.exitCode = 99;
-    ctx.output.reason = "review postflight: no PR number in context";
-    ctx.data.action = failedAction2(ctx.output.reason);
-    return;
-  }
-  if (!agentResult || agentResult.outcome !== "completed") {
-    const reason = agentResult?.error ?? "agent did not complete";
-    try {
-      postPrReviewComment(prNumber, `\u26A0\uFE0F kody review FAILED: ${truncate2(reason, 1e3)}`, ctx.cwd);
-    } catch {
-    }
-    ctx.output.exitCode = 1;
-    ctx.output.reason = reason;
-    ctx.data.action = failedAction2(reason);
-    return;
-  }
-  const reviewBody = agentResult.finalText.trim();
-  if (!reviewBody) {
-    try {
-      postPrReviewComment(prNumber, `\u26A0\uFE0F kody review FAILED: agent produced no review body`, ctx.cwd);
-    } catch {
-    }
-    ctx.output.exitCode = 1;
-    ctx.output.reason = "empty review body";
-    ctx.data.action = failedAction2("empty review body");
-    return;
-  }
-  try {
-    postPrReviewComment(prNumber, reviewBody, ctx.cwd);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    ctx.output.exitCode = 4;
-    ctx.output.reason = `failed to post review comment: ${msg}`;
-    ctx.data.action = failedAction2(ctx.output.reason);
-    return;
-  }
-  const verdict = detectVerdict(reviewBody);
-  ctx.data.reviewVerdict = verdict;
-  ctx.data.reviewBody = reviewBody;
-  ctx.data.action = reviewAction(verdict, { bodyPreview: truncate2(reviewBody, 500) });
-  ctx.output.exitCode = verdict === "FAIL" ? 1 : 0;
-  process.stdout.write(
-    `
-REVIEW_POSTED=https://github.com/${ctx.config.github.owner}/${ctx.config.github.repo}/pull/${prNumber} (verdict: ${verdict})
-`
-  );
-};
-
 // src/scripts/recordClassification.ts
 import { execFileSync as execFileSync19 } from "child_process";
 var API_TIMEOUT_MS8 = 3e4;
@@ -6028,7 +6184,7 @@ var recordClassification = async (ctx) => {
     reason = parsed?.reason ?? null;
   }
   if (!classification) {
-    ctx.data.action = failedAction3("classification missing or invalid");
+    ctx.data.action = failedAction4("classification missing or invalid");
     tryAuditComment(
       issueNumber,
       "\u26A0\uFE0F kody classifier could not decide \u2014 please re-run with an explicit `@kody <type>`.",
@@ -6069,7 +6225,7 @@ function tryAuditComment(issueNumber, body, cwd) {
 function makeAction3(type, payload) {
   return { type, payload, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
 }
-function failedAction3(reason) {
+function failedAction4(reason) {
   return { type: "CLASSIFY_FAILED", payload: { reason }, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
 }
 
@@ -6108,12 +6264,12 @@ function fail(ctx, profile, reason) {
   ctx.data.agentDone = false;
   ctx.data.agentFailureReason = reason;
   const modeSeg = profile.name.replace(/-/g, "_").toUpperCase();
-  const failedAction4 = {
+  const failedAction5 = {
     type: `${modeSeg}_FAILED`,
     payload: { reason },
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   };
-  ctx.data.action = failedAction4;
+  ctx.data.action = failedAction5;
 }
 function countActionItems(block) {
   if (!block.trim()) return 0;
@@ -6154,12 +6310,12 @@ function fail2(ctx, profile, reason) {
   ctx.data.agentDone = false;
   ctx.data.agentFailureReason = reason;
   const modeSeg = profile.name.replace(/-/g, "_").toUpperCase();
-  const failedAction4 = {
+  const failedAction5 = {
     type: `${modeSeg}_FAILED`,
     payload: { reason },
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   };
-  ctx.data.action = failedAction4;
+  ctx.data.action = failedAction5;
 }
 
 // src/scripts/resolveArtifacts.ts
@@ -7137,6 +7293,151 @@ function sleep2(ms) {
   return new Promise((res) => setTimeout(res, ms));
 }
 
+// src/scripts/warmupMcp.ts
+import { spawn as spawn4 } from "child_process";
+var PER_SERVER_TIMEOUT_MS = 6e4;
+var PER_REQUEST_TIMEOUT_MS = 2e4;
+var warmupMcp = async (_ctx, profile) => {
+  const servers = profile.claudeCode.mcpServers ?? [];
+  if (servers.length === 0) return;
+  for (const s of servers) {
+    const start = Date.now();
+    try {
+      const result = await warmupOne(s.command, s.args ?? [], s.env);
+      const ms = Date.now() - start;
+      process.stderr.write(`[kody warmup] ${s.name}: ${result.toolCount} tools (${ms}ms)
+`);
+    } catch (err) {
+      const ms = Date.now() - start;
+      const reason = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`[kody warmup] ${s.name} FAILED after ${ms}ms: ${reason}
+`);
+    }
+  }
+};
+async function warmupOne(command, args, env) {
+  const child = spawn4(command, args, {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: env ? { ...process.env, ...env } : process.env
+  });
+  let stderrBuf = "";
+  child.stderr.on("data", (b) => {
+    stderrBuf += b.toString("utf8");
+    if (stderrBuf.length > 4096) stderrBuf = stderrBuf.slice(-4096);
+  });
+  const overallDeadline = Date.now() + PER_SERVER_TIMEOUT_MS;
+  const lines = lineStream(child.stdout);
+  let nextId = 1;
+  const send = (method, params) => {
+    const id = nextId++;
+    const payload = JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n";
+    child.stdin.write(payload);
+    return id;
+  };
+  const notify = (method, params) => {
+    const payload = JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n";
+    child.stdin.write(payload);
+  };
+  const awaitResponse = async (id) => {
+    const reqDeadline = Math.min(Date.now() + PER_REQUEST_TIMEOUT_MS, overallDeadline);
+    while (Date.now() < reqDeadline) {
+      const line = await lines.next(reqDeadline - Date.now());
+      if (line === null) break;
+      let msg = null;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (msg && msg.id === id) return msg;
+    }
+    throw new Error(`request id=${id} timed out (stderr tail: ${stderrBuf.trim().slice(-300) || "(empty)"})`);
+  };
+  try {
+    const initId = send("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: "kody-warmup", version: "0.1.0" }
+    });
+    const initResp = await awaitResponse(initId);
+    if (initResp.error) throw new Error(`initialize error: ${initResp.error.message}`);
+    notify("notifications/initialized");
+    const listId = send("tools/list");
+    const listResp = await awaitResponse(listId);
+    if (listResp.error) throw new Error(`tools/list error: ${listResp.error.message}`);
+    const tools = listResp.result?.tools;
+    const toolCount = Array.isArray(tools) ? tools.length : 0;
+    if (toolCount === 0) throw new Error("tools/list returned 0 tools");
+    return { toolCount };
+  } finally {
+    try {
+      child.kill("SIGTERM");
+    } catch {
+    }
+    setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+      }
+    }, 2e3).unref();
+  }
+}
+function lineStream(stream) {
+  let buf = "";
+  const queue = [];
+  let waiter = null;
+  let ended = false;
+  const tryDeliver = () => {
+    if (waiter && queue.length > 0) {
+      const w = waiter;
+      waiter = null;
+      w(queue.shift());
+    } else if (waiter && ended) {
+      const w = waiter;
+      waiter = null;
+      w(null);
+    }
+  };
+  stream.on("data", (chunk) => {
+    buf += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    let idx;
+    while ((idx = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, idx).replace(/\r$/, "");
+      buf = buf.slice(idx + 1);
+      if (line.length > 0) queue.push(line);
+    }
+    tryDeliver();
+  });
+  stream.on("end", () => {
+    if (buf.length > 0) {
+      queue.push(buf);
+      buf = "";
+    }
+    ended = true;
+    tryDeliver();
+  });
+  return {
+    next: (timeoutMs) => new Promise((resolve4) => {
+      if (queue.length > 0) {
+        resolve4(queue.shift());
+        return;
+      }
+      if (ended) {
+        resolve4(null);
+        return;
+      }
+      waiter = resolve4;
+      const t = setTimeout(() => {
+        if (waiter === resolve4) {
+          waiter = null;
+          resolve4(null);
+        }
+      }, Math.max(0, timeoutMs));
+      t.unref?.();
+    })
+  };
+}
+
 // src/scripts/watchStalePrsFlow.ts
 function readWatchConfig(ctx) {
   const cfg = ctx.config.watch;
@@ -7322,6 +7623,7 @@ var preflightScripts = {
   skipAgent,
   classifyByLabel,
   diagMcp,
+  warmupMcp,
   dispatchJobTicks,
   dispatchJobFileTicks
 };
@@ -7358,6 +7660,7 @@ var postflightScripts = {
   recordClassification,
   dispatchClassified,
   notifyTerminal,
+  openQaIssue,
   recordOutcome,
   mergeReleasePr,
   waitForCi,
@@ -7699,7 +8002,7 @@ async function runShellEntry(entry, ctx, profile) {
     env[`KODY_CFG_${k}`] = v;
   }
   const timeoutMs = resolveShellTimeoutMs(entry);
-  const child = spawn4("bash", [shellPath, ...positional], {
+  const child = spawn5("bash", [shellPath, ...positional], {
     cwd: ctx.cwd,
     env,
     stdio: ["pipe", "pipe", "pipe"],

package/dist/executables/qa-engineer/profile.json

@@ -0,0 +1,91 @@
+{
+  "name": "qa-engineer",
+  "role": "primitive",
+  "describe": "Free-form QA: browses a running site with Playwright MCP, explores routes, exercises UI states, posts a structured QA report. Opens a new issue per run by default; pass --issue <N> to comment on an existing one. Read-only on the repo.",
+  "kind": "oneshot",
+  "inputs": [
+    {
+      "name": "url",
+      "flag": "--url",
+      "type": "string",
+      "required": true,
+      "describe": "Base URL the agent should browse (e.g. http://localhost:3000)."
+    },
+    {
+      "name": "scope",
+      "flag": "--scope",
+      "type": "string",
+      "required": false,
+      "describe": "Optional feature focus (e.g. 'admin chat memory recall'). Without a scope the agent does a broad smoke pass over discovered routes."
+    },
+    {
+      "name": "issue",
+      "flag": "--issue",
+      "type": "int",
+      "required": false,
+      "describe": "Optional: comment the QA report on this existing issue instead of opening a new one."
+    },
+    {
+      "name": "authProfile",
+      "flag": "--auth-profile",
+      "type": "string",
+      "required": false,
+      "describe": "Path to a Playwright storageState.json for pre-authenticated sessions (skips manual login)."
+    }
+  ],
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "acceptEdits",
+    "maxTurns": null,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "tools": [
+      "Read",
+      "Grep",
+      "Glob",
+      "Bash",
+      "Write",
+      "Edit",
+      "mcp__playwright"
+    ],
+    "hooks": ["block-git"],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": [
+      {
+        "name": "playwright",
+        "command": "npx",
+        "args": ["-y", "--package=@playwright/mcp@latest", "--", "playwright-mcp"]
+      }
+    ]
+  },
+  "cliTools": [
+    {
+      "name": "playwright",
+      "install": {
+        "required": false,
+        "checkCommand": "ls \"$HOME/.cache/ms-playwright\" 2>/dev/null | grep -q '^chromium' || ls \"$HOME/Library/Caches/ms-playwright\" 2>/dev/null | grep -q '^chromium'",
+        "installCommand": "npx --yes playwright install chromium"
+      },
+      "verify": "ls \"$HOME/.cache/ms-playwright\" 2>/dev/null | grep -q '^chromium' || ls \"$HOME/Library/Caches/ms-playwright\" 2>/dev/null | grep -q '^chromium'",
+      "usage": "The Playwright MCP server uses Chromium under the hood. Preflight ensures it is installed. Save screenshots under `.kody/qa-reports/<run>/` if you take any — that directory is gitignored.",
+      "allowedUses": ["--version"]
+    }
+  ],
+  "inputArtifacts": [],
+  "outputArtifacts": [],
+  "scripts": {
+    "preflight": [
+      { "script": "discoverQaContext" },
+      { "script": "loadQaGuide" },
+      { "script": "loadConventions" },
+      { "script": "warmupMcp" },
+      { "script": "composePrompt" }
+    ],
+    "postflight": [
+      { "script": "openQaIssue" }
+    ]
+  }
+}

package/dist/executables/qa-engineer/prompt.md

@@ -0,0 +1,103 @@
+You are Kody, a senior QA engineer. Your job is to **browse the running app like a real user**, exercise the UI broadly and intentionally, and produce one structured QA report. You do NOT fix bugs. You do NOT touch tracked source files. You do NOT run `git` or `gh`.
+
+You may write throwaway artifacts (screenshots, ad-hoc Playwright specs) under `.kody/qa-reports/` — that path is gitignored.
+
+# Target
+
+Base URL: `{{args.url}}`
+{{#args.scope}}Focus: **{{args.scope}}**{{/args.scope}}
+{{^args.scope}}Focus: broad smoke across discovered routes.{{/args.scope}}
+{{#args.authProfile}}Auth: a saved Playwright `storageState.json` is available at `{{args.authProfile}}`. Pass it to `mcp__playwright__browser_navigate` via the `storageState` parameter so the session starts pre-authenticated.{{/args.authProfile}}
+{{^args.authProfile}}Auth: log in fresh using credentials from the QA guide if needed.{{/args.authProfile}}
+
+Report destination: {{#args.issue}}existing issue #{{args.issue}} (postflight will comment on it){{/args.issue}}{{^args.issue}}a new issue (postflight will open one and label it `kody:qa-report`){{/args.issue}}.
+
+# How to browse
+
+You have the **Playwright MCP** tools (`mcp__playwright__browser_navigate`, `mcp__playwright__browser_snapshot`, `mcp__playwright__browser_click`, `mcp__playwright__browser_type`, `mcp__playwright__browser_take_screenshot`, etc.). These return structured accessibility snapshots — prefer them over raw screenshots when you need to reason about the DOM. Reach for screenshots when something *looks* wrong rather than *is* wrong.
+
+Before anything else, navigate to the base URL:
+
+```
+mcp__playwright__browser_navigate({ url: "{{args.url}}" })
+```
+
+If that errors (timeout, DNS, connection refused), the app is unreachable. STOP browsing, write a short report explaining the failure, and exit. Don't fabricate findings.
+
+# QA context (auto-discovered from the repo)
+
+```
+{{qaContext}}
+```
+
+# QA guide (committed in the repo — authoritative over the auto-discovery above)
+
+{{qaGuide}}
+
+{{conventionsBlock}}
+
+{{toolsUsage}}
+
+# What to do
+
+1. **Plan the session.** From the QA context, the QA guide, and the focus, build a short test matrix. For each candidate UI surface, list the user-visible behaviors worth verifying. Skip surfaces unrelated to the focus.
+
+2. **Authenticate if required.** If a route under test needs a role and you have credentials (in the QA guide or via `--auth-profile`), log in once. If credentials for a needed role are missing, note it as a gap and browse only what you can.
+
+3. **Exercise each surface.** For every UI surface in your matrix, run through the relevant states. Don't pad — apply the checklist where it actually matters:
+   - **Happy path.** The user-visible behavior the surface exists to support, end to end.
+   - **Empty state.** Zero items, no rows, no results. Is the screen meaningfully empty or just confusingly blank?
+   - **Loading.** What renders before data resolves? Skeletons? Layout shift?
+   - **Error.** Force a failure where you reasonably can — invalid input, broken nav, network throttle. Is the error visible and actionable?
+   - **Validation.** Submit forms with invalid / boundary / empty inputs. What's the feedback?
+   - **Mobile / narrow viewport.** Resize to ~375px wide. Anything cut off, overlapping, illegible?
+   - **Keyboard nav.** Tab through. Is focus visible at every step? Can a keyboard-only user reach every interactive element? Does Enter/Space activate the right control?
+   - **Destructive action.** If present (delete, archive, sign out), confirm it's gated behind a confirmation and the gate works.
+
+4. **Capture evidence.** Save screenshots that show the bug or the verified-good state under `.kody/qa-reports/<scope-slug>/<finding-slug>.png`. Reference them by relative path in the report. Don't screenshot every step — only what you need to back a finding.
+
+5. **Write the report.** Your FINAL MESSAGE must be **the entire QA report markdown, verbatim** — no preamble, no `DONE` marker, no `COMMIT_MSG` marker. The postflight reads your final message and posts it.
+
+# Required output format
+
+```
+## Verdict: PASS | CONCERNS | FAIL
+
+_QA by kody — browsed `{{args.url}}`{{#args.scope}} (focus: {{args.scope}}){{/args.scope}}_
+
+### Summary
+<2–3 sentences: what you covered and what the running app actually does>
+
+### What I browsed
+- `<route>` — <surface checked, states exercised, screenshot path if any>
+- ...
+
+### Findings
+- **[P0 | P1 | P2 | P3] <short title>** — `<route>`
+  - **Steps:** 1) … 2) … 3) …
+  - **Expected:** …
+  - **Actual:** …
+  - **Evidence:** `.kody/qa-reports/.../shot.png` (if applicable)
+- ...
+- (write "None." if you found no defects)
+
+### Gaps
+- <anything you could NOT verify and why — missing creds, unreachable surface, no test data — say "None." if you covered everything in your matrix>
+
+### Bottom line
+<one sentence>
+```
+
+# Severity rubric
+
+- **P0** — blocks core flow, data loss, security exposure, total breakage on a critical path. Verdict must be FAIL if any P0 lands.
+- **P1** — broken feature on a non-critical path, or a P0-class issue with a workaround. Verdict typically FAIL.
+- **P2** — degraded UX (visual bugs, minor a11y, confusing copy, edge-case handling). Verdict typically CONCERNS.
+- **P3** — polish (alignment, micro-copy, non-blocking inconsistency). Doesn't affect verdict on its own.
+
+# Rules
+
+- No commits. No `git` / `gh`. No edits outside `.kody/qa-reports/`.
+- Verdict **PASS** only when every UI surface you exercised behaved as the user would expect.
+- Be specific in every finding: route + concrete steps + screenshot path (or DOM snapshot reference). No "consider improving X" advice.
+- If the base URL was unreachable, the report should still be valid markdown — just say so under "Bottom line" and "Gaps", and use verdict **CONCERNS** (not FAIL — there's no defect, only an unreachable target).

package/package.json

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

package/templates/kody.yml

@@ -81,13 +81,16 @@ jobs:
           node-version: 22
 
       - name: Write pip cache key for LiteLLM
-        run: echo "litellm[proxy]" > "${{ runner.temp }}/kody-pip-requirements.txt"
+        run: echo "litellm[proxy]" > .kody-pip-requirements.txt
 
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
           cache: "pip"
-          cache-dependency-path: ${{ runner.temp }}/kody-pip-requirements.txt
+          cache-dependency-path: .kody-pip-requirements.txt
+
+      - name: Remove pip cache key file (avoid blocking branch switches)
+        run: rm -f .kody-pip-requirements.txt
 
       - env:
           ALL_SECRETS:   ${{ toJSON(secrets) }}