@kody-ade/kody-engine 0.4.217 → 0.4.219

package/dist/bin/kody.js

@@ -15,7 +15,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@kody-ade/kody-engine",
-      version: "0.4.217",
+      version: "0.4.219",
       description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
       license: "MIT",
       type: "module",
@@ -1981,6 +1981,110 @@ var init_agent = __esm({
   }
 });
 
+// src/scripts/jobFrontmatter.ts
+function splitFrontmatter(raw) {
+  const match = FRONTMATTER_RE.exec(raw);
+  if (!match) return { frontmatter: {}, body: raw };
+  const inner = match[1] ?? "";
+  const body = raw.slice(match[0].length);
+  return { frontmatter: parseFlatYaml(inner), body };
+}
+function isScheduleEvery(value) {
+  return typeof value === "string" && SCHEDULE_EVERY_VALUES.includes(value);
+}
+function scheduleEveryToMs(every) {
+  const MIN = 60 * 1e3;
+  const HOUR = 60 * MIN;
+  const DAY = 24 * HOUR;
+  switch (every) {
+    case "15m":
+      return 15 * MIN;
+    case "30m":
+      return 30 * MIN;
+    case "1h":
+      return HOUR;
+    case "2h":
+      return 2 * HOUR;
+    case "6h":
+      return 6 * HOUR;
+    case "12h":
+      return 12 * HOUR;
+    case "1d":
+      return DAY;
+    case "3d":
+      return 3 * DAY;
+    case "7d":
+      return 7 * DAY;
+    case "manual":
+      return Number.POSITIVE_INFINITY;
+  }
+}
+function parseFlatYaml(text) {
+  const out = {};
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const colon = line.indexOf(":");
+    if (colon < 0) continue;
+    const key = line.slice(0, colon).trim();
+    const value = stripQuotes(line.slice(colon + 1).trim());
+    if (key === "action" && value.length > 0) {
+      out.action = value;
+    } else if (key === "executable" && value.length > 0) {
+      out.executable = value;
+    } else if (key === "every" && isScheduleEvery(value)) {
+      out.every = value;
+    } else if (key === "tickScript" && value.length > 0) {
+      out.tickScript = value;
+    } else if (key === "disabled") {
+      const lower = value.toLowerCase();
+      if (lower === "true") out.disabled = true;
+      else if (lower === "false") out.disabled = false;
+    } else if (key === "staff" && value.length > 0) {
+      out.staff = value;
+    } else if (key === "mentions") {
+      const logins = value.split(",").map((s) => s.trim().replace(/^@/, "")).filter(Boolean);
+      if (logins.length > 0) out.mentions = logins;
+    } else if (key === "tools") {
+      const names = value.split(",").map((s) => s.trim()).filter(Boolean);
+      if (names.length > 0) out.tools = names;
+    } else if (key === "executables") {
+      const names = value.split(",").map((s) => s.trim()).filter(Boolean);
+      if (names.length > 0) out.executables = names;
+    }
+  }
+  return out;
+}
+function stripQuotes(value) {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if (first === '"' && last === '"' || first === "'" && last === "'") {
+      return value.slice(1, -1);
+    }
+  }
+  return value;
+}
+var SCHEDULE_EVERY_VALUES, FRONTMATTER_RE;
+var init_jobFrontmatter = __esm({
+  "src/scripts/jobFrontmatter.ts"() {
+    "use strict";
+    SCHEDULE_EVERY_VALUES = [
+      "15m",
+      "30m",
+      "1h",
+      "2h",
+      "6h",
+      "12h",
+      "1d",
+      "3d",
+      "7d",
+      "manual"
+    ];
+    FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+  }
+});
+
 // src/registry.ts
 import * as fs6 from "fs";
 import * as path6 from "path";
@@ -2020,6 +2124,21 @@ function getBuiltinJobsRoot() {
   }
   return candidates[0];
 }
