@kody-ade/kody-engine 0.4.233 → 0.4.235

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.233",
+      version: "0.4.235",
       description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
       license: "MIT",
       type: "module",
@@ -2385,21 +2385,6 @@ function getCompanyStoreExecutablesRoot() {
 function getCompanyStoreDutiesRoot() {
   return getCompanyStoreAssetRoot("duties");
 }
-function getBuiltinJobsRoot() {
-  const here = path8.dirname(new URL(import.meta.url).pathname);
-  const candidates = [
-    path8.join(here, "jobs"),
-    // dev: src/
-    path8.join(here, "..", "jobs"),
-    // built: dist/bin → dist/jobs
-    path8.join(here, "..", "src", "jobs")
-    // fallback
-  ];
-  for (const c of candidates) {
-    if (fs8.existsSync(c) && fs8.statSync(c).isDirectory()) return c;
-  }
-  return candidates[0];
-}
 function getBuiltinDutiesRoot() {
   const here = path8.dirname(new URL(import.meta.url).pathname);
   const candidates = [
@@ -2415,23 +2400,6 @@ function getBuiltinDutiesRoot() {
   }
   return candidates[0];
 }
-function listBuiltinJobs(root = getBuiltinJobsRoot()) {
-  if (!fs8.existsSync(root) || !fs8.statSync(root).isDirectory()) return [];
-  const out = [];
-  for (const ent of fs8.readdirSync(root, { withFileTypes: true })) {
-    if (ent.name.startsWith("_") || ent.name.startsWith(".")) continue;
-    const full = path8.join(root, ent.name);
-    if (ent.isDirectory()) {
-      const profilePath = path8.join(full, DUTY_PROFILE_FILE);
-      const bodyPath = path8.join(full, DUTY_BODY_FILE);
-      if (!fs8.existsSync(profilePath) || !fs8.statSync(profilePath).isFile()) continue;
-      if (!fs8.existsSync(bodyPath) || !fs8.statSync(bodyPath).isFile()) continue;
-      out.push({ slug: ent.name, dir: full, profilePath, bodyPath });
-    }
-  }
-  out.sort((a, b) => a.slug.localeCompare(b.slug));
-  return out;
-}
 function getExecutableRoots() {
   const storeRoot = getCompanyStoreExecutablesRoot();
   return [getProjectExecutablesRoot(), ...storeRoot ? [storeRoot] : [], getExecutablesRoot()];
@@ -2480,9 +2448,12 @@ function listDutyActions(projectDutiesRoot = getProjectDutiesRoot()) {
     out.push(action);
   };
   const roots = getDutyRoots(projectDutiesRoot);
+  const executableRoots = getExecutableRoots();
   for (const action of listFolderDutyActions(roots[0], "project-folder")) add(action);
+  for (const action of listExecutableDutyActions(executableRoots[0], "project-executable")) add(action);
   if (roots.length === 3) {
     for (const action of listFolderDutyActions(roots[1], "company-store")) add(action);
+    for (const action of listExecutableDutyActions(executableRoots[1], "company-store-executable")) add(action);
     for (const action of listBuiltinDutyActions(roots[2])) add(action);
   } else {
     for (const action of listBuiltinDutyActions(roots[1])) add(action);
@@ -2527,6 +2498,34 @@ function executableDeclaresInput(executable, inputName) {
 function isSafeName(name) {
   return /^[a-z][a-z0-9-]*$/.test(name) && !name.includes("..");
 }
+function listExecutableDutyActions(root, source) {
+  if (!fs8.existsSync(root) || !fs8.statSync(root).isDirectory()) return [];
+  const out = [];
+  for (const ent of fs8.readdirSync(root, { withFileTypes: true })) {
+    if (!ent.isDirectory() || !isSafeName(ent.name)) continue;
+    const profilePath = path8.join(root, ent.name, DUTY_PROFILE_FILE);
+    if (!fs8.existsSync(profilePath) || !fs8.statSync(profilePath).isFile()) continue;
+    try {
+      const raw = JSON.parse(fs8.readFileSync(profilePath, "utf-8"));
+      const action = typeof raw.action === "string" && raw.action.trim() ? raw.action.trim() : "";
+      if (!action) continue;
+      if (!PUBLIC_EXECUTABLE_ACTION_ROLES.has(String(raw.role))) continue;
+      if (!PUBLIC_EXECUTABLE_CAPABILITY_KINDS.has(String(raw.capabilityKind))) continue;
+      if (!Array.isArray(raw.inputs)) continue;
+      out.push({
+        action,
+        duty: ent.name,
+        executable: ent.name,
+        cliArgs: {},
+        source,
+        describe: typeof raw.describe === "string" ? raw.describe : void 0,
+        profilePath
+      });
+    } catch {
+    }
+  }
+  return out.sort((a, b) => a.action.localeCompare(b.action));
+}
 function listFolderDutyActions(root, source) {
   if (!fs8.existsSync(root) || !fs8.statSync(root).isDirectory()) return [];
   const out = [];
@@ -2607,11 +2606,14 @@ function parseGenericFlags(argv) {
   if (positional.length > 0) args._ = positional;
   return args;
 }
+var PUBLIC_EXECUTABLE_ACTION_ROLES, PUBLIC_EXECUTABLE_CAPABILITY_KINDS;
 var init_registry = __esm({
   "src/registry.ts"() {
     "use strict";
     init_companyStore();
     init_dutyFolders();
+    PUBLIC_EXECUTABLE_ACTION_ROLES = /* @__PURE__ */ new Set(["primitive", "orchestrator", "container", "watch", "utility"]);
+    PUBLIC_EXECUTABLE_CAPABILITY_KINDS = /* @__PURE__ */ new Set(["observe", "act", "verify"]);
   }
 });
 
@@ -3121,6 +3123,7 @@ function loadProfile(profilePath) {
       action: typeof r.action === "string" && r.action.trim() ? r.action.trim() : void 0,
       executable: execRef,
       describe: typeof r.describe === "string" ? r.describe : base.describe,
+      capabilityKind: parseCapabilityKind(profilePath, r.capabilityKind) ?? base.capabilityKind,
       staff: typeof r.staff === "string" && r.staff.trim() ? r.staff.trim() : base.staff,
       every: typeof r.every === "string" && r.every.trim() ? r.every.trim() : void 0,
       dutyTools: parseStringArray(r.dutyTools ?? r.tools) ?? base.dutyTools,
@@ -3165,6 +3168,7 @@ function loadProfile(profilePath) {
     action: typeof r.action === "string" && r.action.trim() ? r.action.trim() : void 0,
     executable: void 0,
     describe: typeof r.describe === "string" ? r.describe : "",
+    capabilityKind: parseCapabilityKind(profilePath, r.capabilityKind),
     // Optional persona to run as. Empty/blank string → undefined (no persona).
     staff: typeof r.staff === "string" && r.staff.trim() ? r.staff.trim() : void 0,
     // Optional recurrence cadence (scheduled duty). Blank → undefined (on-demand).
@@ -3255,6 +3259,13 @@ function requireString(p, r, key) {
   }
   return v;
 }
+function parseCapabilityKind(p, raw) {
+  if (raw === void 0 || raw === null || raw === "") return void 0;
+  if (typeof raw !== "string" || !VALID_CAPABILITY_KINDS.has(raw)) {
+    throw new ProfileError(p, `"capabilityKind" must be one of: observe | act | verify`);
+  }
+  return raw;
+}
 function parseStringArray(raw) {
   if (!Array.isArray(raw)) return void 0;
   const values = raw.map((t) => String(t).trim()).filter(Boolean);
@@ -3331,6 +3342,17 @@ function parseCliTools(p, raw) {
   if (!Array.isArray(raw)) throw new ProfileError(p, `"cliTools" must be an array or absent`);
   const out = [];
   for (const [i, item] of raw.entries()) {
+    if (typeof item === "string" && item.trim()) {
+      const name = item.trim();
+      out.push({
+        name,
+        install: { required: false, checkCommand: `command -v ${name}` },
+        verify: `command -v ${name}`,
+        usage: "",
+        allowedUses: []
+      });
+      continue;
+    }
     if (!item || typeof item !== "object") {
       throw new ProfileError(p, `cliTools[${i}] must be an object`);
     }
@@ -3490,7 +3512,7 @@ function parseScriptList(p, key, raw) {
   }
   return out;
 }
-var VALID_INPUT_TYPES, VALID_PERMISSION_MODES, VALID_ROLES, VALID_CONTAINER_CHILD_TARGETS, VALID_PHASES, KNOWN_PROFILE_KEYS;
+var VALID_INPUT_TYPES, VALID_PERMISSION_MODES, VALID_ROLES, VALID_CONTAINER_CHILD_TARGETS, VALID_PHASES, VALID_CAPABILITY_KINDS, KNOWN_PROFILE_KEYS;
 var init_profile = __esm({
   "src/profile.ts"() {
     "use strict";
@@ -3506,6 +3528,7 @@ var init_profile = __esm({
     VALID_ROLES = /* @__PURE__ */ new Set(["primitive", "orchestrator", "container", "watch", "utility"]);
     VALID_CONTAINER_CHILD_TARGETS = /* @__PURE__ */ new Set(["issue", "pr"]);
     VALID_PHASES = /* @__PURE__ */ new Set(["research", "planning", "implementing", "reviewing", "shipped", "failed", "idle"]);
+    VALID_CAPABILITY_KINDS = /* @__PURE__ */ new Set(["observe", "act", "verify"]);
     KNOWN_PROFILE_KEYS = /* @__PURE__ */ new Set([
       "name",
       "action",
@@ -3515,6 +3538,7 @@ var init_profile = __esm({
       "dutyTools",
       "tools",
       "mentions",
+      "capabilityKind",
       "stage",
       "readsFrom",
       "writesTo",
@@ -4746,6 +4770,125 @@ var init_dutyReport = __esm({
   }
 });
 
+// src/dutyResult.ts
+function parseDutyResultsFromText(text) {
+  const results = [];
+  for (const match of text.matchAll(RESULT_LINE)) {
+    const raw = match[1]?.trim();
+    if (!raw) continue;
+    try {
+      const parsed = parseDutyResult(JSON.parse(raw));
+      if (parsed) results.push(parsed);
+    } catch {
+    }
+  }
+  return results;
+}
+function parseDutyResult(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const obj = raw;
+  if (obj.version !== 1) return null;
+  if (!isDutyResultStatus(obj.status)) return null;
+  const summary = typeof obj.summary === "string" ? obj.summary.trim() : "";
+  if (!summary) return null;
+  const facts = parseFacts2(obj.facts);
+  if (!facts) return null;
+  const artifacts = parseArtifacts(obj.artifacts);
+  if (!artifacts) return null;
+  return {
+    version: 1,
+    status: obj.status,
+    summary,
+    facts,
+    artifacts
+  };
+}
+function applyDutyResultToObjectiveState(state, result, evidenceOverride) {
+  const priorFacts = parseFacts2(state.extra.facts) ?? {};
+  const nextFacts = { ...priorFacts };
+  for (const [key, value] of Object.entries(result.facts)) {
+    if (CONTROL_FACT_KEYS2.has(key)) continue;
+    nextFacts[key] = value;
+  }
+  const evidence = evidenceOverride || (typeof nextFacts.pendingEvidence === "string" ? nextFacts.pendingEvidence : "");
+  if (evidence) {
+    if (result.status === "pass") nextFacts[evidence] = true;
+    if (result.status === "fail" || result.status === "blocked") nextFacts[evidence] = false;
+    if ((result.status === "pass" || result.status === "fail" || result.status === "blocked") && nextFacts.pendingEvidence === evidence) {
+      delete nextFacts.pendingEvidence;
+    }
+  }
+  const blockers = parseStringArray2(state.extra.blockers) ?? [];
+  if ((result.status === "fail" || result.status === "blocked") && !blockers.includes(result.summary)) {
+    blockers.push(result.summary);
+  }
+  return {
+    ...state,
+    extra: {
+      ...state.extra,
+      facts: nextFacts,
+      blockers,
+      lastDutyResult: {
+        status: result.status,
+        summary: result.summary,
+        facts: result.facts,
+        artifacts: result.artifacts
+      }
+    }
+  };
+}
+function isDutyResultStatus(value) {
+  return typeof value === "string" && STATUSES.has(value);
+}
+function parseFacts2(raw) {
+  if (raw === void 0) return {};
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const facts = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (!key.trim()) return null;
+    if (CONTROL_FACT_KEYS2.has(key)) continue;
+    facts[key] = value;
+  }
+  return facts;
+}
+function parseStringArray2(raw) {
+  if (!Array.isArray(raw)) return null;
+  const out = [];
+  for (const item of raw) {
+    if (typeof item !== "string") return null;
+    out.push(item);
+  }
+  return out;
+}
+function parseArtifacts(raw) {
+  if (raw === void 0) return [];
+  if (!Array.isArray(raw)) return null;
+  const artifacts = [];
+  for (const item of raw) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return null;
+    const rawArtifact = item;
+    const label = typeof rawArtifact.label === "string" ? rawArtifact.label.trim() : "";
+    const url = typeof rawArtifact.url === "string" ? rawArtifact.url.trim() : "";
+    const artifactPath = typeof rawArtifact.path === "string" ? rawArtifact.path.trim() : "";
+    if (!label || !url && !artifactPath) return null;
+    artifacts.push({
+      label,
+      ...url ? { url } : {},
+      ...artifactPath ? { path: artifactPath } : {}
+    });
+  }
+  return artifacts;
+}
+var RESULT_LINE, STATUSES, CONTROL_FACT_KEYS2;
+var init_dutyResult = __esm({
+  "src/dutyResult.ts"() {
+    "use strict";
+    RESULT_LINE = /^KODY_DUTY_RESULT=(.+)$/gm;
+    STATUSES = /* @__PURE__ */ new Set(["pass", "fail", "blocked", "changed", "noop"]);
+    CONTROL_FACT_KEYS2 = /* @__PURE__ */ new Set(["blockers", "destination", "duties", "route", "stage", "state"]);
+  }
+});
+
 // src/lifecycleLabels.ts
 function groupOf(label) {
   const idx = label.indexOf(":");
@@ -6738,49 +6881,88 @@ function collectReports(raw, agentResult) {
   const out = [];
   if (Array.isArray(raw)) {
     for (const item of raw) {
-      if (isDutyReport(item)) out.push(item);
+      const parsed = parseDutyReport(item);
+      if (parsed) out.push(parsed);
     }
   }
   if (agentResult?.finalText) out.push(...parseDutyReportsFromText(agentResult.finalText));
   return out;
 }
-function isDutyReport(raw) {
-  return !!raw && typeof raw === "object" && !Array.isArray(raw) && !!raw.target && (raw.target.type === "goal" || raw.target.type === "task" || raw.target.type === "duty") && typeof raw.target.id === "string";
+function collectResults(raw, agentResult) {
+  const out = [];
+  if (Array.isArray(raw)) {
+    for (const item of raw) {
+      const parsed = parseDutyResult(item);
+      if (parsed) out.push(parsed);
+    }
+  }
+  if (agentResult?.finalText) out.push(...parseDutyResultsFromText(agentResult.finalText));
+  return out;
 }
-function describeMessage(report) {
-  const keys = [
-    ...Object.keys(report.evidence ?? {}).map((key) => `evidence:${key}`),
-    ...Object.keys(report.facts ?? {}).map((key) => `fact:${key}`)
-  ];
-  return `chore(goals): apply duty report for ${report.target.id}${keys.length ? ` (${keys.join(", ")})` : ""}`;
+function groupGoalReports(reports) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const report of reports) {
+    if (report.target.type !== "goal") continue;
+    const list = grouped.get(report.target.id) ?? [];
+    list.push(report);
+    grouped.set(report.target.id, list);
+  }
+  return grouped;
+}
+function describeMessage(goalId, reports, results) {
+  const pieces = [];
+  if (reports && reports.length > 0) pieces.push(`report=${reports.length}`);
+  if (results.length > 0) pieces.push(`result=${results.map((result) => result.status).join(",")}`);
+  return `Apply duty output to ${goalId}${pieces.length > 0 ? ` (${pieces.join("; ")})` : ""}`;
 }
 var applyDutyReports;
 var init_applyDutyReports = __esm({
   "src/scripts/applyDutyReports.ts"() {
     "use strict";
     init_dutyReport();
+    init_dutyResult();
     init_state2();
     init_stateStore();
     applyDutyReports = async (ctx, _profile, agentResult) => {
       const reports = collectReports(ctx.data.dutyReports, agentResult);
-      if (reports.length === 0) return;
+      const results = collectResults(ctx.data.dutyResults, agentResult);
+      const resultGoalId = typeof ctx.args.goal === "string" && ctx.args.goal.length > 0 ? ctx.args.goal : null;
+      if (reports.length === 0 && (results.length === 0 || !resultGoalId)) return;
       const owner = ctx.config.github?.owner;
       const repo = ctx.config.github?.repo;
       if (!owner || !repo) {
         process.stderr.write("[kody duty-report] missing github owner/repo; cannot apply reports\n");
         return;
       }
-      const goalReports = reports.filter((report) => report.target.type === "goal");
-      for (const report of goalReports) {
-        const prior = fetchGoalState(owner, repo, report.target.id, ctx.cwd);
+      const reportsByGoal = groupGoalReports(reports);
+      const goalIds = new Set(reportsByGoal.keys());
+      if (results.length > 0 && resultGoalId) goalIds.add(resultGoalId);
+      for (const goalId of goalIds) {
+        const prior = fetchGoalState(owner, repo, goalId, ctx.cwd);
         if (!prior) {
-          process.stderr.write(`[kody duty-report] goal ${report.target.id} missing on kody-state; report skipped
+          process.stderr.write(`[kody duty-report] goal ${goalId} missing on kody-state; report skipped
 `);
           continue;
         }
-        const next = applyDutyReportToGoalState(prior, report);
+        let next = prior;
+        for (const report of reportsByGoal.get(goalId) ?? []) {
+          next = applyDutyReportToGoalState(next, report);
+        }
+        if (goalId === resultGoalId) {
+          const evidence = typeof ctx.args.evidence === "string" && ctx.args.evidence.length > 0 ? ctx.args.evidence : void 0;
+          for (const result of results) {
+            next = applyDutyResultToObjectiveState(next, result, evidence);
+          }
+        }
         if (serializeGoalState(next) === serializeGoalState(prior)) continue;
-        putGoalState(owner, repo, report.target.id, { ...next, updatedAt: nowIso() }, describeMessage(report), ctx.cwd);
+        putGoalState(
+          owner,
+          repo,
+          goalId,
+          { ...next, updatedAt: nowIso() },
+          describeMessage(goalId, reportsByGoal.get(goalId), results),
+          ctx.cwd
+        );
       }
     };
   }
@@ -9900,26 +10082,6 @@ function performInit(cwd, force) {
     fs31.writeFileSync(workflowPath, WORKFLOW_TEMPLATE);
     wrote.push(".github/workflows/kody.yml");
   }
-  const builtinJobs = listBuiltinJobs();
-  if (builtinJobs.length > 0) {
-    const jobsDir = path30.join(cwd, ".kody", "duties");
-    fs31.mkdirSync(jobsDir, { recursive: true });
-    for (const job of builtinJobs) {
-      const targetDir = path30.join(jobsDir, job.slug);
-      const relProfile = path30.join(".kody", "duties", job.slug, "profile.json");
-      const relBody = path30.join(".kody", "duties", job.slug, "duty.md");
-      if (fs31.existsSync(targetDir) && fs31.existsSync(path30.join(targetDir, "profile.json")) && !force) {
-        skipped.push(relProfile);
-        skipped.push(relBody);
-        continue;
-      }
-      fs31.mkdirSync(targetDir, { recursive: true });
-      fs31.writeFileSync(path30.join(targetDir, "profile.json"), fs31.readFileSync(job.profilePath, "utf-8"));
-      fs31.writeFileSync(path30.join(targetDir, "duty.md"), fs31.readFileSync(job.bodyPath, "utf-8"));
-      wrote.push(relProfile);
-      wrote.push(relBody);
-    }
-  }
   const staffDir = path30.join(cwd, ".kody", "staff");
   const staffPath = path30.join(staffDir, "kody.md");
   if (fs31.existsSync(staffPath) && !force) {
@@ -9985,7 +10147,7 @@ jobs:
           python-version: "3.12"
       - env:
           GH_TOKEN: \${{ secrets.KODY_TOKEN || github.token }}
-        run: npx -y -p @kody-ade/kody-engine@latest kody-engine ${name}
+        run: npx -y -p @kody-ade/kody-engine@latest kody-engine exec ${name}
 `;
 }
 var WORKFLOW_TEMPLATE, DEFAULT_STAFF_PERSONA, initFlow;
@@ -14432,6 +14594,26 @@ function isMutatingPostflight(scriptName) {
 function shouldBlockMutatingPostflight(scriptName, exitCode) {
   return isMutatingPostflight(scriptName) && (exitCode ?? 0) !== 0;
 }
+function collectShellSideChannels(ctx, stdout) {
+  if (/^KODY_SKIP_AGENT=true\s*$/m.test(stdout)) {
+    ctx.skipAgent = true;
+    if (ctx.output.exitCode === void 0) ctx.output.exitCode = 0;
+  }
+  const prUrlMatch = stdout.match(/^KODY_PR_URL=(.+)$/m);
+  if (prUrlMatch?.[1]) ctx.output.prUrl = prUrlMatch[1].trim();
+  const reasonMatch = stdout.match(/^KODY_REASON=(.+)$/m);
+  if (reasonMatch?.[1]) ctx.output.reason = reasonMatch[1].trim();
+  const dutyReports = parseDutyReportsFromText(stdout);
+  if (dutyReports.length > 0) {
+    const prior = Array.isArray(ctx.data.dutyReports) ? ctx.data.dutyReports : [];
+    ctx.data.dutyReports = [...prior, ...dutyReports];
+  }
+  const dutyResults = parseDutyResultsFromText(stdout);
+  if (dutyResults.length > 0) {
+    const prior = Array.isArray(ctx.data.dutyResults) ? ctx.data.dutyResults : [];
+    ctx.data.dutyResults = [...prior, ...dutyResults];
+  }
+}
 function operatorRequestBlock(why) {
   const text = why.trim();
   if (!text) return null;
@@ -15136,19 +15318,7 @@ async function runShellEntry(entry, ctx, profile) {
     ctx.output.reason = `shell '${shellName}' failed to spawn: ${result.spawnErr.message}`;
     return;
   }
-  if (/^KODY_SKIP_AGENT=true\s*$/m.test(stdout)) {
-    ctx.skipAgent = true;
-    if (ctx.output.exitCode === void 0) ctx.output.exitCode = 0;
-  }
-  const prUrlMatch = stdout.match(/^KODY_PR_URL=(.+)$/m);
-  if (prUrlMatch?.[1]) ctx.output.prUrl = prUrlMatch[1].trim();
-  const reasonMatch = stdout.match(/^KODY_REASON=(.+)$/m);
-  if (reasonMatch?.[1]) ctx.output.reason = reasonMatch[1].trim();
-  const dutyReports = parseDutyReportsFromText(stdout);
-  if (dutyReports.length > 0) {
-    const prior = Array.isArray(ctx.data.dutyReports) ? ctx.data.dutyReports : [];
-    ctx.data.dutyReports = [...prior, ...dutyReports];
-  }
+  collectShellSideChannels(ctx, stdout);
   if (timedOut) {
     ctx.skipAgent = true;
     const seconds = Math.round(timeoutMs / 1e3);
@@ -15199,6 +15369,7 @@ var init_executor = __esm({
     init_container();
     init_discipline();
     init_dutyReport();
+    init_dutyResult();
     init_events();
     init_lifecycleLabels();
     init_litellm();
@@ -15269,7 +15440,8 @@ async function runJob(job, base) {
   const resolvedDuty = action ? resolveDutyAction(action, projectDutiesRoot) : null;
   const dutyIdentity = valid.duty ?? resolvedDuty?.duty;
   const dutyContext = loadDutyContext(dutyIdentity, base.cwd);
-  if (!resolvedDuty && !dutyContext) {
+  const explicitExecutableOnly = valid.executable !== void 0 && (valid.action === void 0 || valid.action === valid.executable) && (valid.duty === void 0 || valid.duty === valid.executable);
+  if (!resolvedDuty && !dutyContext && !explicitExecutableOnly) {
     throw new InvalidJobError(`job duty not found: ${action ?? valid.duty ?? "<none>"}`);
   }
   const dutySelectedExecutable = resolvedDuty?.executable ?? dutyContext?.config.executable ?? dutyContext?.config.executables?.[0] ?? (dutyContext?.config.tickScript ? "duty-tick-scripted" : void 0);
@@ -19882,6 +20054,7 @@ Usage:
   kody-engine release --issue <N>                    [--cwd <path>] [--verbose|--quiet]
   kody-engine init                                   [--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>]
@@ -19889,7 +20062,8 @@ Usage:
   kody-engine version
 
 Top-level work commands are duty actions. A duty owns the public action name
-and selects an implementation executable.
+and selects an implementation executable. Use exec only for internal executable
+profiles such as scheduled helpers.
 
 Exit codes:
   0   success (PR opened, verify passed \u2014 or resolve produced a merge commit)
@@ -19920,6 +20094,24 @@ function parseArgs(argv) {
   if (cmd === "stats") {
     return { ...result, command: "stats", statsArgv: argv.slice(1) };
   }
+  if (cmd === "exec") {
+    const executableName = argv[1];
+    if (!executableName || executableName.startsWith("-")) {
+      result.errors.push("exec requires an executable name");
+      return result;
+    }
+    if (!resolveExecutable(executableName)) {
+      result.errors.push(`unknown executable: ${executableName}`);
+      return result;
+    }
+    result.command = "__exec__";
+    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;
+  }
   const SERVER_VERBS = /* @__PURE__ */ new Set(["serve", "pool-serve", "runner-serve", "brain-serve", "brain-proxy", "mcp-http-server"]);
   if (SERVER_VERBS.has(cmd)) {
     result.command = "server";
@@ -19940,7 +20132,7 @@ function parseArgs(argv) {
     return result;
   }
   const discoveredActions = listDutyActions().map((e) => e.action);
-  const available = ["ci", "chat", "stats", "help", "version", ...discoveredActions];
+  const available = ["ci", "chat", "stats", "exec", "help", "version", ...discoveredActions];
   result.errors.push(`unknown command: ${cmd} (available: ${available.join(", ")})`);
   return result;
 }
@@ -20072,7 +20264,44 @@ ${HELP_TEXT}`);
       return 99;
     }
   }
-  process.stderr.write("error: command did not resolve to a duty\n");
+  if (args.command === "__exec__") {
+    const executable = args.executableName;
+    const cliArgs = args.cliArgs ?? {};
+    const skipConfig = configlessCommands.has(executable);
+    try {
+      const result = await runJob(
+        {
+          action: executable,
+          duty: executable,
+          executable,
+          cliArgs,
+          target: numericTarget(cliArgs),
+          flavor: "instant"
+        },
+        {
+          cwd,
+          skipConfig,
+          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] ${executable} crashed: ${msg}
+`);
+      if (err instanceof Error && err.stack) process.stderr.write(`${err.stack}
+`);
+      process.stdout.write(`PR_URL=FAILED: ${executable} crashed: ${msg}
+`);
+      return 99;
+    }
+  }
+  process.stderr.write("error: command did not resolve to a duty or executable\n");
   return 64;
 }
 function numericTarget(cliArgs) {

package/dist/executables/types.ts

@@ -15,6 +15,8 @@ import type { Phase } from "../state.js"
 // Profile shape (mirrors the JSON on disk).
 // ────────────────────────────────────────────────────────────────────────────
 
+export type CapabilityKind = "observe" | "act" | "verify"
+
 export interface Profile {
   name: string
   /**
@@ -33,6 +35,11 @@ export interface Profile {
    */
   staff?: string
   describe: string
+  /**
+   * Author-facing capability promise for a duty/executable. This classifies the
+   * shape of result it should return; it does not change executor control flow.
+   */
+  capabilityKind?: CapabilityKind
   /**
    * Semantic role — what this executable IS, not when it runs.
    *   - primitive:    single-step agent executor (flow → agent → verify → commit → PR).
@@ -390,6 +397,58 @@ export interface OutputContract {
   }
 }
 
+export interface CapabilityAlert {
+  level?: "info" | "warning" | "error"
+  message: string
+}
+
+export interface CapabilitySuggestedAction {
+  action: string
+  args?: Record<string, unknown>
+  reason?: string
+}
+
+export interface CapabilityResourceRef {
+  type: string
+  id?: string | number
+  number?: number
+  url?: string
+  name?: string
+}
+
+export interface CapabilityEvidenceItem {
+  source?: string
+  message: string
+  url?: string
+}
+
+export interface ObserveResult {
+  kind: "observe"
+  facts?: Record<string, unknown>
+  alerts?: CapabilityAlert[]
+  suggestedActions?: CapabilitySuggestedAction[]
+  evidence?: Record<string, unknown>
+}
+
+export interface ActResult {
+  kind: "act"
+  status: "created" | "changed" | "triggered" | "skipped" | "failed"
+  changedResources?: CapabilityResourceRef[]
+  createdResources?: CapabilityResourceRef[]
+  actionResult?: Record<string, unknown>
+  evidence?: Record<string, unknown>
+}
+
+export interface VerifyResult {
+  kind: "verify"
+  passed: boolean
+  evidence?: CapabilityEvidenceItem[]
+  blockers?: string[]
+  facts?: Record<string, unknown>
+}
+
+export type CapabilityResult = ObserveResult | ActResult | VerifyResult
+
 // ────────────────────────────────────────────────────────────────────────────
 // Run-time context passed to every script.
 // ────────────────────────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine",
-  "version": "0.4.233",
+  "version": "0.4.235",
   "description": "kody — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   "license": "MIT",
   "type": "module",
@@ -12,6 +12,26 @@
     "templates",
     "kody.config.schema.json"
   ],
+  "scripts": {
+    "kody:run": "tsx bin/kody.ts",
+    "serve": "tsx bin/kody.ts serve",
+    "serve:vscode": "tsx bin/kody.ts serve vscode",
+    "serve:claude": "tsx bin/kody.ts serve claude",
+    "build": "tsup && node scripts/copy-assets.cjs",
+    "check:modularity": "tsx scripts/check-script-modularity.ts",
+    "pretest": "pnpm check:modularity",
+    "test": "vitest run tests/unit tests/int --coverage",
+    "posttest": "tsx scripts/check-coverage-floor.ts",
+    "test:smoke": "vitest run tests/smoke --no-coverage",
+    "test:e2e": "vitest run tests/e2e --no-coverage",
+    "test:all": "vitest run tests --no-coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "format": "biome format --write",
+    "brain:publish": "docker buildx build --platform linux/amd64 -f runner/Dockerfile.brain -t ghcr.io/${KODY_BRAIN_GHCR_OWNER:-aharonyaircohen}/kody-brain:latest --push runner",
+    "prepublishOnly": "pnpm typecheck && vitest run tests/unit tests/int --no-coverage && pnpm build"
+  },
   "dependencies": {
     "@actions/cache": "^6.0.0",
     "@anthropic-ai/claude-agent-sdk": "0.2.119",
@@ -35,24 +55,5 @@
     "url": "git+https://github.com/aharonyaircohen/kody-engine.git"
   },
   "homepage": "https://github.com/aharonyaircohen/kody-engine",
-  "bugs": "https://github.com/aharonyaircohen/kody-engine/issues",
-  "scripts": {
-    "kody:run": "tsx bin/kody.ts",
-    "serve": "tsx bin/kody.ts serve",
-    "serve:vscode": "tsx bin/kody.ts serve vscode",
-    "serve:claude": "tsx bin/kody.ts serve claude",
-    "build": "tsup && node scripts/copy-assets.cjs",
-    "check:modularity": "tsx scripts/check-script-modularity.ts",
-    "pretest": "pnpm check:modularity",
-    "test": "vitest run tests/unit tests/int --coverage",
-    "posttest": "tsx scripts/check-coverage-floor.ts",
-    "test:smoke": "vitest run tests/smoke --no-coverage",
-    "test:e2e": "vitest run tests/e2e --no-coverage",
-    "test:all": "vitest run tests --no-coverage",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check",
-    "lint:fix": "biome check --write",
-    "format": "biome format --write",
-    "brain:publish": "docker buildx build --platform linux/amd64 -f runner/Dockerfile.brain -t ghcr.io/${KODY_BRAIN_GHCR_OWNER:-aharonyaircohen}/kody-brain:latest --push runner"
-  }
-}
+  "bugs": "https://github.com/aharonyaircohen/kody-engine/issues"
+}

package/dist/jobs/watch-stale-prs/duty.md

@@ -1,95 +0,0 @@
-{{dutyReference}}
-
-You are **{{staffTitle}}** (staff `{{staffSlug}}`), running the **watch-stale-prs** duty — a weekly digest of open PRs that haven't been touched in a while. You do **not** touch code, do **not** commit, and do **not** edit files. You coordinate by inspecting GitHub state via `gh` and writing a single report file at `.kody/reports/{{dutySlug}}.md`.
-
-## Who you are — staff persona (authoritative identity)
-
-The duty assigns you, staff **`{{staffSlug}}`**, as its executor. This persona defines *who* runs the duty: your authority, doctrine, voice, and hard limits. Where the persona's restrictions are stricter than the duty body, **the persona wins** — a duty can never grant you authority your staff persona withholds.
-
-{{workerPersona}}
-
-## The duty
-
-Slug **`{{dutySlug}}`** — *{{dutyTitle}}*, assigned to staff **`{{staffSlug}}`**, running on executable **`{{executableSlug}}`**. Cadence is enforced by the engine via the `every: 7d` profile field — this duty only fires once per 7 days regardless of how often `duty-scheduler` wakes. No prose cadence guard needed.
-
-**Addressing the operator.** When the duty tells you to @-mention the operator, the exact handle(s) to use are: {{mentions}}. Copy that string **verbatim** — never invent, abbreviate, guess, or retype a GitHub username. If the line above is blank, the duty declared no operator; post without a mention.
-
-### What "stale" means
-
-Find every open PR untouched for **≥ 7 days** and write a report listing them, sorted by staleness (oldest first). When there are no stale PRs, write a short "all clear" report so operators know the check ran.
-
-A PR is stale if:
-
-- `state` is `OPEN`, AND
-- `updatedAt` is more than 7 days before now.
-
-Use `gh pr list --state open --limit 100 --json number,title,url,updatedAt,author` to enumerate. Filter and sort client-side; do not call `gh` once per PR.
-
-### Report shape
-
-Write to `.kody/reports/watch-stale-prs.md`. Overwrite each run.
-
-When stale PRs exist:
-
-```markdown
-# Stale PRs — <ISO date>
-
-🟡 <N> PR(s) untouched for > 7 days.
-
-| # | Title | Author | Days stale | Updated |
-|---|-------|--------|------------|---------|
-| [#123](url) | <title> | @user | 14 | 2026-04-25 |
-| ... | | | | |
-```
-
-When none:
-
-```markdown
-# Stale PRs — <ISO date>
-
-🟢 No open PRs untouched for more than 7 days.
-```
-
-Truncate to the 50 oldest if the list is longer; append a final line
-`> … and N more not shown`.
-
-## Allowed Commands
-
-- `gh pr list --state open --limit 100 --json number,title,url,updatedAt,author`
-- `gh api -X GET /repos/{owner}/{repo}/contents/.kody/reports/watch-stale-prs.md`
-  — only to fetch the existing file's `sha` for an update.
-- `gh api -X PUT /repos/{owner}/{repo}/contents/.kody/reports/watch-stale-prs.md`
-  — to write the report (base64-encoded `content`, `message`, and `sha`
-  when updating). This is the **only** permitted write path for this job.
-
-## Restrictions
-
-- Never edit, create, or delete any other file in the working tree.
-- Never `git commit`, `git push`, or open a PR.
-- Never post comments on PRs or issues; the report file is the only
-  output channel.
-- Never call `gh` per-PR — one `pr list` is enough.
-
-## State
-
-`cursor`: always `"idle"` — this job has no phases; each fire is a
-one-shot report write.
-
-`data`:
-
-- `lastStaleCount` (number) — how many stale PRs were in the most recent
-  report. Diagnostic only; the engine ignores it.
-
-(Engine-managed fields like `lastFiredAt` live under `data` automatically;
-do not write or rely on them from the prompt.)
-
-`done`: always `false` — this job is evergreen.
-
-## What to do on this tick
-
-1. **Check `done`.** If the prior state has `done: true`, emit the same state back unchanged and exit without any action.
-2. **Enumerate stale PRs** with `gh pr list`.
-3. **Write the report** to `.kody/reports/{{dutySlug}}.md` via `gh api -X PUT`.
-4. **Submit the new state** by calling the `submit_state` tool with `cursor: "idle"`, the `lastStaleCount` in `data`, and `done: false`.
-
-The duty cadence (`every: 7d`) is enforced by the engine — do not re-arm it from the prompt.

package/dist/jobs/watch-stale-prs/profile.json

@@ -1,46 +0,0 @@
-{
-  "name": "watch-stale-prs",
-  "role": "primitive",
-  "describe": "Weekly digest of open PRs that haven't been touched in a while. Writes a markdown report at .kody/reports/watch-stale-prs.md (surfaced by the dashboard's /reports page).",
-  "kind": "oneshot",
-  "staff": "kody",
-  "every": "7d",
-  "inputs": [],
-  "claudeCode": {
-    "model": "inherit",
-    "permissionMode": "default",
-    "maxTurns": 100,
-    "maxThinkingTokens": null,
-    "systemPromptAppend": null,
-    "enableSubmitTool": true,
-    "tools": ["Bash", "Read", "mcp__kody-submit"],
-    "hooks": [],
-    "skills": [],
-    "commands": [],
-    "subagents": [],
-    "plugins": [],
-    "mcpServers": []
-  },
-  "cliTools": [
-    {
-      "name": "gh",
-      "install": {
-        "required": true,
-        "checkCommand": "command -v gh"
-      },
-      "verify": "gh auth status",
-      "usage": "Use `gh` for all GitHub actions: `gh pr list --state open --limit 100 --json number,title,url,updatedAt,author` to enumerate candidate PRs, `gh api -X GET /repos/{owner}/{repo}/contents/.kody/reports/watch-stale-prs.md` to fetch the existing file's `sha` for an update, `gh api -X PUT /repos/{owner}/{repo}/contents/.kody/reports/watch-stale-prs.md` to write the report (base64-encoded `content`, `message`, and `sha` when updating). NEVER edit files in the working tree.",
-      "allowedUses": ["pr", "api"]
-    }
-  ],
-  "scripts": {
-    "preflight": [
-      { "script": "loadDutyState" },
-      { "script": "composePrompt" }
-    ],
-    "postflight": [
-      { "script": "parseJobStateFromAgentResult", "with": { "fenceLabel": "kody-job-next-state" } },
-      { "script": "writeJobStateFile" }
-    ]
-  }
-}