agent-control-plane 0.1.0

package/tools/bin/render-dashboard-demo-media.sh

@@ -0,0 +1,333 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+OUTPUT_DIR="${ROOT_DIR}/assets/readme"
+PNG_OUT="${OUTPUT_DIR}/dashboard-demo.png"
+GIF_OUT="${OUTPUT_DIR}/dashboard-demo.gif"
+
+require_bin() {
+  local name="$1"
+  if ! command -v "$name" >/dev/null 2>&1; then
+    echo "missing required dependency: $name" >&2
+    exit 1
+  fi
+}
+
+require_bin python3
+require_bin ffmpeg
+require_bin playwright
+require_bin curl
+
+PLAYWRIGHT_CLI="$(command -v playwright)"
+PLAYWRIGHT_PACKAGE_ROOT="$(
+  python3 - "$PLAYWRIGHT_CLI" <<'PY'
+import os
+import sys
+
+print(os.path.dirname(os.path.realpath(sys.argv[1])))
+PY
+)"
+
+tmpdir="$(mktemp -d)"
+server_pid=""
+controller_pid=""
+port="$(
+  python3 - <<'PY'
+import socket
+
+sock = socket.socket()
+sock.bind(("127.0.0.1", 0))
+print(sock.getsockname()[1])
+sock.close()
+PY
+)"
+
+cleanup() {
+  if [[ -n "${server_pid}" ]]; then
+    kill "${server_pid}" >/dev/null 2>&1 || true
+    wait "${server_pid}" 2>/dev/null || true
+  fi
+  if [[ -n "${controller_pid}" ]]; then
+    kill "${controller_pid}" >/dev/null 2>&1 || true
+    wait "${controller_pid}" 2>/dev/null || true
+  fi
+  rm -rf "${tmpdir}"
+}
+trap cleanup EXIT
+
+profile_registry_root="${tmpdir}/profiles"
+profile_dir="${profile_registry_root}/demo-retail"
+runs_root="${tmpdir}/runtime/demo-retail/runs"
+state_root="${tmpdir}/runtime/demo-retail/state"
+frames_dir="${tmpdir}/frames"
+mkdir -p \
+  "${profile_dir}" \
+  "${runs_root}/demo-issue-14" \
+  "${runs_root}/demo-issue-17" \
+  "${runs_root}/demo-issue-21" \
+  "${state_root}/resident-workers/issues/14" \
+  "${state_root}/resident-workers/issues/issue-lane-recurring-general-openclaw-safe" \
+  "${state_root}/retries/providers" \
+  "${state_root}/scheduled-issues" \
+  "${state_root}/resident-workers/issue-queue/pending" \
+  "${frames_dir}" \
+  "${OUTPUT_DIR}"
+
+sleep 600 &
+controller_pid="$!"
+
+cat >"${profile_dir}/control-plane.yaml" <<EOF
+schema_version: "1"
+id: "demo-retail"
+repo:
+  slug: "example/retail-agent-demo"
+  root: "${tmpdir}/repo"
+  default_branch: "main"
+runtime:
+  orchestrator_agent_root: "${tmpdir}/runtime/demo-retail"
+  worktree_root: "${tmpdir}/worktrees"
+  agent_repo_root: "${tmpdir}/repo"
+  runs_root: "${runs_root}"
+  state_root: "${state_root}"
+  history_root: "${tmpdir}/runtime/demo-retail/history"
+  retained_repo_root: "${tmpdir}/repo"
+  vscode_workspace_file: "${tmpdir}/demo-retail.code-workspace"
+session_naming:
+  issue_prefix: "demo-issue-"
+  pr_prefix: "demo-pr-"
+execution:
+  coding_worker: "openclaw"
+  openclaw:
+    model: "openrouter/sonic"
+    thinking: "adaptive"
+    timeout_seconds: 900
+EOF
+
+cat >"${runs_root}/demo-issue-14/run.env" <<'EOF'
+TASK_KIND=issue
+TASK_ID=14
+SESSION=demo-issue-14
+MODE=safe
+STARTED_AT=2026-03-27T15:00:00Z
+CODING_WORKER=openclaw
+WORKTREE=/tmp/demo-worktree-14
+BRANCH=agent/demo/issue-14
+RESIDENT_WORKER_KEY=issue-lane-recurring-general-openclaw-safe
+OPENCLAW_MODEL=openrouter/sonic
+EOF
+
+cat >"${runs_root}/demo-issue-14/runner.env" <<'EOF'
+RUNNER_STATE=succeeded
+THREAD_ID=thread-demo-14
+LAST_EXIT_CODE=0
+UPDATED_AT=2026-03-27T15:04:00Z
+EOF
+
+cat >"${runs_root}/demo-issue-14/result.env" <<'EOF'
+OUTCOME=implemented
+ACTION=host-publish-issue-pr
+EOF
+
+cat >"${runs_root}/demo-issue-17/run.env" <<'EOF'
+TASK_KIND=issue
+TASK_ID=17
+SESSION=demo-issue-17
+MODE=safe
+STARTED_AT=2026-03-27T15:05:00Z
+CODING_WORKER=openclaw
+WORKTREE=/tmp/demo-worktree-17
+BRANCH=agent/demo/issue-17
+OPENCLAW_MODEL=openrouter/sonic
+EOF
+
+cat >"${runs_root}/demo-issue-17/runner.env" <<'EOF'
+RUNNER_STATE=succeeded
+THREAD_ID=thread-demo-17
+LAST_EXIT_CODE=0
+UPDATED_AT=2026-03-27T15:08:00Z
+EOF
+
+cat >"${runs_root}/demo-issue-17/result.env" <<'EOF'
+OUTCOME=reported
+ACTION=host-comment-scheduled-report
+EOF
+
+cat >"${runs_root}/demo-issue-21/run.env" <<'EOF'
+TASK_KIND=issue
+TASK_ID=21
+SESSION=demo-issue-21
+MODE=safe
+STARTED_AT=2026-03-27T15:10:00Z
+CODING_WORKER=openclaw
+WORKTREE=/tmp/demo-worktree-21
+BRANCH=agent/demo/issue-21
+OPENCLAW_MODEL=openrouter/sonic
+EOF
+
+cat >"${runs_root}/demo-issue-21/runner.env" <<'EOF'
+RUNNER_STATE=succeeded
+THREAD_ID=thread-demo-21
+LAST_EXIT_CODE=0
+UPDATED_AT=2026-03-27T15:12:00Z
+EOF
+
+cat >"${runs_root}/demo-issue-21/result.env" <<'EOF'
+OUTCOME=blocked
+ACTION=host-comment-blocked
+FAILURE_REASON=provider-quota-limit
+EOF
+
+cat >"${state_root}/resident-workers/issues/14/controller.env" <<EOF
+ISSUE_ID=14
+SESSION=demo-issue-14
+CONTROLLER_PID=${controller_pid}
+CONTROLLER_MODE=safe
+CONTROLLER_LOOP_COUNT=4
+CONTROLLER_STATE=waiting-provider
+CONTROLLER_REASON=provider-cooldown
+ACTIVE_RESIDENT_WORKER_KEY=issue-lane-recurring-general-openclaw-safe
+ACTIVE_RESIDENT_LANE_KIND=recurring
+ACTIVE_RESIDENT_LANE_VALUE=general
+ACTIVE_PROVIDER_BACKEND=openclaw
+ACTIVE_PROVIDER_MODEL=openrouter/sonic
+PROVIDER_SWITCH_COUNT=1
+PROVIDER_FAILOVER_COUNT=1
+PROVIDER_WAIT_COUNT=2
+PROVIDER_WAIT_TOTAL_SECONDS=45
+PROVIDER_LAST_WAIT_SECONDS=21
+UPDATED_AT=2026-03-27T15:13:00Z
+EOF
+
+cat >"${state_root}/resident-workers/issues/issue-lane-recurring-general-openclaw-safe/metadata.env" <<'EOF'
+RESIDENT_WORKER_KIND=issue
+RESIDENT_WORKER_SCOPE=lane
+RESIDENT_WORKER_KEY=issue-lane-recurring-general-openclaw-safe
+ISSUE_ID=14
+CODING_WORKER=openclaw
+TASK_COUNT=9
+LAST_STATUS=running
+LAST_STARTED_AT=2026-03-27T15:00:00Z
+LAST_RUN_SESSION=demo-issue-14
+LAST_OUTCOME=implemented
+LAST_ACTION=host-publish-issue-pr
+EOF
+
+cat >"${state_root}/retries/providers/openclaw-openrouter-sonic.env" <<'EOF'
+ATTEMPTS=2
+NEXT_ATTEMPT_EPOCH=4102444800
+NEXT_ATTEMPT_AT=2100-01-01T00:00:00Z
+LAST_REASON=provider-quota-limit
+UPDATED_AT=2026-03-27T15:14:00Z
+EOF
+
+cat >"${state_root}/scheduled-issues/17.env" <<'EOF'
+INTERVAL_SECONDS=1800
+LAST_STARTED_AT=2026-03-27T15:05:00Z
+NEXT_DUE_AT=2026-03-27T15:35:00Z
+UPDATED_AT=2026-03-27T15:05:00Z
+EOF
+
+cat >"${state_root}/scheduled-issues/44.env" <<'EOF'
+INTERVAL_SECONDS=3600
+LAST_STARTED_AT=2026-03-27T14:30:00Z
+NEXT_DUE_AT=2026-03-27T15:30:00Z
+UPDATED_AT=2026-03-27T14:30:00Z
+EOF
+
+cat >"${state_root}/resident-workers/issue-queue/pending/issue-27.env" <<'EOF'
+ISSUE_ID=27
+SESSION=demo-issue-27
+UPDATED_AT=2026-03-27T15:14:00Z
+EOF
+
+cat >"${state_root}/resident-workers/issue-queue/pending/issue-28.env" <<'EOF'
+ISSUE_ID=28
+SESSION=demo-issue-28
+UPDATED_AT=2026-03-27T15:15:00Z
+EOF
+
+ACP_PROFILE_REGISTRY_ROOT="${profile_registry_root}" \
+  python3 "${ROOT_DIR}/tools/dashboard/server.py" \
+  --host 127.0.0.1 \
+  --port "${port}" \
+  >"${tmpdir}/server.log" 2>&1 &
+server_pid="$!"
+
+dashboard_url="http://127.0.0.1:${port}"
+
+for _ in $(seq 1 40); do
+  if curl -sf "${dashboard_url}/api/snapshot.json" >/dev/null 2>&1; then
+    break
+  fi
+  sleep 0.25
+done
+
+if ! curl -sf "${dashboard_url}/api/snapshot.json" >/dev/null 2>&1; then
+  cat "${tmpdir}/server.log" >&2
+  echo "failed to start dashboard demo server" >&2
+  exit 1
+fi
+
+cat >"${tmpdir}/capture-demo.js" <<'EOF'
+const fs = require("fs");
+const path = require("path");
+const { chromium } = require(process.env.PLAYWRIGHT_PACKAGE_ROOT);
+
+async function captureFrame(page, target, filename) {
+  await page.evaluate((top) => window.scrollTo({ top, behavior: "instant" }), target);
+  await page.waitForTimeout(350);
+  await page.screenshot({ path: filename });
+}
+
+(async () => {
+  const pngOut = process.env.ACP_PNG_OUT;
+  const framesDir = process.env.ACP_FRAMES_DIR;
+  const url = process.env.ACP_DEMO_URL;
+
+  fs.mkdirSync(path.dirname(pngOut), { recursive: true });
+  fs.mkdirSync(framesDir, { recursive: true });
+
+  const browser = await chromium.launch({ headless: true });
+  const page = await browser.newPage({
+    viewport: { width: 1440, height: 1080 },
+    deviceScaleFactor: 1,
+    colorScheme: "light",
+  });
+
+  await page.goto(url, { waitUntil: "networkidle" });
+  await page.waitForTimeout(800);
+  await page.screenshot({ path: pngOut, fullPage: true });
+
+  await captureFrame(page, 0, path.join(framesDir, "frame-00.png"));
+  await page.click("#refresh-button");
+  await page.waitForTimeout(500);
+  await captureFrame(page, 0, path.join(framesDir, "frame-01.png"));
+  await captureFrame(page, 900, path.join(framesDir, "frame-02.png"));
+  await captureFrame(page, 1700, path.join(framesDir, "frame-03.png"));
+  await captureFrame(page, 0, path.join(framesDir, "frame-04.png"));
+
+  await browser.close();
+})().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+EOF
+
+PLAYWRIGHT_PACKAGE_ROOT="${PLAYWRIGHT_PACKAGE_ROOT}" \
+ACP_DEMO_URL="${dashboard_url}" \
+ACP_PNG_OUT="${PNG_OUT}" \
+ACP_FRAMES_DIR="${frames_dir}" \
+node "${tmpdir}/capture-demo.js"
+
+ffmpeg \
+  -y \
+  -framerate 1.25 \
+  -i "${frames_dir}/frame-%02d.png" \
+  -vf "fps=10,scale=1200:-1:flags=lanczos,split[s0][s1];[s0]palettegen=stats_mode=diff[p];[s1][p]paletteuse=dither=bayer" \
+  "${GIF_OUT}" \
+  >/dev/null 2>&1
+
+echo "DASHBOARD_DEMO_URL=${dashboard_url}"
+echo "PNG_OUT=${PNG_OUT}"
+echo "GIF_OUT=${GIF_OUT}"

