agent-control-plane 0.3.0 → 0.6.0

package/README.md

@@ -12,6 +12,8 @@
 `agent-control-plane` (ACP) keeps your coding agents running reliably without
 you having to stare at them all day.
 
+**✅ ROADMAP COMPLETE (v0.6.0)** - All planned features delivered!
+
 It is the operator layer for coding agents that need to keep running after the
 novelty wears off — and the responsible adult in the room that stops them from
 going completely off the rails.
@@ -33,7 +35,7 @@ however, and suddenly that "not smart enough" free model is grinding through
 your issue backlog like a junior developer who is weirdly enthusiastic about
 reading CI logs.
 
-That is what ACP does. It turns a GitHub repo into a managed runtime: a
+That is what ACP does. It turns a forge-backed repo into a managed runtime: a
 repeatable setup, a stable home for state, a heartbeat that keeps agents
 scheduled and supervised, and a dashboard you can actually glance at without
 spelunking through temp folders, worktrees, or half-remembered `tmux` sessions.
@@ -73,7 +75,7 @@ monthly API budget in a long weekend, or enter a retry loop that only stops when
 the credit card does.
 
 ACP is the person standing next to the fuse. It enforces launch limits,
-reconciles outcomes before touching GitHub, validates before it publishes, and
+reconciles outcomes before touching your forge, validates before it publishes, and
 respects cooldowns instead of hammering a provider at full throttle. The agent
 gets to be smart and fast. ACP makes sure "smart and fast" does not also mean
 "unattended and irreversible."
@@ -98,6 +100,27 @@ it had a supervisor."
 | Run reproducible agent research cheaply | Cost-controlled execution harness for studying agent behavior, output quality, or prompting strategies |
 | Enforce safety by architecture, not by hope | Launch limits, reconcile gates, and cooldowns that are built into the runtime, not left to chance |
 
+## Why Gitea Local-First
+
+ACP started GitHub-first, but a local-first Gitea loop is often a better daily
+working setup:
+
+- It reduces dependence on GitHub API rate limits for routine issue and PR work.
+- It lets agents collaborate against a local forge while you keep GitHub as the
+  public mirror or release boundary.
+- It gives you a safer place to let ACP iterate quickly, because local Gitea is
+  cheaper to reset, inspect, and isolate than a live hosted repo.
+- It matches how ACP now works best operationally: local runtime state,
+  local worktrees, local dashboard, and a forge that can live on the same
+  machine.
+
+The intended model is:
+
+- `Gitea main` is the working mainline ACP automates day to day.
+- Your local source checkout auto-syncs from that forge mainline.
+- GitHub becomes the publish/release mirror once the codebase is stable enough
+  to push outward.
+
 ## Use Cases
 
 Teams and solo builders usually reach for ACP when one of these starts to feel
@@ -120,7 +143,7 @@ familiar:
 ## Roadmap
 
 ACP is moving toward a true multi-backend control plane. The goal is one runtime
-and one dashboard for many coding-agent backends, across macOS, Linux, and
+and one dashboard for many coding-agent backends, across macOS, Linux, and Windows (WSL2)
 Windows.
 
 ### Backend Status
@@ -129,14 +152,41 @@ Windows.
 | --- | --- | --- |
 | `codex` | Production-ready | Full ACP workflow support today. |
 | `claude` | Production-ready | Full ACP workflow support today. |
