@kody-ade/kody-engine 0.3.69 → 0.3.70-beta.2

package/dist/bin/kody.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.3.69",
+  version: "0.3.70-beta.2",
   description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -1122,7 +1122,8 @@ import * as fs8 from "fs";
 import * as path7 from "path";
 var VALID_INPUT_TYPES = /* @__PURE__ */ new Set(["int", "string", "bool", "enum"]);
 var VALID_PERMISSION_MODES = /* @__PURE__ */ new Set(["default", "acceptEdits", "plan", "bypassPermissions"]);
-var VALID_ROLES = /* @__PURE__ */ new Set(["primitive", "orchestrator", "watch", "utility"]);
+var VALID_ROLES = /* @__PURE__ */ new Set(["primitive", "orchestrator", "container", "watch", "utility"]);
+var VALID_CONTAINER_CHILD_TARGETS = /* @__PURE__ */ new Set(["issue", "pr"]);
 var VALID_PHASES = /* @__PURE__ */ new Set(["research", "planning", "implementing", "reviewing", "shipped", "failed", "idle"]);
 var ProfileError = class extends Error {
   constructor(profilePath, message) {
@@ -1162,6 +1163,7 @@ function loadProfile(profilePath) {
     }
     phase = r.phase;
   }
+  const children = parseContainerChildren(profilePath, role, r.children);
   const profile = {
     name: requireString(profilePath, r, "name"),
     describe: typeof r.describe === "string" ? r.describe : "",
@@ -1176,6 +1178,7 @@ function loadProfile(profilePath) {
     outputContract: r.outputContract,
     inputArtifacts: parseInputArtifacts(profilePath, r.input),
     outputArtifacts: parseOutputArtifacts(profilePath, r.output),
+    children,
     dir: path7.dirname(profilePath)
   };
   return profile;
@@ -1336,6 +1339,45 @@ function parseOutputArtifacts(p, raw) {
   }
   return out;
 }
+function parseContainerChildren(p, role, raw) {
+  const isContainer = role === "container";
+  const present = raw !== void 0 && raw !== null;
+  if (!isContainer) {
+    if (!present) return void 0;
+    if (Array.isArray(raw) && raw.length === 0) return void 0;
+    throw new ProfileError(p, `"children" is only allowed when role === "container"`);
+  }
+  if (!present) {
+    throw new ProfileError(p, `role: "container" requires a non-empty "children" array`);
+  }
+  if (!Array.isArray(raw) || raw.length === 0) {
+    throw new ProfileError(p, `role: "container" requires a non-empty "children" array`);
+  }
+  const out = [];
+  for (const [i, item] of raw.entries()) {
+    if (!item || typeof item !== "object") {
+      throw new ProfileError(p, `children[${i}] must be an object { exec, target, next }`);
+    }
+    const r = item;
+    const exec = requireString(p, r, "exec");
+    const target = requireString(p, r, "target");
+    if (!VALID_CONTAINER_CHILD_TARGETS.has(target)) {
+      throw new ProfileError(p, `children[${i}].target must be "issue" or "pr"`);
+    }
+    if (!r.next || typeof r.next !== "object" || Array.isArray(r.next)) {
+      throw new ProfileError(p, `children[${i}].next must be an object mapping action types to next step`);
+    }
+    const next = {};
+    for (const [k, v] of Object.entries(r.next)) {
+      if (typeof v !== "string" || v.length === 0) {
+        throw new ProfileError(p, `children[${i}].next["${k}"] must be a non-empty string`);
+      }
+      next[k] = v;
+    }
+    out.push({ exec, target, next });
+  }
+  return out;
+}
 function parseScriptList(p, key, raw) {
   if (!Array.isArray(raw)) {
     throw new ProfileError(p, `scripts.${key} must be an array`);
@@ -6878,6 +6920,7 @@ function runShell(cmd, cwd, timeoutMs = 3e4) {
 }
 
 // src/executor.ts
+var CONTAINER_MAX_ITERATIONS = 50;
 async function runExecutable(profileName, input) {
   const profilePath = resolveProfilePath(profileName);
   const profile = loadProfile(profilePath);
@@ -6977,7 +7020,10 @@ async function runExecutable(profileName, input) {
       }
     }
     let agentResult = null;
-    if (!ctx.skipAgent) {
+    if (profile.role === "container") {
+      ctx.skipAgent = true;
+      await runContainerLoop(profile, ctx, input);
+    } else if (!ctx.skipAgent) {
       const prompt = ctx.data.prompt;
       if (!prompt) {
         return finish({ exitCode: 99, reason: "composePrompt did not produce a prompt (ctx.data.prompt missing)" });
@@ -7254,6 +7300,157 @@ async function runShellEntry(entry, ctx, profile) {
 function envKey(name) {
   return name.toUpperCase().replace(/-/g, "_");
 }
+async function runContainerLoop(profile, ctx, input) {
+  const children = profile.children;
+  if (!children || children.length === 0) {
+    process.stderr.write(`[kody container] profile "${profile.name}" has no children \u2014 nothing to run
+`);
+    ctx.output.exitCode = 0;
+    ctx.output.reason = "container has no children";
+    return;
+  }
+  const runChild = input.__runChild ?? ((name, opts) => runExecutable(name, opts));
+  const reader = input.__readTaskState ?? readTaskState;
+  const issueNumber = ctx.args.issue;
+  let currentIdx = 0;
+  let iteration = 0;
+  while (currentIdx >= 0 && currentIdx < children.length) {
+    iteration++;
+    if (iteration > CONTAINER_MAX_ITERATIONS) {
+      const reason = `container exceeded ${CONTAINER_MAX_ITERATIONS} iterations \u2014 possible routing loop`;
+      process.stderr.write(`[kody container] aborting: ${reason}
+`);
+      ctx.output.exitCode = 1;
+      ctx.output.reason = reason;
+      return;
+    }
+    const child = children[currentIdx];
+    process.stderr.write(`[kody container] step ${iteration}: invoking ${child.exec}
+`);
+    const priorState = readContainerState(ctx, child, reader);
+    const priorAction = priorState.executables?.[child.exec]?.lastAction;
+    let actionType;
+    if (priorAction && /_COMPLETED$/i.test(priorAction.type)) {
+      process.stderr.write(`[kody container] skipping ${child.exec}: already completed (${priorAction.type})
+`);
+      actionType = priorAction.type;
+    } else {
+      let cliArgs;
+      if (child.target === "pr") {
+        const prUrl = priorState.core?.prUrl;
+        const prNumber = prUrl ? parsePrNumber4(prUrl) : null;
+        if (!prNumber) {
+          const reason = `container child "${child.exec}" needs --pr but state.core.prUrl is unset`;
+          process.stderr.write(`[kody container] aborting: ${reason}
+`);
+          ctx.output.exitCode = 1;
+          ctx.output.reason = reason;
+          const action = {
+            type: "AGENT_NOT_RUN",
+            payload: { reason, dispatchTarget: "pr", child: child.exec },
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          };
+          ctx.data.action = action;
+          return;
+        }
+        cliArgs = { pr: prNumber };
+      } else {
+        if (issueNumber === void 0) {
+          const reason = `container child "${child.exec}" needs --issue but ctx.args.issue is unset`;
+          process.stderr.write(`[kody container] aborting: ${reason}
+`);
+          ctx.output.exitCode = 1;
+          ctx.output.reason = reason;
+          return;
+        }
+        cliArgs = { issue: issueNumber };
+      }
+      let childOut;
+      try {
+        childOut = await runChild(child.exec, {
+          cliArgs,
+          cwd: input.cwd,
+          config: input.config,
+          skipConfig: input.skipConfig,
+          verbose: input.verbose,
+          quiet: input.quiet
+        });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[kody container] child "${child.exec}" crashed: ${msg}
+`);
+        ctx.output.exitCode = 1;
+        ctx.output.reason = `child "${child.exec}" crashed: ${msg}`;
+        return;
+      }
+      const next = readContainerState(ctx, child, reader);
+      ctx.data.taskState = next;
+      const actionFromState = next.core?.lastOutcome?.type;
+      actionType = actionFromState ?? (childOut.exitCode === 0 ? "RUN_COMPLETED" : "RUN_FAILED");
+    }
+    const route = child.next[actionType] ?? child.next["*"];
+    if (!route) {
+      const reason = `no route for action "${actionType}" from child "${child.exec}"`;
+      process.stderr.write(`[kody container] aborting: ${reason}
+`);
+      ctx.output.exitCode = 1;
+      ctx.output.reason = reason;
+      return;
+    }
+    process.stderr.write(`[kody container] outcome ${actionType}: dispatching to ${route}
+`);
+    if (route === "done") {
+      ctx.output.exitCode = 0;
+      return;
+    }
+    if (route === "abort") {
+      ctx.output.exitCode = 1;
+      ctx.output.reason = `container aborted by route from "${child.exec}" on ${actionType}`;
+      return;
+    }
+    const nextIdx = children.findIndex((c) => c.exec === route);
+    if (nextIdx < 0) {
+      const reason = `container route "${route}" does not match any declared child exec name`;
+      process.stderr.write(`[kody container] aborting: ${reason}
+`);
+      ctx.output.exitCode = 1;
+      ctx.output.reason = reason;
+      return;
+    }
+    currentIdx = nextIdx;
+  }
+}
+function readContainerState(ctx, _child, reader) {
+  const issueNumber = ctx.args.issue;
+  if (issueNumber !== void 0) {
+    try {
+      return reader("issue", issueNumber, ctx.cwd);
+    } catch {
+    }
+  }
+  if (ctx.data.taskState && typeof ctx.data.taskState === "object") {
+    return ctx.data.taskState;
+  }
+  return {
+    schemaVersion: 1,
+    core: {
+      phase: "idle",
+      status: "pending",
+      currentExecutable: null,
+      lastOutcome: null,
+      attempts: {}
+    },
+    executables: {},
+    artifacts: {},
+    history: []
+  };
+}
+function parsePrNumber4(url) {
+  const m = url.match(/\/pull\/(\d+)(?:[/?#]|$)/);
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  return Number.isFinite(n) ? n : null;
+}
 function flattenConfig(obj, prefix = "") {
   const out = [];
   for (const [k, v] of Object.entries(obj)) {

package/dist/executables/release/deploy.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+#
+# release/deploy.sh — function library for the deploy phase.
+#
+# Functions:
+#   read_changelog_section <branch> <ver>   -> prints the body of the matching ## header block
+#   build_pr_body <ver> <changelog> <default_branch> <release_branch> <issue>
+#                                            -> echoes the deploy PR body
+#   open_deploy_pr <new_version> <issue>    -> echoes deploy PR URL (or empty if no-op)
+
+# shellcheck disable=SC2148
+
+# Extract the section for $ver from CHANGELOG.md fetched from origin/$branch.
+# Handles three header shapes:
+#   "## [0.25.0] - 2026-04-15"   (bracketed, dash separator)
+#   "## 0.22.0 (2026-03-25)"     (bare, parenthesized date)
+#   "## v0.25.5 — 2026-05-05"    (v-prefixed, em-dash, kody style)
+read_changelog_section() {
+  local branch="$1" ver="$2" raw=""
+  if ! raw=$(git show "origin/${branch}:CHANGELOG.md" 2>/dev/null); then
+    return 0
+  fi
+  printf '%s' "$raw" | awk -v ver="$ver" '
+    BEGIN { capture = 0 }
+    /^##[[:space:]]/ {
+      if (capture) { exit }
+      header = $0
+      sub(/^##[[:space:]]+/, "", header)
+      sub(/^\[/, "", header); sub(/\].*/, "", header)
+      sub(/[[:space:]].*/, "", header)
+      sub(/[(].*/, "", header)
+      sub(/^v/, "", header)
+      if (header == ver) { capture = 1; next }
+    }
+    capture { print }
+  ' | awk '
+    NF { if (!started) started = 1; out[++n] = $0; last = n; next }
+    started { out[++n] = $0 }
+    END { for (i = 1; i <= last; i++) print out[i] }
+  '
+}
+
+build_pr_body() {
+  local ver="$1" changelog="$2" default_branch="$3" release_branch="$4" issue="$5"
+  printf 'Automated deploy PR opened by kody — promotes `%s` to `%s` for release **v%s**.\n\n' \
+    "$default_branch" "$release_branch" "$ver"
+  if [[ -n "$changelog" ]]; then
+    printf '<!-- kody-changelog-start -->\n## What'\''s changing in v%s\n\n%s\n<!-- kody-changelog-end -->\n\n' \
+      "$ver" "$changelog"
+  fi
+  printf 'Merge this PR to deploy v%s to `%s`.' "$ver" "$release_branch"
+  if [[ "$issue" =~ ^[0-9]+$ && "$issue" != "0" ]]; then
+    printf '\n\nTracking-Issue: #%s\n' "$issue"
+  else
+    printf '\n'
+  fi
+}
+
+# Open or reuse the deploy PR (default_branch → release_branch).
+# Returns the PR URL via stdout. Empty stdout = single-branch repo, no-op.
+# Refreshes existing PR's body via gh pr edit (idempotent).
+open_deploy_pr() {
+  local new_version="$1"
+  local issue_arg="$2"
+  local default_branch="${KODY_CFG_GIT_DEFAULTBRANCH:-main}"
+  local release_branch="${KODY_CFG_RELEASE_RELEASEBRANCH:-}"
+
+  # Single-branch repos: nothing to deploy.
+  if [[ -z "$release_branch" || "$release_branch" == "$default_branch" ]]; then
+    echo "[deploy] no releaseBranch configured (or equals defaultBranch) — skipping deploy PR" >&2
+    echo ""
+    return 0
+  fi
+
+  # Read the section from the integration branch (where release-prepare just merged).
+  local changelog_section
+  changelog_section=$(read_changelog_section "$default_branch" "$new_version" || true)
+  if [[ -z "$changelog_section" ]]; then
+    echo "[deploy] no CHANGELOG section for v${new_version} on origin/${default_branch} — minimal body" >&2
+  fi
+
+  local body
+  body=$(build_pr_body "$new_version" "$changelog_section" "$default_branch" "$release_branch" "$issue_arg")
+
+  # Idempotency: reuse an open PR for this branch pair if one exists.
+  local existing pr_url
+  existing=$(gh pr list --head "$default_branch" --base "$release_branch" --state open --json url --limit 1 2>/dev/null \
+    | python3 -c 'import json,sys; data=json.load(sys.stdin); print(data[0]["url"] if data else "")' 2>/dev/null \
+    || echo "")
+
+  if [[ -n "$existing" ]]; then
+    echo "  reusing existing deploy PR: ${existing}" >&2
+    pr_url="$existing"
+    if ! printf '%s' "$body" | gh pr edit "$pr_url" --body-file - >/dev/null 2>&1; then
+      echo "[deploy] WARN: failed to refresh deploy PR body" >&2
+    fi
+  else
+    if ! pr_url=$(printf '%s' "$body" | gh pr create --head "$default_branch" --base "$release_branch" --title "deploy: ${default_branch} → ${release_branch} (v${new_version})" --body-file -); then
+      echo "[deploy] gh pr create failed" >&2
+      return 1
+    fi
+  fi
+
+  if [[ -z "$pr_url" ]]; then
+    echo "[deploy] empty PR URL after gh pr create" >&2
+    return 1
+  fi
+
+  # Persist the deploy-PR marker on the originating issue body, replacing
+  # any prepare-PR marker so the dashboard pivots to the deploy PR.
+  if [[ "$issue_arg" =~ ^[0-9]+$ && "$issue_arg" != "0" ]]; then
+    local pr_number="${pr_url##*/}"
+    if [[ "$pr_number" =~ ^[0-9]+$ ]]; then
+      local cur_body cleaned_body
+      cur_body=$(gh issue view "$issue_arg" --json body -q .body 2>/dev/null || echo "")
+      cleaned_body=$(printf '%s' "$cur_body" | sed -E '/<!-- kody-release-pr:[^>]*-->/d')
+      {
+        printf '%s' "$cleaned_body"
+        printf '\n\n<!-- kody-release-pr: #%s -->\n' "$pr_number"
+      } | gh issue edit "$issue_arg" --body-file - >/dev/null 2>&1 || \
+        echo "[deploy] WARN: failed to write kody-release-pr marker to issue #${issue_arg}" >&2
+    fi
+  fi
+
+  echo "$pr_url"
+  return 0
+}

package/dist/executables/release/prepare.sh

@@ -0,0 +1,345 @@
+#!/usr/bin/env bash
+#
+# release/prepare.sh — function library for the prepare phase.
+#
+# Functions exported:
+#   read_pkg_version
+#   bump_version <cur> <patch|minor|major>
+#   write_pkg_version <file> <new>
+#   resolve_version_files            -> prints \n-separated paths
+#   generate_changelog               -> prints raw `subject||sha` lines
+#   format_changelog <new_version>   -> reads stdin, prints markdown entry
+#   prepend_changelog <entry>
+#   remote_branch_exists <branch>
+#   find_open_pr <branch>            -> prints url or empty
+#   open_prepare_pr <new_version> <issue_number> <prefer>
+#                                    -> echoes PR url; sets globals
+#   set_kody_release_pr_marker <issue_number> <pr_url>
+#
+# Side-effects: bumps version files, generates CHANGELOG.md, commits +
+# pushes a release branch, opens the prepare PR.
+
+# shellcheck disable=SC2148
+
+read_pkg_version() {
+  python3 -c "import json,sys; print(json.load(open('package.json'))['version'])"
+}
+
+bump_version() {
+  local cur="$1" kind="$2"
+  local core="${cur%%-*}"
+  if ! [[ "$core" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
+    echo "[prepare] cannot parse version '$cur'" >&2
+    return 1
+  fi
+  local maj="${BASH_REMATCH[1]}" min="${BASH_REMATCH[2]}" pat="${BASH_REMATCH[3]}"
+  case "$kind" in
+    major) maj=$((maj + 1)); min=0; pat=0 ;;
+    minor) min=$((min + 1)); pat=0 ;;
+    patch|*) pat=$((pat + 1)) ;;
+  esac
+  echo "${maj}.${min}.${pat}"
+}
+
+write_pkg_version() {
+  local file="$1" new="$2"
+  python3 - "$file" "$new" <<'PY'
+import json, sys
+path, new = sys.argv[1], sys.argv[2]
+try:
+    with open(path) as f:
+        text = f.read()
+except FileNotFoundError:
+    print("MISSING")
+    sys.exit(0)
+try:
+    data = json.loads(text)
+except Exception:
+    print("UNCHANGED")
+    sys.exit(0)
+if data.get("version") == new:
+    print("UNCHANGED")
+    sys.exit(0)
+data["version"] = new
+with open(path, "w") as f:
+    f.write(json.dumps(data, indent=2) + "\n")
+print("WROTE")
+PY
+}
+
+resolve_version_files() {
+  local raw="${KODY_CFG_RELEASE_VERSIONFILES:-}"
+  if [[ -z "$raw" ]]; then
+    echo "package.json"
+    return
+  fi
+  python3 - <<PY
+import json, os
+raw = os.environ.get("KODY_CFG_RELEASE_VERSIONFILES", "")
+try:
+    arr = json.loads(raw)
+except Exception:
+    print("package.json"); raise SystemExit
+if isinstance(arr, list) and arr:
+    for f in arr:
+        if isinstance(f, str) and f:
+            print(f)
+else:
+    print("package.json")
+PY
+}
+
+generate_changelog() {
+  local last_tag count
+  if ! last_tag=$(git describe --tags --abbrev=0 --match 'v*' 2>/dev/null); then
+    git fetch --tags --quiet 2>/dev/null || true
+    last_tag=$(git describe --tags --abbrev=0 --match 'v*' 2>/dev/null || true)
+  fi
+  if [[ -n "$last_tag" ]]; then
+    count=$(git rev-list --count "${last_tag}..HEAD" --no-merges 2>/dev/null || echo "?")
+    echo "  changelog: ${count} commits since ${last_tag}" >&2
+    git log "${last_tag}..HEAD" --pretty=format:'%s||%h' --no-merges 2>/dev/null || true
+  else
+    echo "  changelog: no previous v* tag found — using last 100 commits" >&2
+    git log -n100 HEAD --pretty=format:'%s||%h' --no-merges 2>/dev/null || true
+  fi
+}
+
+format_changelog() {
+  local new_version="$1"
+  local date_str
+  date_str=$(date -u +%Y-%m-%d)
+  python3 - "$new_version" "$date_str" <<'PY'
+import sys, re
+new_version, date_str = sys.argv[1], sys.argv[2]
+raw = sys.stdin.read()
+buckets = {k: [] for k in ("feat", "fix", "perf", "refactor", "docs", "chore", "other")}
+for line in raw.splitlines():
+    line = line.strip()
+    if not line or "||" not in line:
+        continue
+    subject, sha = line.split("||", 1)
+    if re.match(r"(?i)^chore:\s*release\s+v\d", subject):
+        continue
+    m = re.match(r"^(\w+)(?:\(.*?\))?\s*:\s*(.+)$", subject)
+    if m:
+        kind = m.group(1).lower()
+        msg = m.group(2)
+    else:
+        kind = "other"
+        msg = subject
+    buckets.setdefault(kind, buckets["other"]).append(f"- {msg} ({sha})")
+labels = [
+    ("feat", "Features"),
+    ("fix", "Fixes"),
+    ("perf", "Performance"),
+    ("refactor", "Refactoring"),
+    ("docs", "Docs"),
+    ("chore", "Chores"),
+    ("other", "Other"),
+]
+parts = [f"## v{new_version} — {date_str}", ""]
+emitted = False
+for key, label in labels:
+    items = buckets.get(key) or []
+    if not items:
+        continue
+    parts.append(f"### {label}")
+    parts.extend(items)
+    parts.append("")
+    emitted = True
+if not emitted:
+    parts.append("_No notable commits since the last release._")
+    parts.append("")
+sys.stdout.write("\n".join(parts))
+PY
+}
+
+prepend_changelog() {
+  local entry="$1"
+  local header='# Changelog
+
+All notable changes to this project will be documented in this file.
+
+'
+  if [[ -f CHANGELOG.md ]]; then
+    if grep -qE '^#\s*Changelog\b' CHANGELOG.md; then
+      python3 - "$entry" <<'PY'
+import sys
+entry = sys.argv[1]
+with open("CHANGELOG.md") as f:
+    prior = f.read()
+idx = prior.index("\n", prior.index("# Changelog"))
+new = prior[: idx + 1] + "\n" + entry + prior[idx + 1 :]
+with open("CHANGELOG.md", "w") as f:
+    f.write(new)
+PY
+    else
+      python3 - "$entry" <<PY
+import sys
+entry = sys.argv[1]
+header = "# Changelog\n\nAll notable changes to this project will be documented in this file.\n\n"
+with open("CHANGELOG.md") as f:
+    prior = f.read()
+with open("CHANGELOG.md", "w") as f:
+    f.write(header + entry + prior)
+PY
+    fi
+  else
+    python3 - "$entry" <<PY
+import sys
+entry = sys.argv[1]
+header = "# Changelog\n\nAll notable changes to this project will be documented in this file.\n\n"
+with open("CHANGELOG.md", "w") as f:
+    f.write(header + entry)
+PY
+  fi
+}
+
+remote_branch_exists() {
+  local branch="$1"
+  git ls-remote --heads origin "$branch" 2>/dev/null | grep -q .
+}
+
+find_open_pr() {
+  local branch="$1"
+  gh pr list --head "$branch" --state open --json url --limit 1 2>/dev/null \
+    | python3 -c 'import json,sys; data=json.load(sys.stdin); print(data[0]["url"] if data else "")' 2>/dev/null \
+    || echo ""
+}
+
+# Returns the PREPARE PR url on stdout. Bumps version files, generates
+# CHANGELOG, commits on a release branch, pushes, opens (or reuses) the PR.
+# Globals it sets via export so release.sh can pass them to deploy/publish:
+#   PREPARE_NEW_VERSION
+#   PREPARE_TAG
+#   PREPARE_RELEASE_BRANCH
+#   PREPARE_CHANGELOG_ENTRY
+open_prepare_pr() {
+  local new_version="$1"
+  local issue_arg="$2"
+  local prefer="$3"
+  local default_branch="${KODY_CFG_GIT_DEFAULTBRANCH:-main}"
+
+  local tag="v${new_version}"
+  local release_branch="release/${tag}"
+
+  export PREPARE_NEW_VERSION="$new_version"
+  export PREPARE_TAG="$tag"
+  export PREPARE_RELEASE_BRANCH="$release_branch"
+
+  # Branch-collision gate.
+  local collides=false
+  if remote_branch_exists "$release_branch"; then
+    collides=true
+    case "$prefer" in
+      theirs)
+        local existing
+        existing=$(find_open_pr "$release_branch")
+        if [[ -n "$existing" ]]; then
+          echo "  reusing existing PR (--prefer theirs): ${existing}" >&2
+          echo "$existing"
+          return 0
+        fi
+        echo "[prepare] --prefer theirs: ${release_branch} exists but no open PR" >&2
+        return 1
+        ;;
+      ours)
+        echo "  branch ${release_branch} exists — will force-push (--prefer ours)" >&2
+        ;;
+      *)
+        echo "[prepare] branch ${release_branch} already exists. Use --prefer ours/theirs." >&2
+        return 1
+        ;;
+    esac
+  fi
+
+  # Bump version files.
+  local files
+  mapfile -t files < <(resolve_version_files)
+  local touched=()
+  for f in "${files[@]}"; do
+    local res
+    res=$(write_pkg_version "$f" "$new_version")
+    if [[ "$res" == "WROTE" ]]; then
+      touched+=("$f")
+    fi
+  done
+  if [[ ${#touched[@]} -eq 0 ]]; then
+    echo "[prepare] no version strings updated (files: ${files[*]})" >&2
+    return 1
+  fi
+  echo "  wrote    ${touched[*]}" >&2
+
+  # Changelog.
+  local raw_log entry
+  raw_log=$(generate_changelog) || raw_log=""
+  entry=$(printf '%s' "$raw_log" | format_changelog "$new_version")
+  prepend_changelog "$entry"
+  echo "  wrote    CHANGELOG.md" >&2
+  export PREPARE_CHANGELOG_ENTRY="$entry"
+
+  # Commit + push.
+  export HUSKY=0 SKIP_HOOKS=1
+  git checkout -b "$release_branch"
+  for f in "${touched[@]}" CHANGELOG.md; do
+    git add -- "$f"
+  done
+  git -c commit.gpgsign=false commit -m "chore: release ${tag}"
+  if [[ "$collides" == "true" && "$prefer" == "ours" ]]; then
+    git push -u --force-with-lease origin "$release_branch"
+  else
+    git push -u origin "$release_branch"
+  fi
+
+  # Open PR.
+  local pr_url=""
+  if [[ "$collides" == "true" && "$prefer" == "ours" ]]; then
+    pr_url=$(find_open_pr "$release_branch")
+  fi
+
+  if [[ -z "$pr_url" ]]; then
+    local body_max=60000 body_entry
+    if [[ ${#entry} -gt $body_max ]]; then
+      body_entry="${entry:0:$body_max}
+
+_… truncated; see CHANGELOG.md_"
+    else
+      body_entry="$entry"
+    fi
+    local tracking_line=""
+    if [[ "$issue_arg" =~ ^[0-9]+$ && "$issue_arg" != "0" ]]; then
+      tracking_line=$'\n\nTracking-Issue: #'"${issue_arg}"
+    fi
+    local body
+    body=$'Automated release PR opened by kody.\n\n'"$body_entry"$'\n\nThe release flow will merge this into `'"${default_branch}"$'` and continue to publish + deploy.'"${tracking_line}"
+    pr_url=$(printf '%s' "$body" | gh pr create --head "$release_branch" --base "$default_branch" --title "chore: release ${tag}" --body-file -)
+  fi
+
+  if [[ -z "$pr_url" ]]; then
+    echo "[prepare] gh pr create returned empty URL" >&2
+    return 1
+  fi
+
+  echo "$pr_url"
+  return 0
+}
+
+set_kody_release_pr_marker() {
+  local issue_arg="$1" pr_url="$2"
+  if [[ ! "$issue_arg" =~ ^[0-9]+$ ]] || [[ "$issue_arg" == "0" ]]; then
+    return 0
+  fi
+  local pr_number="${pr_url##*/}"
+  if [[ ! "$pr_number" =~ ^[0-9]+$ ]]; then
+    return 0
+  fi
+  local cur_body cleaned_body
+  cur_body=$(gh issue view "$issue_arg" --json body -q .body 2>/dev/null || echo "")
+  cleaned_body=$(printf '%s' "$cur_body" | sed -E '/<!-- kody-release-pr:[^>]*-->/d')
+  {
+    printf '%s' "$cleaned_body"
+    printf '\n\n<!-- kody-release-pr: #%s -->\n' "$pr_number"
+  } | gh issue edit "$issue_arg" --body-file - >/dev/null 2>&1 || \
+    echo "[prepare] WARN: failed to write kody-release-pr marker to issue #${issue_arg}" >&2
+}

package/dist/executables/release/profile.json

@@ -1,14 +1,38 @@
 {
   "name": "release",
-  "role": "orchestrator",
-  "describe": "Release orchestrator: drives release-prepare → merge PR → release-publish → release-deploy. No agent — postflight entries ARE the transition table, evaluated top-to-bottom via runWhen.",
+  "role": "utility",
+  "phase": "shipped",
+  "describe": "Single-job release flow: prepare → wait CI → merge → publish → deploy → notify. No orchestrator chain — runs end-to-end inside one workflow run.",
   "inputs": [
     {
       "name": "issue",
       "flag": "--issue",
       "type": "int",
       "required": true,
-      "describe": "GitHub issue number to drive the release flow on."
+      "describe": "GitHub issue number that triggered the release."
+    },
+    {
+      "name": "bump",
+      "flag": "--bump",
+      "type": "enum",
+      "values": ["patch", "minor", "major"],
+      "required": false,
+      "describe": "Version bump increment. Default patch."
+    },
+    {
+      "name": "dry-run",
+      "flag": "--dry-run",
+      "type": "bool",
+      "required": false,
+      "describe": "Print plan without writing files, committing, or opening a PR."
+    },
+    {
+      "name": "prefer",
+      "flag": "--prefer",
+      "type": "enum",
+      "values": ["ours", "theirs"],
+      "required": false,
+      "describe": "On release/vX.Y.Z branch collision: 'ours' force-pushes; 'theirs' reuses the existing PR."
     }
   ],
   "claudeCode": {
@@ -38,54 +62,34 @@
           "description": "kody flow: release"
         }
       },
-      {
-        "script": "setLifecycleLabel",
-        "with": {
-          "label": "kody:orchestrating",
-          "color": "1d76db",
-          "description": "kody: orchestrating a multi-stage flow"
-        }
-      },
       { "script": "loadIssueContext" },
       { "script": "loadTaskState" },
+      { "shell": "release.sh", "timeoutSec": 5400 },
       { "script": "skipAgent" }
     ],
     "postflight": [
-      { "script": "startFlow", "with": { "entry": "release-prepare", "target": "issue" } },
-
-      { "script": "waitForCi",
-        "with": { "timeoutMinutes": 60, "pollSeconds": 30, "initialWaitSeconds": 15, "maxFixCiAttempts": 0 },
-        "runWhen": { "data.taskState.core.lastOutcome.type": "RELEASE_PREPARE_COMPLETED" } },
-
-      { "script": "mergeReleasePr",
-        "runWhen": { "data.action.type": "CI_PASSED" } },
-
-      { "script": "dispatch", "with": { "next": "release-publish", "target": "issue" },
-        "runWhen": { "data.taskState.core.lastOutcome.type": "RELEASE_MERGE_COMPLETED" } },
-
-      { "script": "dispatch", "with": { "next": "release-deploy", "target": "issue" },
-        "runWhen": { "data.taskState.core.lastOutcome.type": "RELEASE_PUBLISH_COMPLETED" } },
-
-      { "script": "waitForCi",
-        "with": { "timeoutMinutes": 60, "pollSeconds": 30, "initialWaitSeconds": 15, "maxFixCiAttempts": 3 },
-        "runWhen": { "data.taskState.core.lastOutcome.type": ["RELEASE_DEPLOY_COMPLETED", "FIX_CI_COMPLETED"] } },
-
-      { "script": "dispatch", "with": { "next": "fix-ci", "target": "pr" },
-        "runWhen": { "data.action.type": "CI_FAILED" } },
-
-      { "script": "finishFlow",
-        "with": { "reason": "release-completed", "label": "kody:done", "color": "0e8a16", "description": "kody: release complete" },
-        "runWhen": { "data.action.type": "CI_PASSED" } },
-
-      { "script": "finishFlow",
-        "with": { "reason": "release-failed", "label": "kody:failed", "color": "e11d21", "description": "kody: release flow failed" },
-        "runWhen": { "data.action.type": ["CI_GIVEUP", "CI_TIMEOUT"] } },
-
-      { "script": "finishFlow",
-        "with": { "reason": "release-failed", "label": "kody:failed", "color": "e11d21", "description": "kody: release flow failed" },
-        "runWhen": { "data.taskState.core.lastOutcome.type": ["RELEASE_PREPARE_FAILED", "RELEASE_MERGE_FAILED", "RELEASE_PUBLISH_FAILED", "RELEASE_DEPLOY_FAILED", "FIX_CI_FAILED"] } },
-
-      { "script": "persistFlowState" }
+      { "script": "recordOutcome" },
+      { "script": "saveTaskState" },
+      {
+        "script": "finishFlow",
+        "with": {
+          "reason": "release-completed",
+          "label": "kody:done",
+          "color": "0e8a16",
+          "description": "kody: release complete"
+        },
+        "runWhen": { "data.action.type": "RELEASE_COMPLETED" }
+      },
+      {
+        "script": "finishFlow",
+        "with": {
+          "reason": "release-failed",
+          "label": "kody:failed",
+          "color": "e11d21",
+          "description": "kody: release flow failed"
+        },
+        "runWhen": { "data.action.type": "RELEASE_FAILED" }
+      }
     ]
   }
 }

package/dist/executables/release/publish.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+#
+# release/publish.sh — function library for the publish phase.
+#
+# Functions:
+#   tag_and_publish <new_version>     -> creates tag locally, pushes, runs publishCommand
+#   create_gh_release <tag>           -> echoes release URL or empty
+
+# shellcheck disable=SC2148
+
+tag_and_publish() {
+  local new_version="$1"
+  local publish_cmd="${KODY_CFG_RELEASE_PUBLISHCOMMAND:-}"
+  local timeout_ms="${KODY_CFG_RELEASE_TIMEOUTMS:-600000}"
+  local timeout_s=$((timeout_ms / 1000))
+  local tag="v${new_version}"
+
+  # Refuse if the tag already exists locally (left over from a prior failed run).
+  if git rev-parse --verify "$tag" >/dev/null 2>&1; then
+    echo "[publish] tag ${tag} already exists locally" >&2
+    return 1
+  fi
+
+  git tag -a "$tag" -m "Release ${tag}"
+  git push origin "$tag"
+
+  # publishCommand (optional). Failure here is recorded but does not abort —
+  # we still want the GH release entry so the tag is discoverable.
+  local publish_status="skipped"
+  if [[ -n "$publish_cmd" ]]; then
+    local cmd="${publish_cmd//\$VERSION/$new_version}"
+    echo "  publish: ${cmd}" >&2
+    if timeout "${timeout_s}" bash -c "$cmd"; then
+      publish_status="ok"
+    else
+      publish_status="failed"
+      echo "[publish] publishCommand failed (continuing to create GH release)" >&2
+    fi
+  fi
+
+  echo "$publish_status"
+  return 0
+}
+
+create_gh_release() {
+  local tag="$1"
+  local draft="${KODY_CFG_RELEASE_DRAFTRELEASE:-false}"
+  local draft_flag=""
+  [[ "$draft" == "true" ]] && draft_flag="--draft"
+
+  local release_url=""
+  if release_url=$(gh release create "$tag" --title "$tag" --notes "Release ${tag} — automated by kody." $draft_flag 2>&1); then
+    echo "$release_url"
+    return 0
+  else
+    echo "[publish] gh release create failed: $release_url" >&2
+    echo ""
+    return 1
+  fi
+}

package/dist/executables/release/release.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+#
+# release/release.sh — single-job release driver.
+#
+# Replaces the orchestrator + 3-executable chain with one linear bash flow:
+#   prepare → wait CI → merge → publish → deploy → notify
+#
+# Inputs (env, set by the executor):
+#   KODY_ARG_ISSUE      triggering issue number (required)
+#   KODY_ARG_BUMP       patch|minor|major (default: patch)
+#   KODY_ARG_DRY_RUN    true|false
+#   KODY_ARG_PREFER     ours|theirs (optional; for branch collision)
+#
+# Config (env, flattened from kody.config.json):
+#   KODY_CFG_GIT_DEFAULTBRANCH         e.g. dev
+#   KODY_CFG_RELEASE_RELEASEBRANCH     e.g. main (unset → deploy is no-op)
+#   KODY_CFG_RELEASE_VERSIONFILES      JSON array
+#   KODY_CFG_RELEASE_PUBLISHCOMMAND    optional; $VERSION substituted
+#   KODY_CFG_RELEASE_NOTIFYCOMMAND     optional; $VERSION + $DEPLOY_PR_URL substituted
+#   KODY_CFG_RELEASE_DRAFTRELEASE      "true" → create as draft
+#   KODY_CFG_RELEASE_TIMEOUTMS         per-command timeout in ms
+#
+# Stdout signals:
+#   KODY_PR_URL=<deploy PR url>
+#   KODY_REASON=<text>
+#   KODY_SKIP_AGENT=true
+#   RELEASE_COMPLETED=true | RELEASE_FAILED=true (consumed by recordOutcome → finishFlow)
+
+set -euo pipefail
+
+HERE="$(dirname "$0")"
+# shellcheck source=prepare.sh
+source "$HERE/prepare.sh"
+# shellcheck source=wait.sh
+source "$HERE/wait.sh"
+# shellcheck source=publish.sh
+source "$HERE/publish.sh"
+# shellcheck source=deploy.sh
+source "$HERE/deploy.sh"
+
+issue="${KODY_ARG_ISSUE:?required}"
+bump="${KODY_ARG_BUMP:-patch}"
+dry_run="${KODY_ARG_DRY_RUN:-false}"
+prefer="${KODY_ARG_PREFER:-}"
+
+default_branch="${KODY_CFG_GIT_DEFAULTBRANCH:-main}"
+notify_cmd="${KODY_CFG_RELEASE_NOTIFYCOMMAND:-}"
+notify_timeout_s=$(( ${KODY_CFG_RELEASE_TIMEOUTMS:-600000} / 1000 ))
+
+# Tracks where we were when an error fired, for clearer failure messages.
+current_step="init"
+
+on_error() {
+  local rc=$?
+  echo "[release] FAILED during step '${current_step}' (exit ${rc})" >&2
+  echo "KODY_REASON=release failed during ${current_step}"
+  echo "RELEASE_FAILED=true"
+  echo "KODY_SKIP_AGENT=true"
+  exit "$rc"
+}
+trap on_error ERR
+
+if [[ ! -f package.json ]]; then
+  echo "[release] package.json not found in $(pwd)" >&2
+  echo "KODY_REASON=release: package.json not found"
+  echo "RELEASE_FAILED=true"
+  echo "KODY_SKIP_AGENT=true"
+  exit 1
+fi
+
+# ── 1. Prepare ────────────────────────────────────────────────────────────
+current_step="prepare"
+old_version=$(read_pkg_version)
+new_version=$(bump_version "$old_version" "$bump")
+tag="v${new_version}"
+echo "→ release: issue=#${issue} bump=${bump} ${old_version} → ${new_version}"
+
+if [[ "$dry_run" == "true" ]]; then
+  echo "RELEASE_PLAN=bump=${new_version} tag=${tag}"
+  echo "KODY_REASON=dry-run — would bump to ${new_version}${prefer:+ (--prefer ${prefer})}"
+  echo "RELEASE_COMPLETED=true"
+  echo "KODY_SKIP_AGENT=true"
+  exit 0
+fi
+
+prep_pr_url=$(open_prepare_pr "$new_version" "$issue" "$prefer")
+if [[ -z "$prep_pr_url" ]]; then
+  echo "[release] prepare returned no PR URL" >&2
+  exit 1
+fi
+echo "✓ prepare: ${prep_pr_url}"
+set_kody_release_pr_marker "$issue" "$prep_pr_url"
+
+# ── 2. Wait for prepare PR CI ─────────────────────────────────────────────
+current_step="wait_prepare_ci"
+prep_pr_num="${prep_pr_url##*/}"
+wait_for_ci "$prep_pr_num" 60 || {
+  echo "[release] CI failed/timeout on prepare PR #${prep_pr_num}" >&2
+  exit 1
+}
+
+# ── 3. Merge prepare PR ───────────────────────────────────────────────────
+current_step="merge"
+if gh pr merge "$prep_pr_num" --merge --admin 2>&1; then
+  echo "✓ merged: PR #${prep_pr_num}"
+elif gh pr merge "$prep_pr_num" --merge 2>&1 | grep -qi "already merged"; then
+  echo "  (already merged)"
+else
+  echo "[release] gh pr merge failed for PR #${prep_pr_num}" >&2
+  exit 1
+fi
+
+# ── 4. Publish (tag + GH release) ─────────────────────────────────────────
+current_step="publish"
+git fetch origin "$default_branch" --tags
+git checkout "$default_branch"
+git reset --hard "origin/$default_branch"
+
+# Sanity: confirm the bump landed on the integration branch.
+landed_version=$(read_pkg_version)
+if [[ "$landed_version" != "$new_version" ]]; then
+  echo "[release] WARN: package.json on ${default_branch} is ${landed_version}, expected ${new_version} after merge" >&2
+fi
+
+publish_status=$(tag_and_publish "$new_version")
+release_url=$(create_gh_release "$tag" || echo "")
+echo "✓ publish: tag=${tag} status=${publish_status} release_url=${release_url:-<none>}"
+
+if [[ "$publish_status" == "failed" ]]; then
+  echo "[release] publishCommand failed but tag + GH release exist" >&2
+  echo "KODY_REASON=tag + GH release created, but publishCommand failed"
+  echo "RELEASE_FAILED=true"
+  echo "KODY_SKIP_AGENT=true"
+  exit 1
+fi
+
+# ── 5. Deploy PR (default → release branch) ───────────────────────────────
+current_step="deploy"
+deploy_pr_url=$(open_deploy_pr "$new_version" "$issue" || echo "")
+if [[ -z "$deploy_pr_url" ]]; then
+  echo "  (deploy: no-op — single-branch repo)"
+else
+  echo "✓ deploy: ${deploy_pr_url}"
+fi
+
+# ── 6. Notify ─────────────────────────────────────────────────────────────
+current_step="notify"
+notify_status="skipped"
+if [[ -n "$notify_cmd" ]]; then
+  cmd="${notify_cmd//\$VERSION/$new_version}"
+  cmd="${cmd//\$DEPLOY_PR_URL/${deploy_pr_url:-}}"
+  echo "  notify: ${cmd}"
+  if timeout "$notify_timeout_s" bash -c "$cmd"; then
+    notify_status="ok"
+  else
+    notify_status="failed"
+    echo "[release] notifyCommand failed (non-fatal)" >&2
+  fi
+fi
+
+# ── 7. Done ───────────────────────────────────────────────────────────────
+current_step="done"
+[[ -n "$deploy_pr_url" ]] && echo "KODY_PR_URL=${deploy_pr_url}"
+echo "RELEASE_TAG=${tag}"
+[[ -n "$release_url" ]] && echo "RELEASE_URL=${release_url}"
+[[ -n "$deploy_pr_url" ]] && echo "RELEASE_DEPLOY_PR=${deploy_pr_url}"
+echo "KODY_REASON=release v${new_version} complete (notify=${notify_status})"
+echo "RELEASE_COMPLETED=true"
+echo "KODY_SKIP_AGENT=true"

package/dist/executables/release/wait.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+#
+# release/wait.sh — wait_for_ci function: poll a PR's check rollup
+# until all non-skipped checks pass, or timeout.
+#
+# Function: wait_for_ci <pr_number> <timeout_minutes> [poll_seconds] [initial_wait]
+# Returns 0 on CI passed, 1 on CI failed/timeout.
+#
+# Special-case: if a PR has zero registered checks (no CI configured),
+# treats that as PASSED after a short stabilization window — so a Tester
+# repo without checks doesn't loop forever.
+
+# shellcheck disable=SC2148
+
+wait_for_ci() {
+  local pr_number="$1"
+  local timeout_minutes="${2:-60}"
+  local poll_seconds="${3:-30}"
+  local initial_wait="${4:-15}"
+
+  if [[ -z "$pr_number" || ! "$pr_number" =~ ^[0-9]+$ ]]; then
+    echo "[wait_for_ci] invalid pr_number: '$pr_number'" >&2
+    return 1
+  fi
+
+  local deadline=$(( $(date +%s) + timeout_minutes * 60 ))
+  echo "→ wait_for_ci: PR #${pr_number}, timeout=${timeout_minutes}m"
+
+  sleep "$initial_wait"
+
+  # Track consecutive "no checks" results so we don't bail prematurely
+  # on a PR that's just slow to register checks.
+  local empty_count=0
+  local empty_threshold=4   # ~2 minutes (4 * poll_seconds=30s) before treating as no-CI
+
+  while (( $(date +%s) < deadline )); do
+    local raw
+    if ! raw=$(gh pr checks "$pr_number" --json state 2>/dev/null); then
+      # gh exits non-zero when there are no checks — treat as no-CI.
+      empty_count=$((empty_count + 1))
+      echo "  [wait_for_ci] gh pr checks returned non-zero (count=${empty_count})"
+      if (( empty_count >= empty_threshold )); then
+        echo "→ wait_for_ci: PR #${pr_number} has no CI checks configured — treating as passed"
+        return 0
+      fi
+      sleep "$poll_seconds"
+      continue
+    fi
+
+    # Empty array? Same path.
+    local total
+    total=$(printf '%s' "$raw" | jq 'length' 2>/dev/null || echo "0")
+    if [[ "$total" == "0" ]]; then
+      empty_count=$((empty_count + 1))
+      echo "  [wait_for_ci] no checks registered yet (count=${empty_count})"
+      if (( empty_count >= empty_threshold )); then
+        echo "→ wait_for_ci: PR #${pr_number} has no CI checks configured — treating as passed"
+        return 0
+      fi
+      sleep "$poll_seconds"
+      continue
+    fi
+    empty_count=0
+
+    # Tally states via jq.
+    local pending failed passed failed_names
+    pending=$(printf '%s' "$raw" | jq '[.[] | select((.state // "") | IN("PENDING","IN_PROGRESS","QUEUED",""))] | length')
+    failed=$(printf '%s' "$raw" | jq '[.[] | select((.state // "") | IN("FAILURE","CANCELLED","TIMED_OUT","ACTION_REQUIRED","STARTUP_FAILURE"))] | length')
+    passed=$(printf '%s' "$raw" | jq '[.[] | select((.state // "") | IN("SUCCESS","SKIPPED","NEUTRAL"))] | length')
+    failed_names=$(printf '%s' "$raw" | jq -r '[.[] | select((.state // "") | IN("FAILURE","CANCELLED","TIMED_OUT","ACTION_REQUIRED","STARTUP_FAILURE")) | .name] | join(",")')
+
+    echo "  [wait_for_ci] pending=${pending} passed=${passed} failed=${failed} (total=${total})"
+
+    if [[ "$failed" -gt 0 ]]; then
+      echo "[wait_for_ci] CI failed on PR #${pr_number}: ${failed_names}" >&2
+      return 1
+    fi
+    if [[ "$pending" -eq 0 && "$passed" -gt 0 ]]; then
+      echo "→ wait_for_ci: all checks passed (${passed}) on PR #${pr_number}"
+      return 0
+    fi
+
+    sleep "$poll_seconds"
+  done
+
+  echo "[wait_for_ci] timeout after ${timeout_minutes}m on PR #${pr_number}" >&2
+  return 1
+}

package/dist/executables/types.ts

@@ -21,14 +21,18 @@ export interface Profile {
   /**
    * Semantic role — what this executable IS, not when it runs.
    *   - primitive:    single-step agent executor (flow → agent → verify → commit → PR).
-   *   - orchestrator: no-agent, drives primitives via a postflight transition table.
+   *   - orchestrator: no-agent, drives primitives via a postflight transition table
+   *                   (comment-based, one GHA run per step).
+   *   - container:    no-agent, runs declared `children` sequentially in-process
+   *                   (one GHA run for the whole flow). Routing is done by per-child
+   *                   `next` maps over action types — no @kody comments dispatched.
    *   - watch:        scheduled observer that inspects repo state and may trigger other executables.
    *   - utility:      no-agent, one-off administrative work (scaffolding, release, etc.).
    *
    * Roles enforce shape at profile-load time and let help/dispatch treat
    * executables differently by category.
    */
-  role: "primitive" | "orchestrator" | "watch" | "utility"
+  role: "primitive" | "orchestrator" | "container" | "watch" | "utility"
   /**
    * Execution model — orthogonal to `role`.
    * `oneshot` (default): single invocation on demand.
@@ -65,10 +69,44 @@ export interface Profile {
    * Artifact entry into the task-state comment's `artifacts` map.
    */
   outputArtifacts: OutputArtifactSpec[]
+  /**
+   * Container children — required when role === "container", forbidden otherwise.
+   * Defines the in-process step sequence and routing map. See ContainerChild.
+   */
+  children?: ContainerChild[]
   /** Absolute directory the profile was loaded from. Used to resolve prompt.md. */
   dir: string
 }
 
+/**
+ * One step in a container's child sequence.
+ *
+ * The container executor runs the first child, reads the resulting action
+ * type from `state.core.lastOutcome`, then looks it up in `next`:
+ *   - exact match → either the name of another child in this container, or
+ *     the literal "done" / "abort"
+ *   - "*" wildcard → fallback when no exact match
+ *   - no match → container aborts
+ */
+export interface ContainerChild {
+  /** Name of the executable to invoke (must resolve via the registry). */
+  exec: string
+  /**
+   * Where to source the target identifier from when invoking this child.
+   *   - "issue": pass --issue <ctx.args.issue>
+   *   - "pr":    parse PR number from state.core.prUrl, pass --pr <N>.
+   *              If state.core.prUrl is not set, the container aborts with
+   *              an AGENT_NOT_RUN action.
+   */
+  target: "issue" | "pr"
+  /**
+   * Map from action.type → next step. Each value must be the name of another
+   * child in this container, "done" (exit 0), or "abort" (exit 1). Lookup is
+   * exact-match first, then "*" as a wildcard fallback.
+   */
+  next: Record<string, string>
+}
+
 export interface InputArtifactSpec {
   /** Artifact name (the key in state.artifacts). */
   name: string

package/package.json

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