package/tools/bin/render-dashboard-snapshot.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import pathlib
+import sys
+
+
+ROOT = pathlib.Path(__file__).resolve().parents[1] / "dashboard"
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from dashboard_snapshot import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/tools/bin/render-flow-config.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/flow-config-lib.sh"
+
+FLOW_SKILL_DIR="$(resolve_flow_skill_dir "${BASH_SOURCE[0]}")"
+PROFILE_REGISTRY_ROOT="$(resolve_flow_profile_registry_root)"
+CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+flow_export_execution_env "${CONFIG_YAML}"
+AVAILABLE_PROFILES="$(flow_list_profile_ids "${FLOW_SKILL_DIR}" | paste -sd, -)"
+INSTALLED_PROFILES="$(flow_list_installed_profile_ids | paste -sd, -)"
+PROFILE_ID="$(flow_resolve_adapter_id "${CONFIG_YAML}")"
+PROFILE_SELECTION_MODE="$(flow_profile_selection_mode "${FLOW_SKILL_DIR}")"
+PROFILE_SELECTION_HINT="$(flow_profile_selection_hint "${FLOW_SKILL_DIR}")"
+PROFILE_NOTES="$(flow_resolve_profile_notes_file "${CONFIG_YAML}")"
+
+config_or_env() {
+  local env_names="${1:?env names required}"
+  local config_key="${2:-}"
+  local env_name=""
+  local value=""
+
+  for env_name in ${env_names}; do
+    value="${!env_name:-}"
+    if [[ -n "${value}" ]]; then
+      printf '%s\n' "${value}"
+      return 0
+    fi
+  done
+
+  if [[ -n "${config_key}" && -f "${CONFIG_YAML}" ]]; then
+    flow_config_get "${CONFIG_YAML}" "${config_key}"
+    return 0
+  fi
+
+  printf '\n'
+}
+
+printf 'FLOW_SKILL_DIR=%s\n' "${FLOW_SKILL_DIR}"
+printf 'PROFILE_REGISTRY_ROOT=%s\n' "${PROFILE_REGISTRY_ROOT}"
+printf 'CONFIG_YAML=%s\n' "${CONFIG_YAML}"
+printf 'PROFILE_ID=%s\n' "${PROFILE_ID}"
+printf 'PROFILE_SELECTION_MODE=%s\n' "${PROFILE_SELECTION_MODE}"
+if [[ -n "${PROFILE_SELECTION_HINT}" ]]; then
+  printf 'PROFILE_SELECTION_HINT=%s\n' "${PROFILE_SELECTION_HINT}"
+fi
+printf 'AVAILABLE_PROFILES=%s\n' "${AVAILABLE_PROFILES}"
+printf 'INSTALLED_PROFILES=%s\n' "${INSTALLED_PROFILES}"
+printf 'PROFILE_NOTES=%s\n' "${PROFILE_NOTES}"
+if [[ -f "${PROFILE_NOTES}" ]]; then
+  printf 'PROFILE_NOTES_EXISTS=yes\n'
+else
+  printf 'PROFILE_NOTES_EXISTS=no\n'
+fi
+printf 'EFFECTIVE_REPO_ROOT=%s\n' "$(config_or_env 'ACP_REPO_ROOT F_LOSNING_REPO_ROOT' repo.root)"
+printf 'EFFECTIVE_AGENT_REPO_ROOT=%s\n' "$(config_or_env 'ACP_AGENT_REPO_ROOT F_LOSNING_AGENT_REPO_ROOT' runtime.agent_repo_root)"
+printf 'EFFECTIVE_WORKTREE_ROOT=%s\n' "$(config_or_env 'ACP_WORKTREE_ROOT F_LOSNING_WORKTREE_ROOT' runtime.worktree_root)"
+printf 'EFFECTIVE_RUNS_ROOT=%s\n' "$(config_or_env 'ACP_RUNS_ROOT F_LOSNING_RUNS_ROOT' runtime.runs_root)"
+printf 'EFFECTIVE_STATE_ROOT=%s\n' "$(config_or_env 'ACP_STATE_ROOT F_LOSNING_STATE_ROOT' runtime.state_root)"
+printf 'EFFECTIVE_RETAINED_REPO_ROOT=%s\n' "$(config_or_env 'ACP_RETAINED_REPO_ROOT F_LOSNING_RETAINED_REPO_ROOT' runtime.retained_repo_root)"
+printf 'EFFECTIVE_VSCODE_WORKSPACE_FILE=%s\n' "$(config_or_env 'ACP_VSCODE_WORKSPACE_FILE F_LOSNING_VSCODE_WORKSPACE_FILE' runtime.vscode_workspace_file)"
+printf 'EFFECTIVE_CODING_WORKER=%s\n' "$(config_or_env 'ACP_CODING_WORKER F_LOSNING_CODING_WORKER' execution.coding_worker)"
+printf 'EFFECTIVE_PROVIDER_QUOTA_COOLDOWNS=%s\n' "$(config_or_env 'ACP_PROVIDER_QUOTA_COOLDOWNS F_LOSNING_PROVIDER_QUOTA_COOLDOWNS' execution.provider_quota.cooldowns)"
+printf 'EFFECTIVE_PROVIDER_POOL_ORDER=%s\n' "$(config_or_env 'ACP_PROVIDER_POOL_ORDER F_LOSNING_PROVIDER_POOL_ORDER' execution.provider_pool_order)"
+printf 'EFFECTIVE_PROVIDER_POOL_NAME=%s\n' "$(config_or_env 'ACP_ACTIVE_PROVIDER_POOL_NAME F_LOSNING_ACTIVE_PROVIDER_POOL_NAME')"
+printf 'EFFECTIVE_PROVIDER_POOL_BACKEND=%s\n' "$(config_or_env 'ACP_ACTIVE_PROVIDER_BACKEND F_LOSNING_ACTIVE_PROVIDER_BACKEND')"
+printf 'EFFECTIVE_PROVIDER_POOL_MODEL=%s\n' "$(config_or_env 'ACP_ACTIVE_PROVIDER_MODEL F_LOSNING_ACTIVE_PROVIDER_MODEL')"
+printf 'EFFECTIVE_PROVIDER_POOL_KEY=%s\n' "$(config_or_env 'ACP_ACTIVE_PROVIDER_KEY F_LOSNING_ACTIVE_PROVIDER_KEY')"
+printf 'EFFECTIVE_PROVIDER_POOLS_EXHAUSTED=%s\n' "$(config_or_env 'ACP_PROVIDER_POOLS_EXHAUSTED F_LOSNING_PROVIDER_POOLS_EXHAUSTED')"
+printf 'EFFECTIVE_PROVIDER_POOL_SELECTION_REASON=%s\n' "$(config_or_env 'ACP_PROVIDER_POOL_SELECTION_REASON F_LOSNING_PROVIDER_POOL_SELECTION_REASON')"
+printf 'EFFECTIVE_PROVIDER_POOL_NEXT_ATTEMPT_EPOCH=%s\n' "$(config_or_env 'ACP_PROVIDER_POOL_NEXT_ATTEMPT_EPOCH F_LOSNING_PROVIDER_POOL_NEXT_ATTEMPT_EPOCH')"
+printf 'EFFECTIVE_PROVIDER_POOL_NEXT_ATTEMPT_AT=%s\n' "$(config_or_env 'ACP_PROVIDER_POOL_NEXT_ATTEMPT_AT F_LOSNING_PROVIDER_POOL_NEXT_ATTEMPT_AT')"
+printf 'EFFECTIVE_PROVIDER_POOL_LAST_REASON=%s\n' "$(config_or_env 'ACP_PROVIDER_POOL_LAST_REASON F_LOSNING_PROVIDER_POOL_LAST_REASON')"
+printf 'EFFECTIVE_CODEX_PROFILE_SAFE=%s\n' "$(config_or_env 'ACP_CODEX_PROFILE_SAFE F_LOSNING_CODEX_PROFILE_SAFE' execution.safe_profile)"
+printf 'EFFECTIVE_CODEX_PROFILE_BYPASS=%s\n' "$(config_or_env 'ACP_CODEX_PROFILE_BYPASS F_LOSNING_CODEX_PROFILE_BYPASS' execution.bypass_profile)"
+printf 'EFFECTIVE_CLAUDE_MODEL=%s\n' "$(config_or_env 'ACP_CLAUDE_MODEL F_LOSNING_CLAUDE_MODEL' execution.claude.model)"
+printf 'EFFECTIVE_CLAUDE_PERMISSION_MODE=%s\n' "$(config_or_env 'ACP_CLAUDE_PERMISSION_MODE F_LOSNING_CLAUDE_PERMISSION_MODE' execution.claude.permission_mode)"
+printf 'EFFECTIVE_CLAUDE_EFFORT=%s\n' "$(config_or_env 'ACP_CLAUDE_EFFORT F_LOSNING_CLAUDE_EFFORT' execution.claude.effort)"
+printf 'EFFECTIVE_CLAUDE_TIMEOUT_SECONDS=%s\n' "$(config_or_env 'ACP_CLAUDE_TIMEOUT_SECONDS F_LOSNING_CLAUDE_TIMEOUT_SECONDS' execution.claude.timeout_seconds)"
+printf 'EFFECTIVE_CLAUDE_MAX_ATTEMPTS=%s\n' "$(config_or_env 'ACP_CLAUDE_MAX_ATTEMPTS F_LOSNING_CLAUDE_MAX_ATTEMPTS' execution.claude.max_attempts)"
+printf 'EFFECTIVE_CLAUDE_RETRY_BACKOFF_SECONDS=%s\n' "$(config_or_env 'ACP_CLAUDE_RETRY_BACKOFF_SECONDS F_LOSNING_CLAUDE_RETRY_BACKOFF_SECONDS' execution.claude.retry_backoff_seconds)"
+printf 'EFFECTIVE_OPENCLAW_MODEL=%s\n' "$(config_or_env 'ACP_OPENCLAW_MODEL F_LOSNING_OPENCLAW_MODEL' execution.openclaw.model)"
+printf 'EFFECTIVE_OPENCLAW_THINKING=%s\n' "$(config_or_env 'ACP_OPENCLAW_THINKING F_LOSNING_OPENCLAW_THINKING' execution.openclaw.thinking)"
+printf 'EFFECTIVE_OPENCLAW_TIMEOUT_SECONDS=%s\n' "$(config_or_env 'ACP_OPENCLAW_TIMEOUT_SECONDS F_LOSNING_OPENCLAW_TIMEOUT_SECONDS' execution.openclaw.timeout_seconds)"