-| `openclaw` | Production-ready | Full ACP workflow support, including resident-style runs. |
-| `ollama` | Experimental | Working adapter with Node.js agentic loop. Runs any model served by a local Ollama instance. Output quality depends on model size — 7–9B models handle exploration well but struggle with complex multi-step tasks. |
-| `pi` | Experimental | Working adapter using the [pi CLI](https://github.com/mariozechner/pi) in `--print --no-session` mode. Connects to any OpenRouter-compatible model. Useful as a lightweight alternative to openclaw for free-tier model testing. |
-| `opencode` | Experimental | Working adapter for [Crush](https://github.com/charmbracelet/crush) (formerly opencode). Non-interactive `crush run` with full tool execution. |
-| `kilo` | Experimental | Working adapter for [Kilo Code](https://github.com/Kilo-Org/kilocode). Non-interactive `kilo run --auto` with JSON event stream. |
-| `gemini-cli` | Roadmap | Strong future candidate; not wired into ACP yet. |
-| `nanoclaw` | Exploratory | Ecosystem reference for containerized and WSL2-friendly workflows. |
-| `picoclaw` | Exploratory | Ecosystem reference for lightweight Linux and edge-style runtimes. |
+| `openclaw` | Production-ready | Full ACP workflow, including resident-style runs. |
+| `ollama` | **Hardening** | Working adapter with Node.js agentic loop. **v0.4.9+: Added health-check + context detection.** Moved toward production-ready. |
+| `pi` | Experimental | Working adapter using the pi CLI. **Health-check + API key validation.** |
+| `opencode` | Experimental | Working adapter for Crush. **Health-check (verify `crush` binary).** |
+| `kilo` | Experimental | Working adapter for Kilo Code. **Health-check + JSON stream validation.** |
+| `gemini-cli` | **Integrated** | Google's official terminal agent (v0.39.1+). Full ACP adapter with health-check, API key validation, and streaming JSON output. |
+| `nanoclaw` | Not integrable | Standalone agent system (like ACP), not a CLI backend. Reference for container patterns. |
+| `picoclaw` | Not integrable | Standalone agent system (Go-based). Runs on $10 hardware. Not a CLI backend. |
+
+### Adapter Pattern
+
+ACP uses a **standardized adapter interface** to support multiple backends. Every adapter implements these functions:
+
+| Function | Purpose |
+| --- | --- |
+| `adapter_info()` | Print adapter metadata (id, name, type, version, model) |
+| `adapter_health_check()` | Verify backend is available (exit 0 = healthy) |
+| `adapter_run()` | Execute a task (params: MODE SESSION WORKTREE PROMPT_FILE) |
+| `adapter_status()` | Get run status for a session |
+
+**Available adapters:**
+- `tools/bin/ollama-adapter.sh` - Ollama local models (implements health-check)
+- All existing backends (`codex`, `claude`, `pi`, `opencode`, `kilo`) use the same interface via `run-codex-task.sh`, `run-claude-task.sh`, etc.
+
+**Using adapters:**
+
+```bash
+# Print adapter info
+bash tools/bin/ollama-adapter.sh
+
+# Run a task with generic runner
+bash tools/bin/run-with-adapter.sh tools/bin/ollama-adapter.sh safe my-session /path/to/worktree /path/to/prompt.txt
+```
+
+See `tools/bin/adapter-interface.sh` for the full interface specification.
 
 If you are trying ACP on a real repo right now, start with `codex`, `claude`,
 or `openclaw`. Use `ollama` to run local models — useful for research, offline
@@ -211,7 +261,7 @@ flowchart LR
   Scheduler --> Workers["issue / PR worker launchers"]
   Workers --> Backends["codex / claude / openclaw / ollama / pi / opencode / kilo"]
   Backends --> Reconcile["reconcile issue / PR session"]
-  Reconcile --> GitHub["issues / PRs / labels / comments"]
+  Reconcile --> Forge["issues / PRs / labels / comments"]
   Scheduler --> State["runs + state + history"]
   State --> Dashboard["dashboard snapshot + UI"]
 ```
@@ -227,7 +277,7 @@ sequenceDiagram
   participant Heartbeat
   participant Worker
   participant Reconcile
-  participant GitHub
+  participant Forge
 
   Operator->>RuntimeCtl: runtime start --profile-id <id>
   RuntimeCtl->>Supervisor: keep runtime alive
@@ -236,7 +286,7 @@ sequenceDiagram
     Bootstrap->>Heartbeat: invoke published heartbeat
     Heartbeat->>Worker: launch eligible issue/PR flow
     Worker->>Reconcile: emit result artifacts
-    Reconcile->>GitHub: labels, comments, PR actions
+    Reconcile->>Forge: labels, comments, PR actions
   end
 ```
 
@@ -267,9 +317,9 @@ system.
 | --- | --- | --- | --- |
 | Node.js `>= 18` | yes | Runs the npm package entrypoint and `npx` wrapper. | CI runs on Node `22`. Node `20` or `22` both work fine. |
 | `bash` | yes | All runtime, profile, and worker orchestration scripts are Bash. | Your login shell can be `zsh`; `bash` just needs to be on `PATH`. |
-| `git` | yes | Manages worktrees, checks branch state, and coordinates repo automation. | Required even if you interact only through GitHub issues and PRs. |
-| `gh` | yes | GitHub CLI auth and API access for issues, PRs, labels, and metadata. | Run `gh auth login` before first use. |
-| `jq` | yes | Parses JSON from `gh` output and worker metadata throughout. | Missing `jq` will break GitHub-heavy and runtime flows. |
+| `git` | yes | Manages worktrees, checks branch state, and coordinates repo automation. | Required even if you interact only through forge issues and PRs. |
+| `gh` | for GitHub-first setups | GitHub CLI auth and API access for issues, PRs, labels, and metadata. | Run `gh auth login` before first use when `--forge-provider github`. |
+| `jq` | yes | Parses JSON from `gh` output and worker metadata throughout. | Missing `jq` will break GitHub-heavy and Gitea-heavy runtime flows. |
 | `python3` | yes | Powers the dashboard server, snapshot renderer, and config helpers. | Required for both dashboard use and several internal scripts. |
 | `tmux` | yes | Runs long-lived worker sessions and captures their status. | Missing `tmux` means background worker workflows will not launch. |
 | Worker CLI (backend-specific) | depends on backend | The coding agent for a profile. Supported: `codex`, `claude`, `openclaw` (production); `ollama`, `pi`, `opencode`, `kilo` (experimental). | Install and authenticate your chosen backend before starting background runs. |
@@ -279,8 +329,10 @@ system.
 | `kilo` CLI | for `kilo` backend | TypeScript coding agent ([kilocode/cli](https://github.com/Kilo-Org/kilocode)). | Install via `npm i -g @kilocode/cli`. |
 | Bundled `codex-quota` + ACP quota manager | automatic for Codex | Quota-aware failover and health signals for Codex profiles. | Bundled by default. Override with `ACP_CODEX_QUOTA_BIN` only if you have a custom setup. |
 
-Make sure `gh` and your chosen worker backend are both authenticated for the
-same OS user before starting any background runtime.
+Make sure your chosen worker backend is authenticated for the same OS user
+before starting any background runtime. For GitHub-first setups, authenticate
+`gh`. For Gitea local-first setups, provide `--gitea-base-url` plus a token or
+username/password during setup so ACP can write issues, PR comments, and labels.
 
 ## Install
 
@@ -313,7 +365,7 @@ npx agent-control-plane@latest setup
 The wizard walks you through the full setup in one pass:
 
 1. Detects the current repo and suggests sane defaults
-2. Installs missing dependencies and authenticates `gh`
+2. Captures forge mode (`github` or `gitea`) and the auth/settings that mode needs
 3. Checks backend readiness (API keys for openclaw/pi, local server for ollama)
 4. Scaffolds the profile, runs health checks, starts the runtime
 5. Launches the monitoring dashboard in the background
@@ -343,16 +395,41 @@ npx agent-control-plane@latest setup \
 With `--json`, ACP emits a single structured object on `stdout` and sends
 progress logs to `stderr`, which keeps parsing stable.
 
+Example: local-first Gitea setup
+
+```bash
+npx agent-control-plane@latest setup \
+  --forge-provider gitea \
+  --repo-slug acp-admin/my-repo \
+  --gitea-base-url http://127.0.0.1:3000 \
+  --gitea-token <token> \
+  --start-runtime \
+  --start-dashboard
+```
+
+This writes the forge settings into the profile `runtime.env`, so later
+heartbeat, reconcile, and publish steps keep talking to the same Gitea
+instance without extra shell exports.
+
 ### Option B — Manual setup
 
 If you prefer explicit control over each step:
 
-**1. Authenticate GitHub**
+**1. Authenticate the working forge**
 
 ```bash
 gh auth login
 ```
 
+For Gitea local-first, skip `gh auth login` and pass Gitea settings directly to
+`setup` or `init`:
+
+```bash
+--forge-provider gitea \
+--gitea-base-url http://127.0.0.1:3000 \
+--gitea-token <token>
+```
+
 **2. Install the packaged runtime**
 
 ```bash
@@ -368,6 +445,7 @@ re-run after upgrades.
 npx agent-control-plane@latest init \
   --profile-id my-repo \
   --repo-slug owner/my-repo \
+  --forge-provider github \
   --repo-root ~/src/my-repo \
   --agent-root ~/.agent-runtime/projects/my-repo \
   --worktree-root ~/src/my-repo-worktrees \
@@ -377,7 +455,9 @@ npx agent-control-plane@latest init \
 | Flag | Purpose |
 | --- | --- |
 | `--profile-id` | Short name used in all ACP commands |
-| `--repo-slug` | GitHub repo ACP should track |
+| `--repo-slug` | Forge repo ACP should track |
+| `--forge-provider` | Which forge ACP should automate (`github` or `gitea`) |
+| `--gitea-base-url` | Base URL when `--forge-provider gitea` |
 | `--repo-root` | Path to your local checkout |
 | `--agent-root` | Where ACP keeps per-project runtime state |
 | `--worktree-root` | Where ACP places repo worktrees |
@@ -407,9 +487,8 @@ grouped and inspectable without digging through scattered temp files.
 ## Starter Issues
 
 The setup wizard can create a set of recurring `agent-keep-open` issues on your
-repo so ACP starts working immediately after installation. Each issue carries the
-`agent-ready` and `agent-keep-open` labels, and ACP picks them up on its next
-heartbeat cycle.
+repo so ACP starts working immediately after installation. ACP picks them up on
+its next heartbeat cycle without requiring a separate readiness label.
 
 Built-in templates:
 
@@ -421,9 +500,9 @@ Built-in templates:
 | Dependency audit | Fix vulnerabilities and update safe patches |
 | Refactoring sweep | Reduce complexity and duplication |
 
-You can also create your own recurring issues — just add the `agent-ready` and
-`agent-keep-open` labels to any GitHub issue and ACP will work on it
-continuously.
+You can also create your own recurring issues by adding the
+`agent-keep-open` label to any GitHub issue. ACP will keep revisiting that
+issue continuously unless it is blocked or already claimed by an open agent PR.
 
 To skip this step during setup, pass `--no-create-starter-issues`.
 
@@ -472,6 +551,40 @@ npx agent-control-plane@latest launchd-uninstall --profile-id my-repo
 
 These commands are macOS-only and manage per-user `launchd` agents.
 
+## Windows (WSL2) Autostart
+
+ACP runs inside WSL2 (Windows Subsystem for Linux) where it uses systemd for service management. This requires WSL2 with systemd enabled (Windows 11 22H2+).
+
+**Prerequisites:**
+1. Install WSL2 with Ubuntu: `wsl --install -d Ubuntu` (in PowerShell Admin)
+2. Enable systemd in WSL2 (create `/etc/wsl.conf` with `[boot] systemd=true`)
+3. Run `wsl --shutdown` from PowerShell, then restart WSL2
+
+**Install project service in WSL2:**
+
+```bash
+# Inside WSL2 Ubuntu terminal
+cd /mnt/c/Users/You/Projects/your-repo
+
+# Bootstrap systemd service (same as Linux)
+agent-control-plane project systemd-bootstrap \
+  --project-dir . \
+  --repo-url https://github.com/your-org/your-repo.git \
+  --worker-type claude \
+  --schedule "*/30 * * * *" \
+  --issues "1,2,3"
+```
+
+**Manage the service:**
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now agent-control-plane@$(basename $(pwd)).timer
+systemctl --user status agent-control-plane@$(basename $(pwd)).timer
+```
+
+See [WSL2_SETUP.md](docs/WSL2_SETUP.md) for full setup guide, Docker in WSL2, and troubleshooting.
+
 ## Update
 
 After upgrading the package, refresh the runtime and verify health:

package/assets/workflow-catalog.json

@@ -7,7 +7,7 @@
     {
       "id": "issue-implementation",
       "kind": "issue",
-      "trigger": "Open issue with agent-ready and without agent-running/agent-blocked",
+      "trigger": "Open issue without agent-running, without an open agent PR claim, and not blocked by retry policy",
       "entrypoint": "tools/bin/start-issue-worker.sh",
       "summary": "Primary implementation loop for focused issues that should end in a PR or a blocked report."
     },

package/bin/pr-risk.sh

@@ -26,10 +26,10 @@ fi
 gh_api_json_matching_or_fallback() {
   local fallback="${1:?fallback required}"
   local jq_filter="${2:?jq filter required}"
-  shift 2
+  local route="${3:?route required}"
   local output=""
 
-  output="$(gh api "$@" 2>/dev/null || true)"
+  output="$(flow_github_api_repo "${REPO_SLUG}" "${route}" 2>/dev/null || true)"
   if jq -e "${jq_filter}" >/dev/null 2>&1 <<<"${output}"; then
     printf '%s\n' "${output}"
     return 0
@@ -38,17 +38,32 @@ gh_api_json_matching_or_fallback() {
   printf '%s\n' "${fallback}"
 }
 
-PR_JSON="$(gh pr view "$PR_NUMBER" -R "$REPO_SLUG" --json number,title,url,body,isDraft,headRefName,headRefOid,baseRefName,labels,files,mergeStateStatus,reviewDecision,reviewRequests,statusCheckRollup,comments 2>/dev/null)" \
-  || { printf 'pr-risk: gh pr view failed for PR %s (repo: %s)\n' "$PR_NUMBER" "$REPO_SLUG" >&2; exit 1; }
+PR_JSON="$(flow_github_pr_view_json "$REPO_SLUG" "$PR_NUMBER" 2>/dev/null || true)"
+if ! jq -e '.number? != null' >/dev/null 2>&1 <<<"${PR_JSON:-}"; then
+  if flow_using_gitea; then
+    printf 'pr-risk: forge PR view failed for PR %s (repo: %s)\n' "$PR_NUMBER" "$REPO_SLUG" >&2
+    exit 1
+  fi
+  PR_JSON="$(gh pr view "$PR_NUMBER" -R "$REPO_SLUG" --json number,title,url,body,isDraft,headRefName,headRefOid,baseRefName,labels,files,mergeStateStatus,reviewDecision,reviewRequests,statusCheckRollup,comments 2>/dev/null)" \
+    || { printf 'pr-risk: forge PR view failed for PR %s (repo: %s)\n' "$PR_NUMBER" "$REPO_SLUG" >&2; exit 1; }
+fi
 PR_HEAD_SHA="$(jq -r '.headRefOid // ""' <<<"$PR_JSON")"
 PR_HEAD_COMMITTED_AT=""
 if [[ -n "${PR_HEAD_SHA}" ]]; then
-  PR_HEAD_COMMITTED_AT="$(gh api "repos/${REPO_SLUG}/commits/${PR_HEAD_SHA}" --jq .commit.committer.date 2>/dev/null || true)"
+  PR_HEAD_COMMITTED_AT="$(
+    flow_github_api_repo "${REPO_SLUG}" "commits/${PR_HEAD_SHA}" 2>/dev/null \
+      | jq -r '.commit.committer.date // .commit.author.date // .created // .timestamp // ""' 2>/dev/null \
+      || true
+  )"
+fi
+if flow_using_gitea; then
+  REVIEW_COMMENTS_JSON='[]'
+else
+  REVIEW_COMMENTS_JSON="$(gh_api_json_matching_or_fallback '[]' 'type == "array"' "pulls/${PR_NUMBER}/comments")"
 fi
-REVIEW_COMMENTS_JSON="$(gh_api_json_matching_or_fallback '[]' 'type == "array"' "repos/${REPO_SLUG}/pulls/${PR_NUMBER}/comments")"
 CHECK_RUNS_JSON='{"check_runs":[]}'
 if [[ -n "${PR_HEAD_SHA}" ]]; then
-  CHECK_RUNS_JSON="$(gh_api_json_matching_or_fallback '{"check_runs":[]}' 'type == "object" and ((.check_runs // []) | type == "array")' "repos/${REPO_SLUG}/commits/${PR_HEAD_SHA}/check-runs")"
+  CHECK_RUNS_JSON="$(gh_api_json_matching_or_fallback '{"check_runs":[]}' 'type == "object" and ((.check_runs // []) | type == "array")' "commits/${PR_HEAD_SHA}/check-runs")"
 fi
 
 PR_JSON="$PR_JSON" PR_HEAD_SHA="$PR_HEAD_SHA" PR_HEAD_COMMITTED_AT="$PR_HEAD_COMMITTED_AT" REVIEW_COMMENTS_JSON="$REVIEW_COMMENTS_JSON" CHECK_RUNS_JSON="$CHECK_RUNS_JSON" PR_LANE_OVERRIDE="${PR_LANE_OVERRIDE:-}" MANAGED_PR_PREFIXES_JSON="$MANAGED_PR_PREFIXES_JSON" MANAGED_PR_ISSUE_CAPTURE_REGEX="$MANAGED_PR_ISSUE_CAPTURE_REGEX" ALLOW_INFRA_CI_BYPASS="$ALLOW_INFRA_CI_BYPASS" LOCAL_FIRST_PR_POLICY="$LOCAL_FIRST_PR_POLICY" node <<'EOF'

package/bin/sync-pr-labels.sh

@@ -100,7 +100,7 @@ fi
 bash "${FLOW_TOOLS_DIR}/agent-github-update-labels" --repo-slug "$REPO_SLUG" --number "$PR_NUMBER" "${args[@]}" >/dev/null
 
 if [[ -n "$linked_issue_id" ]]; then
-  bash "${FLOW_TOOLS_DIR}/agent-github-update-labels" --repo-slug "$REPO_SLUG" --number "$linked_issue_id" --remove agent-ready --remove agent-running >/dev/null || true
+  bash "${FLOW_TOOLS_DIR}/agent-github-update-labels" --repo-slug "$REPO_SLUG" --number "$linked_issue_id" --remove agent-running >/dev/null || true
 fi
 
 printf 'PR_NUMBER=%s\n' "$PR_NUMBER"

package/hooks/heartbeat-hooks.sh

@@ -36,13 +36,115 @@ HEARTBEAT_SNAPSHOT_CACHE_DIR="${TMPDIR:-/tmp}/heartbeat-snapshot.$$"
 # pipes), so in-memory variables would be lost immediately.  We rely exclusively
 # on the PID-scoped disk cache under HEARTBEAT_SNAPSHOT_CACHE_DIR.
 
+heartbeat_github_mirror_dir() {
+  [[ -n "${STATE_ROOT:-}" ]] || return 1
+  printf '%s/github-mirror/heartbeat\n' "${STATE_ROOT}"
+}
+
+heartbeat_github_mirror_file() {
+  local mirror_key="${1:?mirror key required}"
+  local mirror_dir=""
+  mirror_dir="$(heartbeat_github_mirror_dir)" || return 1
+  printf '%s/%s.json\n' "${mirror_dir}" "${mirror_key}"
+}
+
+heartbeat_json_matches_kind() {
+  local payload="${1:-}"
+  local expected_kind="${2:-}"
+
+  [[ -n "${payload}" && -n "${expected_kind}" ]] || return 1
+  jq -e --arg kind "${expected_kind}" 'type == $kind' >/dev/null <<<"${payload}"
+}
+
+heartbeat_write_json_mirror() {
+  local mirror_key="${1:?mirror key required}"
+  local payload="${2:-}"
+  local expected_kind="${3:?expected kind required}"
+  local source_mode="${4:-live}"
+  local mirror_file=""
+  local mirror_dir=""
+  local meta_file=""
+  local tmp_file=""
+  local meta_tmp_file=""
+  local updated_at=""
+
+  heartbeat_json_matches_kind "${payload}" "${expected_kind}" || return 1
+  mirror_dir="$(heartbeat_github_mirror_dir)" || return 1
+  mirror_file="${mirror_dir}/${mirror_key}.json"
+  meta_file="${mirror_dir}/${mirror_key}.env"
+  mkdir -p "${mirror_dir}"
+  updated_at="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  tmp_file="${mirror_file}.tmp.$$"
+  meta_tmp_file="${meta_file}.tmp.$$"
+  printf '%s' "${payload}" >"${tmp_file}"
+  {
+    printf 'MIRROR_KEY=%s\n' "${mirror_key}"
+    printf 'JSON_KIND=%s\n' "${expected_kind}"
+    printf 'SOURCE=%s\n' "${source_mode}"
+    printf 'UPDATED_AT=%s\n' "${updated_at}"
+  } >"${meta_tmp_file}"
+  mv "${tmp_file}" "${mirror_file}"
+  mv "${meta_tmp_file}" "${meta_file}"
+}
+
+heartbeat_read_json_mirror() {
+  local mirror_key="${1:?mirror key required}"
+  local expected_kind="${2:?expected kind required}"
+  local default_json="${3:-}"
+  local mirror_file=""
+  local payload=""
+
+  mirror_file="$(heartbeat_github_mirror_file "${mirror_key}" 2>/dev/null || true)"
+  if [[ -n "${mirror_file}" && -f "${mirror_file}" ]]; then
+    payload="$(cat "${mirror_file}" 2>/dev/null || true)"
+    if heartbeat_json_matches_kind "${payload}" "${expected_kind}"; then
+      printf '%s\n' "${payload}"
+      return 0
+    fi
+  fi
+
+  printf '%s\n' "${default_json}"
+}
+
+heartbeat_cached_json_with_local_mirror() {
+  local cache_file="${1:?cache file required}"
+  local mirror_key="${2:?mirror key required}"
+  local expected_kind="${3:?expected kind required}"
+  local default_json="${4:-}"
+  local live_fetch_fn="${5:?live fetch function required}"
+  local payload=""
+
+  shift 5
+
+  if [[ -f "${cache_file}" ]]; then
+    cat "${cache_file}"
+    return 0
+  fi
+
+  if payload="$("${live_fetch_fn}" "$@" 2>/dev/null)" && heartbeat_json_matches_kind "${payload}" "${expected_kind}"; then
+    heartbeat_write_json_mirror "${mirror_key}" "${payload}" "${expected_kind}" "live" || true
+  else
+    payload="$(heartbeat_read_json_mirror "${mirror_key}" "${expected_kind}" "${default_json}")"
+  fi
+
+  printf '%s' "${payload}" >"${cache_file}"
+  printf '%s\n' "${payload}"
+}
+
 heartbeat_cached_issue_list_json() {
   mkdir -p "${HEARTBEAT_SNAPSHOT_CACHE_DIR}"
   local cache_file="${HEARTBEAT_SNAPSHOT_CACHE_DIR}/issues.json"
   if [[ ! -f "${cache_file}" ]]; then
-    local snapshot
-    snapshot="$(flow_github_issue_list_json "$REPO_SLUG" open 100 2>/dev/null || true)"
-    printf '%s' "${snapshot}" >"${cache_file}"
+    heartbeat_cached_json_with_local_mirror \
+      "${cache_file}" \
+      "issues-open-100" \
+      "array" \
+      '[]' \
+      flow_github_issue_list_json_live \
+      "$REPO_SLUG" \
+      open \
+      100
+    return 0
   fi
   cat "${cache_file}"
 }
@@ -51,9 +153,16 @@ heartbeat_cached_pr_list_json() {
   mkdir -p "${HEARTBEAT_SNAPSHOT_CACHE_DIR}"
   local cache_file="${HEARTBEAT_SNAPSHOT_CACHE_DIR}/prs.json"
   if [[ ! -f "${cache_file}" ]]; then
-    local snapshot
-    snapshot="$(flow_github_pr_list_json "$REPO_SLUG" open 100 2>/dev/null || true)"
-    printf '%s' "${snapshot}" >"${cache_file}"
+    heartbeat_cached_json_with_local_mirror \
+      "${cache_file}" \
+      "prs-open-100" \
+      "array" \
+      '[]' \
+      flow_github_pr_list_json_live \
+      "$REPO_SLUG" \
+      open \
+      100
+    return 0
   fi
   cat "${cache_file}"
 }
@@ -111,7 +220,6 @@ heartbeat_retry_reason_is_baseline_blocked() {
 heartbeat_issue_json_cached() {
   local issue_id="${1:?issue id required}"
   local cache_file=""
-  local issue_json=""
 
   if [[ ! -d "${HEARTBEAT_ISSUE_JSON_CACHE_DIR}" ]]; then
     mkdir -p "${HEARTBEAT_ISSUE_JSON_CACHE_DIR}"
@@ -123,9 +231,14 @@ heartbeat_issue_json_cached() {
     return 0
   fi
 
-  issue_json="$(flow_github_issue_view_json "$REPO_SLUG" "$issue_id" 2>/dev/null || true)"
-  printf '%s' "${issue_json}" >"${cache_file}"
-  printf '%s\n' "${issue_json}"
+  heartbeat_cached_json_with_local_mirror \
+    "${cache_file}" \
+    "issue-${issue_id}" \
+    "object" \
+    '{}' \
+    flow_github_issue_view_json_live \
+    "$REPO_SLUG" \
+    "$issue_id"
 }
 
 heartbeat_open_agent_pr_issue_ids() {
@@ -483,9 +596,9 @@ heartbeat_mark_issue_running() {
   local cached_json
   cached_json="$(heartbeat_issue_json_cached "$issue_id" 2>/dev/null || true)"
   if [[ "$is_heavy" == "yes" ]]; then
-    ACP_CACHED_ISSUE_JSON="${cached_json}" bash "${FLOW_TOOLS_DIR}/agent-github-update-labels" --repo-slug "$REPO_SLUG" --number "$issue_id" --remove agent-ready --remove agent-blocked --add agent-running --add agent-e2e-heavy >/dev/null || true
+    ACP_CACHED_ISSUE_JSON="${cached_json}" bash "${FLOW_TOOLS_DIR}/agent-github-update-labels" --repo-slug "$REPO_SLUG" --number "$issue_id" --remove agent-blocked --add agent-running --add agent-e2e-heavy >/dev/null || true
   else
-    ACP_CACHED_ISSUE_JSON="${cached_json}" bash "${FLOW_TOOLS_DIR}/agent-github-update-labels" --repo-slug "$REPO_SLUG" --number "$issue_id" --remove agent-ready --remove agent-blocked --add agent-running >/dev/null || true
+    ACP_CACHED_ISSUE_JSON="${cached_json}" bash "${FLOW_TOOLS_DIR}/agent-github-update-labels" --repo-slug "$REPO_SLUG" --number "$issue_id" --remove agent-blocked --add agent-running >/dev/null || true
   fi
 }
 

package/hooks/issue-reconcile-hooks.sh

@@ -218,7 +218,7 @@ issue_publish_extra_args() {
 }
 
 issue_remove_running() {
-  bash "${FLOW_TOOLS_DIR}/agent-github-update-labels" --repo-slug "${REPO_SLUG}" --number "$ISSUE_ID" --remove agent-ready --remove agent-running --remove agent-blocked >/dev/null || true
+  bash "${FLOW_TOOLS_DIR}/agent-github-update-labels" --repo-slug "${REPO_SLUG}" --number "$ISSUE_ID" --remove agent-running --remove agent-blocked >/dev/null || true
 }
 
 issue_mark_blocked() {

package/hooks/pr-reconcile-hooks.sh

@@ -75,7 +75,7 @@ pr_cleanup_linked_issue_session() {
 
   local should_close
   should_close="$(pr_linked_issue_should_close "$issue_id")"
-  update_args=(--remove agent-ready --remove agent-running --remove agent-blocked --remove agent-e2e-heavy --remove agent-automerge --remove agent-exclusive)
+  update_args=(--remove agent-running --remove agent-blocked --remove agent-e2e-heavy --remove agent-automerge --remove agent-exclusive)
   pr_best_effort_update_labels --repo-slug "${REPO_SLUG}" --number "$issue_id" "${update_args[@]}"
 
   local issue_session="${ISSUE_SESSION_PREFIX}${issue_id}"