@kody-ade/kody-engine 0.4.17 → 0.4.19

package/dist/bin/kody.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.4.17",
+  version: "0.4.19",
   description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -3897,6 +3897,83 @@ function failedAction3(reason) {
 import * as fs19 from "fs";
 import * as path18 from "path";
 
+// src/scripts/jobFrontmatter.ts
+var SCHEDULE_EVERY_VALUES = [
+  "15m",
+  "30m",
+  "1h",
+  "2h",
+  "6h",
+  "12h",
+  "1d",
+  "3d",
+  "7d",
+  "manual"
+];
+var FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+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 === "every" && isScheduleEvery(value)) {
+      out.every = value;
+    }
+  }
+  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;
+}
+
 // src/scripts/issueStateComment.ts
 function isStateEnvelope(x) {
   if (x === null || typeof x !== "object") return false;
@@ -4254,7 +4331,15 @@ var dispatchJobFileTicks = async (ctx, _profile, args) => {
     process.stdout.write(`[jobs] ticking ${slugs.length} job(s) via ${targetExecutable}
 `);
     const results = [];
+    const now = Date.now();
     for (const slug of slugs) {
+      const decision = await decideShouldFire(ctx.cwd, jobsDir, slug, backend, now);
+      if (decision.skip) {
+        process.stdout.write(`[jobs] \u23ED  skip ${slug}: ${decision.reason}
+`);
+        results.push({ slug, exitCode: 0, skipped: true, reason: decision.reason });
+        continue;
+      }
       process.stdout.write(`[jobs] \u2192 tick ${slug}
 `);
       try {
@@ -4291,6 +4376,53 @@ var dispatchJobFileTicks = async (ctx, _profile, args) => {
     }
   }
 };
+async function decideShouldFire(cwd, jobsDir, slug, backend, now) {
+  let every;
+  try {
+    const raw = fs19.readFileSync(path18.join(cwd, jobsDir, `${slug}.md`), "utf-8");
+    every = splitFrontmatter(raw).frontmatter.every;
+  } catch {
+    return { skip: false, reason: "frontmatter unreadable" };
+  }
+  if (!every) return { skip: false, reason: "no schedule (every cron tick)" };
+  if (every === "manual") {
+    return { skip: true, reason: "manual-only (no auto-fire; trigger via dashboard Run now)" };
+  }
+  let lastFiredAt = null;
+  try {
+    const loaded = await backend.load(slug);
+    const raw = loaded.state.data?.lastFiredAt;
+    if (typeof raw === "string") {
+      const ms = Date.parse(raw);
+      if (!Number.isNaN(ms)) lastFiredAt = ms;
+    }
+  } catch {
+    return { skip: false, reason: "state unreadable; firing" };
+  }
+  if (lastFiredAt === null) {
+    return { skip: false, reason: `first tick (every ${every})` };
+  }
+  const intervalMs = scheduleEveryToMs(every);
+  const elapsedMs = now - lastFiredAt;
+  if (elapsedMs >= intervalMs) {
+    return { skip: false, reason: `due (every ${every}, last ${formatAgo(elapsedMs)} ago)` };
+  }
+  const remainingMs = intervalMs - elapsedMs;
+  return {
+    skip: true,
+    reason: `every ${every}; ${formatAgo(elapsedMs)} since last tick, next in ${formatAgo(remainingMs)}`
+  };
+}
+function formatAgo(ms) {
+  const sec = Math.max(0, Math.round(ms / 1e3));
+  if (sec < 60) return `${sec}s`;
+  const min = Math.round(sec / 60);
+  if (min < 60) return `${min}m`;
+  const hr = Math.round(min / 60);
+  if (hr < 48) return `${hr}h`;
+  const day = Math.round(hr / 24);
+  return `${day}d`;
+}
 function listJobSlugs(absDir) {
   if (!fs19.existsSync(absDir)) return [];
   let entries;
@@ -8123,9 +8255,16 @@ var writeJobStateFile = async (ctx, _profile, _agentResult, args) => {
   if (!loaded) {
     throw new Error("writeJobStateFile: ctx.data.jobState missing \u2014 preflight must run first");
   }
+  const stamped = {
+    ...next,
+    data: {
+      ...next.data,
+      lastFiredAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
   const jobsDir = String(args?.jobsDir ?? ".kody/jobs");
   const backend = resolveBackend({ config: ctx.config, cwd: ctx.cwd, jobsDir });
-  await backend.save(loaded, next);
+  await backend.save(loaded, stamped);
 };
 
 // src/scripts/writeRunSummary.ts

package/dist/executables/goal-tick/tick.sh

@@ -124,10 +124,19 @@ PY
 }
 
 ensure_goal_issue() {
-  # Create the umbrella goal issue (once), label it goal:<id> + kody:building,
-  # and persist its number on state.json. Idempotent: if state already has
-  # goalIssueNumber, this is a no-op. The issue auto-closes when the final
-  # goal PR merges, via the `Closes #N` line we add to that PR body.
+  # Create-or-adopt the umbrella goal issue (once), label it goal:<id> +
+  # kody:building, and persist its number on state.json. The issue auto-closes
+  # when the final goal PR merges, via the `Closes #N` line we add to that PR
+  # body.
+  #
+  # Lookup order:
+  #   1. state.json `goalIssueNumber` — fast path.
+  #   2. Search GitHub for an existing umbrella by label `goal:<id>` + the
+  #      canonical title `goal: <goal_id>`. This is the recovery path when
+  #      state.json got wiped (e.g. dashboard pause/resume dropped the field
+  #      in older versions). Without this lookup we'd open a duplicate
+  #      umbrella every time goalIssueNumber goes missing.
+  #   3. Create a fresh umbrella as a last resort.
   local existing
   existing=$(read_state_field "goalIssueNumber")
   if [ -n "$existing" ] && [ "$existing" != "0" ]; then
@@ -142,20 +151,34 @@ ensure_goal_issue() {
   body=$(printf "Umbrella issue for goal **%s**.\n\nClosed automatically when the goal PR (\`%s\` → \`%s\`) merges.\n" \
     "$goal_id" "$goal_branch" "$default_branch")
 
-  # `gh issue create` prints the new issue's URL on stdout
-  # (https://github.com/<owner>/<repo>/issues/<n>). It does NOT support
-  # --json/--jq, so parse the trailing number off the URL.
-  local url
-  url=$(gh issue create \
-    --title "$title" \
-    --body "$body" \
-    --label "$label" \
-    --label "kody:building" 2>/dev/null || echo "")
-
-  num="${url##*/}"
-  if [ -z "$num" ] || ! [[ "$num" =~ ^[0-9]+$ ]]; then
-    echo "[goal-tick] ensure_goal_issue: gh issue create failed (got '${url}') — continuing without umbrella issue"
-    return 0
+  # Recovery path: an umbrella may already exist from a prior run that lost
+  # state. Match strictly by label + exact title to avoid grabbing a child
+  # task issue. Prefer OPEN issues; fall back to closed ones (the umbrella
+  # could have been closed by a prior goal PR merge that we're now re-driving).
+  num=$(gh api \
+    "repos/{owner}/{repo}/issues?labels=${label}&state=all&per_page=100" \
+    --jq "[.[] | select(.pull_request == null) | select(.title == \"${title}\")] | (map(select(.state == \"open\")) + map(select(.state != \"open\")))[0].number // empty" \
+    2>/dev/null || echo "")
+
+  if [ -n "$num" ] && [[ "$num" =~ ^[0-9]+$ ]]; then
+    echo "[goal-tick] adopted existing umbrella issue #${num} for ${goal_id}"
+  else
+    # `gh issue create` prints the new issue's URL on stdout
+    # (https://github.com/<owner>/<repo>/issues/<n>). It does NOT support
+    # --json/--jq, so parse the trailing number off the URL.
+    local url
+    url=$(gh issue create \
+      --title "$title" \
+      --body "$body" \
+      --label "$label" \
+      --label "kody:building" 2>/dev/null || echo "")
+
+    num="${url##*/}"
+    if [ -z "$num" ] || ! [[ "$num" =~ ^[0-9]+$ ]]; then
+      echo "[goal-tick] ensure_goal_issue: gh issue create failed (got '${url}') — continuing without umbrella issue"
+      return 0
+    fi
+    echo "[goal-tick] opened umbrella issue #${num} for ${goal_id}"
   fi
 
   python3 - "$state_file" "$num" <<'PY'
@@ -171,7 +194,6 @@ with open(path, "w") as f:
     json.dump(s, f, indent=2)
     f.write("\n")
 PY
-  echo "[goal-tick] opened umbrella issue #${num} for ${goal_id}"
 }
 
 list_goal_issues() {
@@ -251,6 +273,66 @@ ensure_label "$failed_label" "b60205" "kody goal-runner: task failed; needs huma
 # counting child tasks, so list_goal_issues can filter it out cleanly.
 ensure_goal_issue
 
+# Merge ready goal-task PRs into the goal branch. We own the merge here
+# instead of relying on GitHub's `--auto` flag (which requires the repo's
+# "Allow auto-merge" setting and silently no-ops when disabled). Only merge
+# non-draft PRs with mergeable=MERGEABLE and mergeStateStatus=CLEAN — i.e.
+# all required checks passed and there are no conflicts. Anything else
+# (BLOCKED, DIRTY, BEHIND, UNSTABLE, draft) is left for the operator.
+open_prs=$(gh pr list --base "$goal_branch" --state open --limit 50 \
+  --json number,isDraft,mergeable,mergeStateStatus 2>/dev/null || echo "[]")
+echo "$open_prs" | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+for pr in data:
+    if pr.get('isDraft'): continue
+    if pr.get('mergeable') != 'MERGEABLE': continue
+    if pr.get('mergeStateStatus') != 'CLEAN': continue
+    print(pr['number'])
+" | while read -r pr_num; do
+  [ -n "$pr_num" ] || continue
+  echo "[goal-tick] merging PR #${pr_num} into ${goal_branch}"
+  if ! gh pr merge "$pr_num" --squash --delete-branch >/dev/null 2>&1; then
+    echo "[goal-tick] failed to merge PR #${pr_num} (continuing)"
+  fi
+done
+
+# Close dispatched task issues whose PR has merged into the goal branch.
+# `Closes #N` in the PR body only auto-closes the issue when the PR merges
+# into the default branch — goal-task PRs target the goal branch, so we must
+# close the issues explicitly. Without this, in_flight stays > 0 forever and
+# the goal stalls after task 1. We accept the linkage from either:
+#   - `Closes|Fixes|Resolves #N` in the PR body (authoritative), OR
+#   - leading number on the head ref (kody convention: `<issue>-<slug>`).
+merged_prs=$(gh pr list --base "$goal_branch" --state merged --limit 50 --json number,headRefName,body 2>/dev/null || echo "[]")
+echo "$merged_prs" | python3 -c "
+import json, re, sys
+data = json.load(sys.stdin)
+seen = set()
+for pr in data:
+    n = None
+    body = pr.get('body') or ''
+    m = re.search(r'(?i)\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)\b', body)
+    if m:
+        n = int(m.group(1))
+    else:
+        bm = re.match(r'^(\d+)-', pr.get('headRefName') or '')
+        if bm:
+            n = int(bm.group(1))
+    if n and n not in seen:
+        seen.add(n)
+        print(n)
+" | while read -r issue_num; do
+  [ -n "$issue_num" ] || continue
+  state=$(gh issue view "$issue_num" --json state --jq .state 2>/dev/null || echo "")
+  if [ "$state" = "OPEN" ]; then
+    echo "[goal-tick] closing #${issue_num} (PR merged into ${goal_branch})"
+    gh issue close "$issue_num" \
+      --comment "_Closed by goal-tick: PR for this task merged into \`${goal_branch}\`._" \
+      >/dev/null 2>&1 || echo "[goal-tick] failed to close #${issue_num} (continuing)"
+  fi
+done
+
 issues_json=$(list_goal_issues)
 total=$(echo "$issues_json" | python3 -c "import json,sys; print(len(json.load(sys.stdin)))")
 if [ "$total" = "0" ]; then

package/dist/executables/job-tick/profile.json

@@ -10,6 +10,12 @@
       "type": "string",
       "required": true,
       "describe": "Job slug — basename (without .md) of the file under .kody/jobs/."
+    },
+    {
+      "name": "force",
+      "flag": "--force",
+      "type": "bool",
+      "describe": "When true, the agent ignores the job body's cadence guard and executes the work this tick. All other body rules (allowed commands, restrictions, state schema) still apply. Used for manual triggers from the dashboard's 'Run now' button."
     }
   ],
   "claudeCode": {

package/dist/executables/job-tick/prompt.md

@@ -20,6 +20,8 @@ This is the state you wrote at the end of the previous tick (or `null` if this i
 
 ## What to do on this tick
 
+`forceRun = {{args.force}}` — set to `true` when an operator clicked "Run now" on the dashboard. When `forceRun` is `true`, ignore the job body's `**Cadence guard.**` paragraph (or any equivalent "skip if last run was within X" rule) and execute the work as if the guard had passed. All other body rules — allowed commands, restrictions, state schema — still apply. Force only overrides cadence.
+
 1. **Check `done`.** If the prior state has `done: true`, emit the same state back unchanged and exit without any action.
 2. **Re-read the job body.** It may have changed since the last tick.
 3. **Execute exactly the work the body's `## Job` section describes**, subject to its `## Allowed Commands` and `## Restrictions`. Use the `## State` section to interpret and update `data`.
@@ -45,8 +47,19 @@ If you fail to emit this block, or the JSON is invalid, the tick fails and the g
 ## Rules
 
 - Never edit, create, or delete files in the working tree.
-- Never commit or push.
+- Never commit or push via `git`. The only permitted commit path is `gh api -X PUT` against the report file (see exception below).
 - Only shell calls allowed: `gh`. Everything must go through it.
 - Keep each tick focused: do one action per candidate per wake. The cron will call you again.
 - If state says you're waiting on something, just check and re-emit — don't spawn a duplicate.
 - Honour the job body's `## Restrictions` over any inferred shortcut.
+
+### Single permitted write: the job's report file
+
+A job MAY (optionally — only if its body asks for it) write a single
+markdown report file at the canonical path:
+
+```
+.kody/reports/{{jobSlug}}.md
+```
+
+Only that exact path. Only via `gh api -X PUT /repos/<owner>/<repo>/contents/.kody/reports/{{jobSlug}}.md` (with base64 content + `sha` of the existing file when updating). All other writes — code files, other report paths, other slugs — remain forbidden. The dashboard's `/reports` page surfaces these files automatically; this is the canonical channel for a job's diagnostic output when an issue comment isn't expressive enough.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine",
-  "version": "0.4.17",
+  "version": "0.4.19",
   "description": "kody — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   "license": "MIT",
   "type": "module",
@@ -12,18 +12,6 @@
     "templates",
     "kody.config.schema.json"
   ],
-  "scripts": {
-    "kody": "tsx bin/kody.ts",
-    "build": "tsup && node scripts/copy-assets.cjs",
-    "test": "vitest run tests/unit tests/int --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",
-    "prepublishOnly": "pnpm build"
-  },
   "dependencies": {
     "@actions/cache": "^6.0.0",
     "@anthropic-ai/claude-agent-sdk": "0.2.119"
@@ -44,5 +32,16 @@
     "url": "git+https://github.com/aharonyaircohen/kody-engine.git"
   },
   "homepage": "https://github.com/aharonyaircohen/kody-engine",
-  "bugs": "https://github.com/aharonyaircohen/kody-engine/issues"
-}
+  "bugs": "https://github.com/aharonyaircohen/kody-engine/issues",
+  "scripts": {
+    "kody": "tsx bin/kody.ts",
+    "build": "tsup && node scripts/copy-assets.cjs",
+    "test": "vitest run tests/unit tests/int --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"
+  }
+}