package/tools/bin/retry-state.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/flow-shell-lib.sh"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/flow-config-lib.sh"
+
+KIND="${1:?usage: retry-state.sh issue|pr ID get|schedule|clear [reason]}"
+ITEM_ID="${2:?usage: retry-state.sh issue|pr ID get|schedule|clear [reason]}"
+ACTION="${3:?usage: retry-state.sh issue|pr ID get|schedule|clear [reason]}"
+REASON="${4:-}"
+
+CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+AGENT_ROOT="$(flow_resolve_agent_root "${CONFIG_YAML}")"
+STATE_ROOT="$(flow_resolve_state_root "${CONFIG_YAML}")"
+COOLDOWNS="$(flow_resolve_retry_cooldowns "${CONFIG_YAML}")"
+FLOW_SKILL_DIR="$(resolve_flow_skill_dir "${BASH_SOURCE[0]}")"
+FLOW_TOOLS_DIR="${FLOW_SKILL_DIR}/tools/bin"
+
+ACP_AGENT_ROOT="$AGENT_ROOT" \
+ACP_STATE_ROOT="$STATE_ROOT" \
+ACP_RETRY_COOLDOWNS="$COOLDOWNS" \
+exec bash "${FLOW_TOOLS_DIR}/agent-project-retry-state" \
+  --state-root "$STATE_ROOT" \
+  --kind "$KIND" \
+  --item-id "$ITEM_ID" \
+  --action "$ACTION" \
+  --reason "$REASON" \
+  --cooldowns "$COOLDOWNS"