+function getBuiltinDutiesRoot() {
+  const here = path6.dirname(new URL(import.meta.url).pathname);
+  const candidates = [
+    path6.join(here, "duties"),
+    // dev: src/
+    path6.join(here, "..", "duties"),
+    // built: dist/bin → dist/duties
+    path6.join(here, "..", "src", "duties")
+    // fallback
+  ];
+  for (const c of candidates) {
+    if (fs6.existsSync(c) && fs6.statSync(c).isDirectory()) return c;
+  }
+  return candidates[0];
+}
 function listBuiltinJobs(root = getBuiltinJobsRoot()) {
   if (!fs6.existsSync(root) || !fs6.statSync(root).isDirectory()) return [];
   const out = [];
@@ -2104,9 +2223,128 @@ function resolveExecutable(name, roots = getExecutableRoots()) {
 function hasExecutable(name, roots = getExecutableRoots()) {
   return resolveExecutable(name, roots) !== null;
 }
+function listDutyActions(projectDutiesRoot = getProjectDutiesRoot()) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  const add = (action) => {
+    if (!isSafeName(action.action) || !isSafeName(action.duty) || !isSafeName(action.executable)) return;
+    if (seen.has(action.action)) return;
+    seen.add(action.action);
+    out.push(action);
+  };
+  for (const action of listProjectFolderDutyActions(projectDutiesRoot)) add(action);
+  for (const action of listProjectMarkdownDutyActions(projectDutiesRoot)) add(action);
+  for (const action of listBuiltinDutyActions()) add(action);
+  return out.sort((a, b) => a.action.localeCompare(b.action));
+}
+function resolveDutyAction(action, projectDutiesRoot = getProjectDutiesRoot()) {
+  if (!isSafeName(action)) return null;
+  return listDutyActions(projectDutiesRoot).find((d) => d.action === action) ?? null;
+}
+function hasDutyAction(action, projectDutiesRoot = getProjectDutiesRoot()) {
+  return resolveDutyAction(action, projectDutiesRoot) !== null;
+}
 function isSafeName(name) {
   return /^[a-z][a-z0-9-]*$/.test(name) && !name.includes("..");
 }
+function listProjectFolderDutyActions(root) {
+  if (!fs6.existsSync(root) || !fs6.statSync(root).isDirectory()) return [];
+  const out = [];
+  for (const ent of fs6.readdirSync(root, { withFileTypes: true })) {
+    if (!ent.isDirectory() || ent.name.startsWith(".") || ent.name.startsWith("_")) continue;
+    if (!isSafeName(ent.name)) continue;
+    const profilePath = path6.join(root, ent.name, "profile.json");
+    if (!fs6.existsSync(profilePath) || !fs6.statSync(profilePath).isFile()) continue;
+    try {
+      const raw = JSON.parse(fs6.readFileSync(profilePath, "utf-8"));
+      const action = stringOr(raw.action, ent.name);
+      const executable = stringOr(raw.executable, ent.name);
+      out.push({
+        action,
+        duty: ent.name,
+        executable,
+        cliArgs: {},
+        source: "project-folder",
+        describe: typeof raw.describe === "string" ? raw.describe : void 0,
+        profilePath
+      });
+    } catch {
+      continue;
+    }
+  }
+  return out.sort((a, b) => a.action.localeCompare(b.action));
+}
+function listProjectMarkdownDutyActions(root) {
+  if (!fs6.existsSync(root) || !fs6.statSync(root).isDirectory()) return [];
+  const out = [];
+  for (const ent of fs6.readdirSync(root, { withFileTypes: true })) {
+    if (!ent.isFile() || !ent.name.endsWith(".md")) continue;
+    const duty = ent.name.slice(0, -3);
+    if (!isSafeName(duty)) continue;
+    const filePath = path6.join(root, ent.name);
+    try {
+      const raw = fs6.readFileSync(filePath, "utf-8");
+      const { frontmatter } = splitFrontmatter(raw);
+      const action = frontmatter.action?.trim() || duty;
+      const implementation = markdownDutyImplementation(duty, frontmatter);
+      out.push({
+        action,
+        duty,
+        executable: implementation.executable,
+        cliArgs: implementation.cliArgs,
+        source: "project-markdown",
+        filePath
+      });
+    } catch {
+      continue;
+    }
+  }
+  return out.sort((a, b) => a.action.localeCompare(b.action));
+}
+function markdownDutyImplementation(duty, frontmatter) {
+  if (frontmatter.executable?.trim()) {
+    return { executable: frontmatter.executable.trim(), cliArgs: {} };
+  }
+  if (frontmatter.executables?.length === 1 && frontmatter.executables[0]?.trim()) {
+    return { executable: frontmatter.executables[0].trim(), cliArgs: {} };
+  }
+  if (frontmatter.tickScript?.trim()) {
+    return { executable: "duty-tick-scripted", cliArgs: { duty } };
+  }
+  return { executable: "duty-tick", cliArgs: { duty } };
+}
+function listBuiltinDutyActions(root = getBuiltinDutiesRoot()) {
+  const filePath = path6.join(root, "public-actions.json");
+  if (!fs6.existsSync(filePath) || !fs6.statSync(filePath).isFile()) return [];
+  try {
+    const raw = JSON.parse(fs6.readFileSync(filePath, "utf-8"));
+    if (!Array.isArray(raw)) return [];
+    const out = [];
+    for (const item of raw) {
+      if (!item || typeof item !== "object") continue;
+      const r = item;
+      const duty = stringOr(r.duty, stringOr(r.name, ""));
+      const action = stringOr(r.action, duty);
+      const executable = stringOr(r.executable, duty);
+      if (!duty || !action || !executable) continue;
+      out.push({
+        action,
+        duty,
+        executable,
+        cliArgs: {},
+        source: "builtin",
+        describe: typeof r.describe === "string" ? r.describe : void 0,
+        filePath
+      });
+    }
+    return out.sort((a, b) => a.action.localeCompare(b.action));
+  } catch {
+    return [];
+  }
+}
+function stringOr(value, fallback) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
+}
 function getProfileInputs(name, roots = getExecutableRoots()) {
   const profilePath = resolveExecutable(name, roots);
   if (!profilePath) return null;
@@ -2147,6 +2385,7 @@ var _builtinNames;
 var init_registry = __esm({
   "src/registry.ts"() {
     "use strict";
+    init_jobFrontmatter();
     _builtinNames = null;
   }
 });
@@ -2495,7 +2734,7 @@ var init_buildSyntheticPlugin = __esm({
 // src/subagents.ts
 import * as fs14 from "fs";
 import * as path13 from "path";
-function splitFrontmatter(raw) {
+function splitFrontmatter2(raw) {
   const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(raw);
   if (!match) return { fm: {}, body: raw.trim() };
   const fm = {};
@@ -2531,7 +2770,7 @@ function loadSubagents(profile) {
   const agents = {};
   for (const name of names) {
     const raw = profile.subagentTemplates?.[name] ?? fs14.readFileSync(resolveAgentFile(profile.dir, name), "utf-8");
-    const { fm, body } = splitFrontmatter(raw);
+    const { fm, body } = splitFrontmatter2(raw);
     if (!body) throw new Error(`loadSubagents: agent '${name}' has an empty prompt body`);
     const def = {
       description: fm.description ?? `Subagent ${name}`,
@@ -2587,6 +2826,7 @@ function loadProfile(profilePath) {
     return {
       ...base,
       name: requireString(profilePath, r, "name"),
+      action: typeof r.action === "string" && r.action.trim() ? r.action.trim() : void 0,
       executable: execRef,
       describe: typeof r.describe === "string" ? r.describe : base.describe,
       staff: typeof r.staff === "string" && r.staff.trim() ? r.staff.trim() : base.staff,
@@ -2630,6 +2870,7 @@ function loadProfile(profilePath) {
   }
   const profile = {
     name: requireString(profilePath, r, "name"),
+    action: typeof r.action === "string" && r.action.trim() ? r.action.trim() : void 0,
     executable: void 0,
     describe: typeof r.describe === "string" ? r.describe : "",
     // Optional persona to run as. Empty/blank string → undefined (no persona).
@@ -2967,6 +3208,7 @@ var init_profile = __esm({
     VALID_PHASES = /* @__PURE__ */ new Set(["research", "planning", "implementing", "reviewing", "shipped", "failed", "idle"]);
     KNOWN_PROFILE_KEYS = /* @__PURE__ */ new Set([
       "name",
+      "action",
       "executable",
       "staff",
       "every",
@@ -7041,10 +7283,12 @@ ${stateBody}`;
 
 // src/jobIdentity.ts
 function stableJobKey(job) {
-  const executable = job.executable ?? job.duty ?? "unknown";
+  const duty = job.duty ?? job.action;
+  const executable = job.executable ?? duty ?? "unknown";
   if (job.flavor === "scheduled" && job.duty) return `scheduled:${job.duty}:${executable}`;
   const target = typeof job.target === "number" ? job.target : targetFromCliArgs(job.cliArgs);
-  return target === void 0 ? `${job.flavor}:${executable}` : `${job.flavor}:${executable}:${target}`;
+  const work = duty ?? executable;
+  return target === void 0 ? `${job.flavor}:${work}` : `${job.flavor}:${work}:${target}`;
 }
 function targetFromCliArgs(cliArgs) {
   if (!cliArgs) return void 0;
@@ -7083,8 +7327,8 @@ function validateJob(input) {
     throw new InvalidJobError("job must be an object");
   }
   const j = input;
-  if (typeof j.executable !== "string" && typeof j.duty !== "string") {
-    throw new InvalidJobError("job must reference an executable or a duty");
+  if (typeof j.executable !== "string" && typeof j.duty !== "string" && typeof j.action !== "string") {
+    throw new InvalidJobError("job must reference a duty action, duty, or executable");
   }
   if (j.flavor !== "instant" && j.flavor !== "scheduled") {
     throw new InvalidJobError(`job.flavor must be "instant" or "scheduled" (got ${String(j.flavor)})`);
@@ -7093,6 +7337,7 @@ function validateJob(input) {
     throw new InvalidJobError("job.cliArgs must be an object when present");
   }
   return {
+    action: typeof j.action === "string" ? j.action : void 0,
     executable: typeof j.executable === "string" ? j.executable : void 0,
     duty: typeof j.duty === "string" ? j.duty : void 0,
     why: typeof j.why === "string" ? j.why : void 0,
@@ -7106,7 +7351,9 @@ function validateJob(input) {
 }
 async function runJob(job, base) {
   const valid = validateJob(job);
-  const profileName = valid.executable ?? valid.duty;
+  const action = valid.action ?? valid.duty;
+  const resolvedDuty = action ? resolveDutyAction(action) : null;
+  const profileName = valid.executable ?? resolvedDuty?.executable ?? valid.duty;
   if (!profileName) {
     throw new InvalidJobError("job resolves to no executable or duty");
   }
@@ -7115,8 +7362,12 @@ async function runJob(job, base) {
   preloadedData.jobKey = stableJobKey(valid);
   preloadedData.jobFlavor = valid.flavor;
   if (valid.target !== void 0) preloadedData.jobTarget = valid.target;
-  if (valid.duty !== void 0 && valid.duty.length > 0) preloadedData.jobDuty = valid.duty;
-  if (valid.executable !== void 0 && valid.executable.length > 0) preloadedData.jobExecutable = valid.executable;
+  if (valid.action !== void 0 && valid.action.length > 0) preloadedData.jobAction = valid.action;
+  const dutyIdentity = valid.duty ?? resolvedDuty?.duty;
+  if (dutyIdentity !== void 0 && dutyIdentity.length > 0) preloadedData.jobDuty = dutyIdentity;
+  const executableIdentity = valid.executable ?? resolvedDuty?.executable;
+  if (executableIdentity !== void 0 && executableIdentity.length > 0)
+    preloadedData.jobExecutable = executableIdentity;
   if (valid.schedule !== void 0 && valid.schedule.length > 0) preloadedData.jobSchedule = valid.schedule;
   if (valid.why !== void 0 && valid.why.length > 0) preloadedData.jobWhy = valid.why;
   if (valid.persona !== void 0) preloadedData.jobPersona = valid.persona;
@@ -7124,16 +7375,20 @@ async function runJob(job, base) {
     cliArgs: { ...valid.cliArgs },
     cwd: base.cwd,
     config: base.config,
+    skipConfig: base.skipConfig,
     verbose: base.verbose,
     quiet: base.quiet,
     preloadedData: Object.keys(preloadedData).length > 0 ? preloadedData : void 0
   };
+  input.cliArgs = resolvedDuty ? { ...resolvedDuty.cliArgs, ...input.cliArgs } : input.cliArgs;
   const run = base.chain === false ? runExecutable : runExecutableChain;
   return run(profileName, input);
 }
 function mintInstantJob(dispatch2, opts) {
   return {
+    action: dispatch2.action,
     executable: dispatch2.executable,
+    duty: dispatch2.duty,
     why: opts?.why ?? dispatch2.why,
     persona: opts?.persona ?? DEFAULT_INSTANT_PERSONA,
     target: dispatch2.target,
@@ -7156,6 +7411,7 @@ var init_job = __esm({
   "src/job.ts"() {
     "use strict";
     init_executor();
+    init_registry();
     init_jobIdentity();
     init_jobIdentity();
     DEFAULT_INSTANT_PERSONA = "kody";
@@ -7169,106 +7425,6 @@ var init_job = __esm({
   }
 });
 
-// src/scripts/jobFrontmatter.ts
-function splitFrontmatter2(raw) {
-  const match = FRONTMATTER_RE.exec(raw);
-  if (!match) return { frontmatter: {}, body: raw };
-  const inner = match[1] ?? "";
-  const body = raw.slice(match[0].length);
-  return { frontmatter: parseFlatYaml(inner), body };
-}
-function isScheduleEvery(value) {
-  return typeof value === "string" && SCHEDULE_EVERY_VALUES.includes(value);
-}
-function scheduleEveryToMs(every) {
-  const MIN = 60 * 1e3;
-  const HOUR = 60 * MIN;
-  const DAY = 24 * HOUR;
-  switch (every) {
-    case "15m":
-      return 15 * MIN;
-    case "30m":
-      return 30 * MIN;
-    case "1h":
-      return HOUR;
-    case "2h":
-      return 2 * HOUR;
-    case "6h":
-      return 6 * HOUR;
-    case "12h":
-      return 12 * HOUR;
-    case "1d":
-      return DAY;
-    case "3d":
-      return 3 * DAY;
-    case "7d":
-      return 7 * DAY;
-    case "manual":
-      return Number.POSITIVE_INFINITY;
-  }
-}
-function parseFlatYaml(text) {
-  const out = {};
-  for (const rawLine of text.split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (!line || line.startsWith("#")) continue;
-    const colon = line.indexOf(":");
-    if (colon < 0) continue;
-    const key = line.slice(0, colon).trim();
-    const value = stripQuotes(line.slice(colon + 1).trim());
-    if (key === "every" && isScheduleEvery(value)) {
-      out.every = value;
-    } else if (key === "tickScript" && value.length > 0) {
-      out.tickScript = value;
-    } else if (key === "disabled") {
-      const lower = value.toLowerCase();
-      if (lower === "true") out.disabled = true;
-      else if (lower === "false") out.disabled = false;
-    } else if (key === "staff" && value.length > 0) {
-      out.staff = value;
-    } else if (key === "mentions") {
-      const logins = value.split(",").map((s) => s.trim().replace(/^@/, "")).filter(Boolean);
-      if (logins.length > 0) out.mentions = logins;
-    } else if (key === "tools") {
-      const names = value.split(",").map((s) => s.trim()).filter(Boolean);
-      if (names.length > 0) out.tools = names;
-    } else if (key === "executables") {
-      const names = value.split(",").map((s) => s.trim()).filter(Boolean);
-      if (names.length > 0) out.executables = names;
-    }
-  }
-  return out;
-}
-function stripQuotes(value) {
-  if (value.length >= 2) {
-    const first = value[0];
-    const last = value[value.length - 1];
-    if (first === '"' && last === '"' || first === "'" && last === "'") {
-      return value.slice(1, -1);
-    }
-  }
-  return value;
-}
-var SCHEDULE_EVERY_VALUES, FRONTMATTER_RE;
-var init_jobFrontmatter = __esm({
-  "src/scripts/jobFrontmatter.ts"() {
-    "use strict";
-    SCHEDULE_EVERY_VALUES = [
-      "15m",
-      "30m",
-      "1h",
-      "2h",
-      "6h",
-      "12h",
-      "1d",
-      "3d",
-      "7d",
-      "manual"
-    ];
-    FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
-  }
-});
-
 // src/scripts/issueStateComment.ts
 function isStateEnvelope(x) {
   if (x === null || typeof x !== "object") return false;
@@ -7827,7 +7983,7 @@ function formatAgo(ms) {
 function readJobFile(cwd, jobsDir, slug) {
   try {
     const raw = fs29.readFileSync(path26.join(cwd, jobsDir, `${slug}.md`), "utf-8");
-    return splitFrontmatter2(raw);
+    return splitFrontmatter(raw);
   } catch {
     return { frontmatter: {}, body: "" };
   }
@@ -9818,7 +9974,7 @@ var init_loadJobFromFile = __esm({
       }
       const raw = fs31.readFileSync(absPath, "utf-8");
       const { title, body } = parseJobFile(raw, slug);
-      const frontmatter = splitFrontmatter2(raw).frontmatter;
+      const frontmatter = splitFrontmatter(raw).frontmatter;
       const mentions = (frontmatter.mentions ?? []).map((login) => `@${login}`).join(" ");
       const workerSlug = (frontmatter.staff ?? "").trim();
       let workerTitle = "";
@@ -10162,7 +10318,7 @@ function stripDirective(body) {
   return lines.slice(start).join("\n").trim();
 }
 function parsePersona(raw, slug) {
-  const stripped = splitFrontmatter2(raw).body;
+  const stripped = splitFrontmatter(raw).body;
   const trimmed = stripped.trim();
   const firstLine2 = trimmed.split("\n", 1)[0] ?? "";
   const h1 = /^#\s+(.+?)\s*$/.exec(firstLine2);
@@ -12500,7 +12656,7 @@ var init_runTickScript = __esm({
         return;
       }
       const raw = fs36.readFileSync(jobPath, "utf-8");
-      const { frontmatter } = splitFrontmatter2(raw);
+      const { frontmatter } = splitFrontmatter(raw);
       const tickScript = frontmatter.tickScript;
       if (!tickScript) {
         ctx.output.exitCode = 99;
@@ -15370,10 +15526,48 @@ function primaryNumericInputName(executable) {
   const intInput = inputs.find((i) => i.type === "int" && i.required);
   return intInput?.name ?? null;
 }
+function resolveOperatorAction(action) {
+  return resolveDutyAction(action);
+}
+function resolveConfiguredAction(action) {
+  const resolved = resolveDutyAction(action);
+  if (resolved) return resolved;
+  return compatibilityDutyAction(action);
+}
+function requiredRoute(action) {
+  return resolveConfiguredAction(action) ?? {
+    action,
+    duty: action,
+    executable: action,
+    cliArgs: {},
+    source: "builtin"
+  };
+}
+function compatibilityDutyAction(action) {
+  if (!/^[a-z][a-z0-9-]*$/.test(action)) return null;
+  return {
+    action,
+    duty: action,
+    executable: action,
+    cliArgs: {},
+    source: "builtin"
+  };
+}
+function routeResult(route, cliArgs, target, why) {
+  const result = {
+    action: route.action,
+    duty: route.duty,
+    executable: route.executable,
+    cliArgs: { ...route.cliArgs, ...cliArgs },
+    target
+  };
+  if (why !== void 0 && why.length > 0) result.why = why;
+  return result;
+}
 function autoDispatch(opts) {
   const explicit = opts?.explicit;
   if (explicit?.issueNumber && explicit.issueNumber > 0) {
-    return { executable: "run", cliArgs: { issue: explicit.issueNumber }, target: explicit.issueNumber };
+    return routeResult(requiredRoute("run"), { issue: explicit.issueNumber }, explicit.issueNumber);
   }
   const eventName = process.env.GITHUB_EVENT_NAME;
   const eventPath = process.env.GITHUB_EVENT_PATH;
@@ -15388,25 +15582,29 @@ function autoDispatch(opts) {
     const inputs2 = objectValue(event.inputs);
     const n = parseInt(String(inputs2?.issue_number ?? ""), 10);
     if (!Number.isNaN(n) && n > 0) {
-      const exe = String(inputs2?.executable ?? "").trim() || "run";
+      const actionName = String(inputs2?.executable ?? "").trim() || "run";
+      const route2 = resolveConfiguredAction(actionName);
+      if (!route2) return null;
       const base = String(inputs2?.base ?? "").trim();
-      const targetKey = primaryNumericInputName(exe) ?? "issue";
+      const targetKey = primaryNumericInputName(route2.executable) ?? "issue";
       const cliArgs = { [targetKey]: n };
       if (base) cliArgs.base = base;
-      return { executable: exe, cliArgs, target: n };
+      return routeResult(route2, cliArgs, n);
     }
     return null;
   }
   if (eventName === "schedule") return null;
   if (eventName === "pull_request") {
-    const exe = opts?.config?.onPullRequest?.trim();
+    const actionName = opts?.config?.onPullRequest?.trim();
     const action = String(event.action ?? "");
-    if (exe && (action === "opened" || action === "synchronize" || action === "reopened")) {
+    if (actionName && (action === "opened" || action === "synchronize" || action === "reopened")) {
+      const route2 = resolveConfiguredAction(actionName);
+      if (!route2) return null;
       const pullRequest = objectValue(event.pull_request);
       const prNum = Number(pullRequest?.number ?? event.number ?? 0);
       if (prNum > 0) {
-        const targetKey = primaryNumericInputName(exe) ?? "pr";
-        return { executable: exe, cliArgs: { [targetKey]: prNum }, target: prNum };
+        const targetKey = primaryNumericInputName(route2.executable) ?? "pr";
+        return routeResult(route2, { [targetKey]: prNum }, prNum);
       }
     }
     return null;
@@ -15430,21 +15628,22 @@ function autoDispatch(opts) {
   const firstToken = firstTokenRaw && POLITE_WORDS.has(firstTokenRaw) ? null : firstTokenRaw;
   const aliases = opts?.config?.aliases ?? BUILTIN_ALIASES;
   const aliased = firstToken ? aliases[firstToken] ?? firstToken : null;
-  let executable = null;
+  let route = null;
   let consumedFirstToken = false;
   if (aliased) {
-    if (getProfileInputs(aliased) !== null) {
-      executable = aliased;
+    route = resolveOperatorAction(aliased);
+    if (route) {
       consumedFirstToken = true;
     } else if (firstToken && aliases[firstToken] && aliases[firstToken] === aliased) {
       process.stderr.write(
-        `[kody] dispatch: alias '${firstToken}' \u2192 '${aliased}' has no matching executable; falling back to default
+        `[kody] dispatch: alias '${firstToken}' \u2192 '${aliased}' has no matching duty action; falling back to default
 `
       );
     }
   }
-  if (!executable && !firstToken) {
-    executable = isPr ? opts?.config?.defaultPrExecutable ?? null : opts?.config?.defaultExecutable ?? null;
+  if (!route && !firstToken) {
+    const defaultAction = isPr ? opts?.config?.defaultPrExecutable ?? null : opts?.config?.defaultExecutable ?? null;
+    route = defaultAction ? resolveConfiguredAction(defaultAction) : null;
   }
   if (isBotAuthor && !consumedFirstToken) {
     process.stderr.write(
@@ -15453,16 +15652,16 @@ function autoDispatch(opts) {
     );
     return null;
   }
-  if (!executable) {
+  if (!route) {
     if (!firstToken) return null;
-    const profileMissing = aliased ? getProfileInputs(aliased) === null : true;
+    const profileMissing = aliased ? resolveOperatorAction(aliased) === null : true;
     process.stderr.write(
-      `[kody] dispatch: no executable resolved for issue_comment (firstToken=${firstToken ?? "<none>"}, aliased=${aliased ?? "<none>"}, profileFound=${!profileMissing}, defaultExecutable=${opts?.config?.defaultExecutable ?? "<unset>"}, defaultPrExecutable=${opts?.config?.defaultPrExecutable ?? "<unset>"})
+      `[kody] dispatch: no duty action resolved for issue_comment (firstToken=${firstToken ?? "<none>"}, aliased=${aliased ?? "<none>"}, actionFound=${!profileMissing}, defaultExecutable=${opts?.config?.defaultExecutable ?? "<unset>"}, defaultPrExecutable=${opts?.config?.defaultPrExecutable ?? "<unset>"})
 `
     );
     return null;
   }
-  const inputs = getProfileInputs(executable);
+  const inputs = getProfileInputs(route.executable);
   const effectiveInputs = inputs ?? [];
   const unknownProfile = inputs === null;
   const rest = extractCommentRest(afterTag, consumedFirstToken ? firstToken : null);
@@ -15479,7 +15678,7 @@ function autoDispatch(opts) {
   } else if (leftover.length > 0) {
     why = leftover;
   }
-  return { executable, cliArgs: args, target: targetNum, why };
+  return routeResult(route, args, targetNum, why);
 }
 function autoDispatchTyped(opts) {
   const legacy = autoDispatch(opts);
@@ -15527,7 +15726,7 @@ function autoDispatchTyped(opts) {
       reason: tokenRaw ? `polite-word lead-in '${tokenRaw}', no default executable configured` : "no subcommand token, no default executable configured"
     };
   }
-  const available = listExecutables().map((e) => e.name).filter((n) => !n.startsWith("goal-") && !n.startsWith("job-")).sort();
+  const available = listDutyActions().map((e) => e.action).filter((n) => !n.startsWith("goal-") && !n.startsWith("job-")).sort();
   return { kind: "unrecognized", token: tokenRaw, target: targetNum, isPr, available };
 }
 function dispatchScheduledWatches(opts) {
@@ -15564,7 +15763,7 @@ function dispatchScheduledWatches(opts) {
         continue;
       }
     }
-    out.push({ executable: exe.name, cliArgs: {}, target: 0 });
+    out.push({ action: exe.name, duty: exe.name, executable: exe.name, cliArgs: {}, target: 0 });
   }
   return out;
 }
@@ -15670,6 +15869,7 @@ init_executor();
 init_gha();
 init_issue();
 init_job();
+init_registry();
 var CI_HELP = `kody ci \u2014 minimal-YAML autonomous engineer (CI preflight + run)
 
 Usage:
@@ -15910,7 +16110,7 @@ async function runCi(argv) {
   const eventName = process.env.GITHUB_EVENT_NAME;
   const dispatchEventPath = process.env.GITHUB_EVENT_PATH;
   let manualWorkflowDispatch = false;
-  let forceRunDuty = null;
+  let forceRunAction = null;
   if (!args.issueNumber && !autoFallback && eventName === "workflow_dispatch" && dispatchEventPath && fs40.existsSync(dispatchEventPath)) {
     try {
       const evt = JSON.parse(fs40.readFileSync(dispatchEventPath, "utf-8"));
@@ -15918,15 +16118,21 @@ async function runCi(argv) {
       const sessionInput = String(evt?.inputs?.sessionId ?? "");
       const exeInput = String(evt?.inputs?.executable ?? "").trim();
       const noTarget = !sessionInput && !(Number.isFinite(issueInput) && issueInput > 0);
-      if (noTarget && exeInput) forceRunDuty = exeInput;
+      if (noTarget && exeInput) forceRunAction = exeInput;
       else manualWorkflowDispatch = noTarget;
     } catch {
       manualWorkflowDispatch = false;
     }
   }
-  if (forceRunDuty) {
+  if (forceRunAction) {
     const config = earlyConfig ?? loadConfig(cwd);
-    process.stdout.write(`\u2192 kody: manual one-shot run of duty ${forceRunDuty}
+    const route = resolveDutyAction(forceRunAction);
+    if (!route) {
+      process.stderr.write(`[kody] manual one-shot action '${forceRunAction}' has no duty action
+`);
+      return 64;
+    }
+    process.stdout.write(`\u2192 kody: manual one-shot run of duty action ${route.action} (${route.duty})
 
 `);
     try {
@@ -15957,13 +16163,22 @@ async function runCi(argv) {
 `);
       return 99;
     }
-    const result = await runExecutableChain(forceRunDuty, {
-      cliArgs: {},
-      cwd,
-      config,
-      verbose: args.verbose,
-      quiet: args.quiet
-    });
+    const result = await runJob(
+      {
+        action: route.action,
+        duty: route.duty,
+        executable: route.executable,
+        cliArgs: route.cliArgs,
+        flavor: "instant",
+        force: true
+      },
+      {
+        cwd,
+        config,
+        verbose: args.verbose,
+        quiet: args.quiet
+      }
+    );
     const ec = result.exitCode;
     return ec === 0 || ec === 1 || ec === 2 ? ec : 99;
   }
@@ -16024,13 +16239,17 @@ ${CI_HELP}`);
     return 64;
   }
   const dispatch2 = autoFallback ?? {
+    action: "run",
+    duty: "run",
     executable: "run",
     cliArgs: { issue: args.issueNumber },
     target: args.issueNumber
   };
   const issueNumber = dispatch2.target;
-  process.stdout.write(`\u2192 kody preflight (cwd=${cwd}, executable=${dispatch2.executable}, target=${issueNumber})
-`);
+  process.stdout.write(
+    `\u2192 kody preflight (cwd=${cwd}, action=${dispatch2.action}, duty=${dispatch2.duty}, executable=${dispatch2.executable}, target=${issueNumber})
+`
+  );
   try {
     const n = unpackAllSecrets();
     if (n > 0) process.stdout.write(`\u2192 kody: unpacked ${n} secret(s) from ALL_SECRETS
@@ -17610,6 +17829,7 @@ ${CHAT_HELP}`);
 // src/entry.ts
 init_config();
 init_executor();
+init_job();
 init_registry();
 
 // src/servers/pool-serve.ts
@@ -17831,6 +18051,7 @@ var PoolManager = class {
   }
   deps;
   free = [];
+  claimed = /* @__PURE__ */ new Set();
   booting = 0;
   claimsInFlight = 0;
   refilling = false;
@@ -17847,16 +18068,15 @@ var PoolManager = class {
   }
   /**
    * Resize the warm target at runtime (per-repo, sourced from the repo's vault
-   * POOL_MIN). Raising it warms up immediately via refill; lowering it just
-   * stops topping up — surplus machines drain as they're claimed/auto-destroyed,
-   * never force-killed. No-op when unchanged or given a bad value.
+   * POOL_MIN). Raising it warms immediately; lowering it prunes idle surplus
+   * warm machines. No-op when unchanged or given a bad value.
    */
   setMin(min) {
     if (!Number.isInteger(min) || min < 0) return;
     if (min === this.deps.config.min) return;
     this.deps.config.min = min;
     this.log(`min set to ${min}`);
-    void this.refill();
+    void this.rebalance("setMin");
   }
   /**
    * Adopt existing pooled machines on owner (re)start: suspended ones become
@@ -17865,12 +18085,17 @@ var PoolManager = class {
   async reconcile() {
     const machines = await this.deps.fly.listPooled(this.deps.config.repoTag);
     this.free = [];
+    const surplus = [];
     for (const m of machines) {
-      if ((m.state === "suspended" || m.state === "suspending") && m.private_ip) {
+      if (!isSuspendedWithIp(m)) continue;
+      if (this.warmCapacity() < this.deps.config.min) {
         this.free.push({ id: m.id, privateIp: m.private_ip });
+      } else {
+        surplus.push(m.id);
       }
     }
-    this.log(`reconcile: adopted ${this.free.length} suspended machine(s)`);
+    const destroyed = await this.destroySurplus(surplus);
+    this.log(`reconcile: adopted ${this.free.length} suspended machine(s), destroyed ${destroyed} surplus`);
     await this.refill();
   }
   /**
@@ -17887,6 +18112,7 @@ var PoolManager = class {
       const machine = this.free.shift();
       if (!machine) break;
       this.claimsInFlight++;
+      this.claimed.add(machine.id);
       try {
         await this.deps.fly.start(machine.id);
         const healthy = await this.deps.fly.waitHealthy(this.baseUrl(machine), {
@@ -17913,6 +18139,7 @@ var PoolManager = class {
         await this.safeDestroy(machine.id);
         lastReason = errMsg2(err);
       } finally {
+        this.claimed.delete(machine.id);
         this.claimsInFlight--;
       }
     }
@@ -17940,16 +18167,24 @@ var PoolManager = class {
     const before = this.free.length;
     this.free = this.free.filter((f) => liveIds.has(f.id));
     const pruned = before - this.free.length;
-    const tracked = new Set(this.free.map((f) => f.id));
+    const destroyedTracked = await this.trimFreeSurplus("resync");
+    const tracked = /* @__PURE__ */ new Set([...this.free.map((f) => f.id), ...this.claimed]);
     let adopted = 0;
+    const surplus = [];
     for (const m of machines) {
-      if ((m.state === "suspended" || m.state === "suspending") && m.private_ip && !tracked.has(m.id)) {
+      if (!isSuspendedWithIp(m) || tracked.has(m.id)) continue;
+      if (this.warmCapacity() < this.deps.config.min) {
         this.free.push({ id: m.id, privateIp: m.private_ip });
+        tracked.add(m.id);
         adopted++;
+      } else if (this.booting === 0) {
+        surplus.push(m.id);
       }
     }
-    if (pruned > 0 || adopted > 0) {
-      this.log(`resync: pruned ${pruned} stale, adopted ${adopted} (free=${this.free.length})`);
+    const destroyedSurplus = await this.destroySurplus(surplus);
+    const destroyed = destroyedTracked + destroyedSurplus;
+    if (pruned > 0 || adopted > 0 || destroyed > 0) {
+      this.log(`resync: pruned ${pruned} stale, adopted ${adopted}, destroyed ${destroyed} surplus (free=${this.free.length})`);
     }
     await this.refill();
   }
@@ -18004,11 +18239,37 @@ var PoolManager = class {
   baseUrl(m) {
     return `http://[${m.privateIp}]:${this.deps.config.port}`;
   }
+  warmCapacity() {
+    return this.free.length + this.booting;
+  }
+  async rebalance(reason) {
+    await this.trimFreeSurplus(reason);
+    await this.refill();
+  }
+  async trimFreeSurplus(reason) {
+    const surplus = [];
+    while (this.free.length > this.deps.config.min) {
+      const machine = this.free.pop();
+      if (machine) surplus.push(machine.id);
+    }
+    const destroyed = await this.destroySurplus(surplus);
+    if (destroyed > 0) this.log(`${reason}: destroyed ${destroyed} surplus free machine(s)`);
+    return destroyed;
+  }
+  async destroySurplus(ids) {
+    let destroyed = 0;
+    for (const id of ids) {
+      if (await this.safeDestroy(id)) destroyed++;
+    }
+    return destroyed;
+  }
   async safeDestroy(id) {
     try {
       await this.deps.fly.destroy(id);
+      return true;
     } catch (err) {
       this.log(`destroy ${id} failed: ${errMsg2(err)}`);
+      return false;
     }
   }
 };
@@ -18027,6 +18288,9 @@ async function defaultPostRun(m, job, cfg) {
 function errMsg2(err) {
   return err instanceof Error ? err.message : String(err);
 }
+function isSuspendedWithIp(m) {
+  return (m.state === "suspended" || m.state === "suspending") && !!m.private_ip;
+}
 
 // src/pool/vault.ts
 import { createDecipheriv as createDecipheriv2 } from "crypto";
@@ -18954,16 +19218,17 @@ Usage:
   kody-engine preview-build --pr <N>                 [--cwd <path>] [--verbose|--quiet]
   kody-engine release --issue <N>                    [--cwd <path>] [--verbose|--quiet]
   kody-engine init                                   [--cwd <path>] [--verbose|--quiet]
-  kody-engine <executable>                           [--cwd <path>] [--verbose|--quiet]
+  kody-engine <action>                               [--cwd <path>] [--verbose|--quiet]
+  kody-engine exec <executable>                      [--cwd <path>] [--verbose|--quiet]
   kody-engine ci      [preflight flags \u2014 see: kody-engine ci --help]
   kody-engine chat    [chat flags \u2014 see: kody-engine chat --help]
   kody-engine stats   [--since 7d|--run <id>|--json|--cwd <path>]
   kody-engine help
   kody-engine version
 
-Each top-level command is a discovered executable under
-\`src/executables/<name>/profile.json\`. Drop in a new directory to add a new
-command; consumer repos can also provide their own executable profiles.
+Top-level work commands are duty actions. A duty owns the public action name
+and selects an implementation executable. \`exec <executable>\` is the low-level
+debug path for engine internals and migration compatibility.
 
 Exit codes:
   0   success (PR opened, verify passed \u2014 or resolve produced a merge commit)
@@ -19004,6 +19269,33 @@ function parseArgs(argv) {
     result.serverArgs = argv.slice(1).filter((a) => !a.startsWith("-"));
     return result;
   }
+  if (cmd === "exec") {
+    const executableName = argv[1];
+    if (!executableName) {
+      result.errors.push("exec requires an executable name");
+      return result;
+    }
+    if (!hasExecutable(executableName)) {
+      result.errors.push(`unknown executable: ${executableName}`);
+      return result;
+    }
+    result.command = "__executable__";
+    result.executableName = executableName;
+    result.cliArgs = parseGenericFlags(argv.slice(2));
+    if (typeof result.cliArgs.cwd === "string") result.cwd = result.cliArgs.cwd;
+    if (result.cliArgs.verbose === true) result.verbose = true;
+    if (result.cliArgs.quiet === true) result.quiet = true;
+    return result;
+  }
+  if (hasDutyAction(cmd)) {
+    result.command = "__duty__";
+    result.actionName = cmd;
+    result.cliArgs = parseGenericFlags(argv.slice(1));
+    if (typeof result.cliArgs.cwd === "string") result.cwd = result.cliArgs.cwd;
+    if (result.cliArgs.verbose === true) result.verbose = true;
+    if (result.cliArgs.quiet === true) result.quiet = true;
+    return result;
+  }
   if (hasExecutable(cmd)) {
     result.command = "__executable__";
     result.executableName = cmd;
@@ -19013,8 +19305,9 @@ function parseArgs(argv) {
     if (result.cliArgs.quiet === true) result.quiet = true;
     return result;
   }
-  const discovered = listExecutables().map((e) => e.name);
-  const available = ["ci", "chat", "stats", "help", "version", ...discovered];
+  const discoveredActions = listDutyActions().map((e) => e.action);
+  const discoveredExecutables = listExecutables().map((e) => `exec ${e.name}`);
+  const available = ["ci", "chat", "stats", "help", "version", ...discoveredActions, ...discoveredExecutables];
   result.errors.push(`unknown command: ${cmd} (available: ${available.join(", ")})`);
   return result;
 }
@@ -19104,6 +19397,48 @@ ${HELP_TEXT}`);
   }
   const cwd = args.cwd ?? process.cwd();
   const configlessCommands = /* @__PURE__ */ new Set(["init", "goal-scheduler"]);
+  if (args.command === "__duty__") {
+    const route = resolveDutyAction(args.actionName);
+    if (!route) {
+      process.stderr.write(`error: unknown duty action '${args.actionName}'
+`);
+      return 64;
+    }
+    const cliArgs = { ...route.cliArgs, ...args.cliArgs ?? {} };
+    const skipConfig2 = configlessCommands.has(route.executable);
+    try {
+      const result = await runJob(
+        {
+          action: route.action,
+          duty: route.duty,
+          executable: route.executable,
+          cliArgs,
+          target: numericTarget(cliArgs),
+          flavor: "instant"
+        },
+        {
+          cwd,
+          skipConfig: skipConfig2,
+          verbose: args.verbose,
+          quiet: args.quiet
+        }
+      );
+      if (result.exitCode !== 0 && result.reason) {
+        process.stderr.write(`error: ${result.reason}
+`);
+      }
+      return result.exitCode;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`[kody] ${args.actionName} crashed: ${msg}
+`);
+      if (err instanceof Error && err.stack) process.stderr.write(`${err.stack}
+`);
+      process.stdout.write(`PR_URL=FAILED: ${args.actionName} crashed: ${msg}
+`);
+      return 99;
+    }
+  }
   const skipConfig = configlessCommands.has(args.executableName ?? "");
   try {
     const result = await runExecutableChain(args.executableName, {
@@ -19129,6 +19464,14 @@ ${HELP_TEXT}`);
     return 99;
   }
 }
+function numericTarget(cliArgs) {
+  for (const key of ["issue", "pr"]) {
+    const raw = cliArgs[key];
+    const n = typeof raw === "number" ? raw : typeof raw === "string" ? parseInt(raw, 10) : Number.NaN;
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return void 0;
+}
 
 // bin/kody.ts
 main().then((code) => {

package/dist/duties/public-actions.json

@@ -0,0 +1,86 @@
+[
+  {
+    "name": "run",
+    "action": "run",
+    "executable": "run",
+    "describe": "Implement a GitHub issue end-to-end."
+  },
+  {
+    "name": "fix",
+    "action": "fix",
+    "executable": "fix",
+    "describe": "Apply review feedback to an existing PR."
+  },
+  {
+    "name": "fix-ci",
+    "action": "fix-ci",
+    "executable": "fix-ci",
+    "describe": "Fix a failing CI workflow on an existing PR."
+  },
+  {
+    "name": "resolve",
+    "action": "resolve",
+    "executable": "resolve",
+    "describe": "Resolve merge conflicts on an existing PR."
+  },
+  {
+    "name": "sync",
+    "action": "sync",
+    "executable": "sync",
+    "describe": "Merge the base branch into a PR branch."
+  },
+  {
+    "name": "merge",
+    "action": "merge",
+    "executable": "merge",
+    "describe": "Self-gating squash merge of a PR."
+  },
+  {
+    "name": "revert",
+    "action": "revert",
+    "executable": "revert",
+    "describe": "Revert one or more commits on a PR branch."
+  },
+  {
+    "name": "preview-build",
+    "action": "preview-build",
+    "executable": "preview-build",
+    "describe": "Build and publish a per-PR preview."
+  },
+  {
+    "name": "release",
+    "action": "release",
+    "executable": "release",
+    "describe": "Run the release flow."
+  },
+  {
+    "name": "release-prepare",
+    "action": "release-prepare",
+    "executable": "release-prepare",
+    "describe": "Prepare a release PR."
+  },
+  {
+    "name": "release-publish",
+    "action": "release-publish",
+    "executable": "release-publish",
+    "describe": "Publish a prepared release."
+  },
+  {
+    "name": "release-deploy",
+    "action": "release-deploy",
+    "executable": "release-deploy",
+    "describe": "Deploy or promote a release."
+  },
+  {
+    "name": "init",
+    "action": "init",
+    "executable": "init",
+    "describe": "Install Kody engine files in a repo."
+  },
+  {
+    "name": "worker-ask",
+    "action": "worker-ask",
+    "executable": "worker-ask",
+    "describe": "Run a staff member once against an inline request."
+  }
+]

package/dist/executables/types.ts

@@ -17,6 +17,12 @@ import type { Phase } from "../state.js"
 
 export interface Profile {
   name: string
+  /**
+   * Public action name owned by a duty. A user may type `@kody <action>`;
+   * dispatch resolves that action to the duty, then the duty selects the
+   * implementation executable. Absent → the duty slug/name is the action.
+   */
+  action?: string
   /**
    * Optional staff member this executable runs *as*. When set, the executor
    * loads `.kody/staff/<staff>.md` and injects that persona (authoritative
@@ -462,6 +468,8 @@ export type AnyScript = PreflightScript | PostflightScript
 export type JobFlavor = "instant" | "scheduled"
 
 export interface Job {
+  /** Public action the user/operator invoked. Mirrors the duty action. */
+  action?: string
   /** How: executable (profile) name to run. 0–1; omitted when intent is
    *  agent-only with no specific verb. */
   executable?: string

package/package.json

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