package/tools/bin/reuse-issue-worktree.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/flow-config-lib.sh"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  reuse-issue-worktree.sh WORKTREE ISSUE_ID [SLUG]
+
+Reset and re-branch an existing managed issue worktree so a recurring issue can
+reuse the same workspace path across multiple cycles.
+EOF
+}
+
+WORKTREE="${1:-}"
+ISSUE_ID="${2:-}"
+SLUG_INPUT="${3:-task}"
+
+if [[ -z "${WORKTREE}" || -z "${ISSUE_ID}" ]]; then
+  usage >&2
+  exit 1
+fi
+
+FLOW_SKILL_DIR="$(resolve_flow_skill_dir "${BASH_SOURCE[0]}")"
+if ! flow_require_explicit_profile_selection "${FLOW_SKILL_DIR}" "reuse-issue-worktree.sh"; then
+  exit 64
+fi
+
+CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+AGENT_REPO_ROOT="$(flow_resolve_agent_repo_root "${CONFIG_YAML}")"
+ISSUE_BRANCH_PREFIX="$(flow_resolve_issue_branch_prefix "${CONFIG_YAML}")"
+DEFAULT_BRANCH="$(flow_resolve_default_branch "${CONFIG_YAML}")"
+BASE_REF="origin/${DEFAULT_BRANCH}"
+PREPARE_SCRIPT="${SCRIPT_DIR}/prepare-worktree.sh"
+
+safe_slug="$(printf '%s' "${SLUG_INPUT}" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-')"
+safe_slug="${safe_slug#-}"
+safe_slug="${safe_slug%-}"
+if [[ -z "${safe_slug}" ]]; then
+  safe_slug="task"
+fi
+
+stamp="$(date +%Y%m%d-%H%M%S)"
+branch_name="${ISSUE_BRANCH_PREFIX}-${ISSUE_ID}-${safe_slug}-${stamp}"
+previous_branch="$(git -C "${WORKTREE}" branch --show-current 2>/dev/null || true)"
+
+if ! git -C "${WORKTREE}" rev-parse --git-dir >/dev/null 2>&1; then
+  echo "invalid managed worktree: ${WORKTREE}" >&2
+  exit 1
+fi
+
+git -C "${AGENT_REPO_ROOT}" fetch \
+  origin \
+  "+refs/heads/${DEFAULT_BRANCH}:refs/remotes/origin/${DEFAULT_BRANCH}" \
+  --prune >/dev/null
+
+# Reset the resident workspace to the latest baseline before switching to the
+# next focused cycle branch.
+git -C "${WORKTREE}" reset --hard >/dev/null
+git -C "${WORKTREE}" clean -fd >/dev/null
+git -C "${WORKTREE}" checkout -B "${branch_name}" "${BASE_REF}" >/dev/null
+
+if [[ -n "${previous_branch}" && "${previous_branch}" != "${branch_name}" ]]; then
+  git -C "${AGENT_REPO_ROOT}" branch -D "${previous_branch}" >/dev/null 2>&1 || true
+fi
+
+"${PREPARE_SCRIPT}" "${WORKTREE}" >/dev/null
+
+printf 'WORKTREE=%s\n' "${WORKTREE}"
+printf 'BRANCH=%s\n' "${branch_name}"
+printf 'BASE_REF=%s\n' "${BASE_REF}"
+printf 'REUSED=yes\n'

package/tools/bin/run-codex-bypass.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+"$(dirname "$0")/run-codex-task.sh" bypass "$@"

package/tools/bin/run-codex-safe.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+"$(dirname "$0")/run-codex-task.sh" safe "$@"