agent-control-plane 0.1.0

package/tools/tests/test-project-launchd-bootstrap.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+FLOW_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+BOOTSTRAP_BIN="${FLOW_ROOT}/tools/bin/project-launchd-bootstrap.sh"
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT
+
+home_dir="$tmpdir/home"
+runtime_home="$tmpdir/runtime-home"
+profile_registry_root="$tmpdir/profiles"
+profile_dir="$profile_registry_root/demo"
+capture_dir="$tmpdir/capture"
+sync_script="$tmpdir/sync.sh"
+runtime_heartbeat_script="$runtime_home/skills/openclaw/agent-control-plane/tools/bin/heartbeat-safe-auto.sh"
+env_file="$profile_dir/runtime.env"
+
+mkdir -p "$home_dir" "$profile_dir" "$(dirname "$runtime_heartbeat_script")" "$capture_dir"
+
+cat >"$sync_script" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+printf 'SYNC_SOURCE=%s\n' "$1" >"${ACP_PROJECT_RUNTIME_CAPTURE_DIR}/sync.log"
+printf 'SYNC_TARGET=%s\n' "$2" >>"${ACP_PROJECT_RUNTIME_CAPTURE_DIR}/sync.log"
+EOF
+chmod +x "$sync_script"
+
+cat >"$runtime_heartbeat_script" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+printf 'PROFILE_ID=%s\n' "${ACP_PROJECT_ID:-}" >"${ACP_PROJECT_RUNTIME_CAPTURE_DIR}/heartbeat.log"
+printf 'PROFILE_REGISTRY_ROOT=%s\n' "${ACP_PROFILE_REGISTRY_ROOT:-}" >>"${ACP_PROJECT_RUNTIME_CAPTURE_DIR}/heartbeat.log"
+printf 'HOME=%s\n' "${HOME:-}" >>"${ACP_PROJECT_RUNTIME_CAPTURE_DIR}/heartbeat.log"
+printf 'PATH=%s\n' "${PATH:-}" >>"${ACP_PROJECT_RUNTIME_CAPTURE_DIR}/heartbeat.log"
+if [[ -n "${OPENROUTER_API_KEY:-}" ]]; then
+  printf 'HAS_OPENROUTER_API_KEY=yes\n' >>"${ACP_PROJECT_RUNTIME_CAPTURE_DIR}/heartbeat.log"
+else
+  printf 'HAS_OPENROUTER_API_KEY=no\n' >>"${ACP_PROJECT_RUNTIME_CAPTURE_DIR}/heartbeat.log"
+fi
+EOF
+chmod +x "$runtime_heartbeat_script"
+
+cat >"$env_file" <<'EOF'
+OPENROUTER_API_KEY=test-openrouter-key
+EOF
+
+ACP_PROJECT_RUNTIME_HOME_DIR="$home_dir" \
+ACP_PROJECT_RUNTIME_SOURCE_HOME="$tmpdir/source-home" \
+ACP_PROJECT_RUNTIME_RUNTIME_HOME="$runtime_home" \
+ACP_PROJECT_RUNTIME_PROFILE_REGISTRY_ROOT="$profile_registry_root" \
+ACP_PROJECT_RUNTIME_PROFILE_ID="demo" \
+ACP_PROJECT_RUNTIME_SYNC_SCRIPT="$sync_script" \
+ACP_PROJECT_RUNTIME_HEARTBEAT_SCRIPT="$runtime_heartbeat_script" \
+ACP_PROJECT_RUNTIME_ALWAYS_SYNC=1 \
+ACP_PROJECT_RUNTIME_CAPTURE_DIR="$capture_dir" \
+bash "$BOOTSTRAP_BIN"
+
+grep -q "^SYNC_SOURCE=$tmpdir/source-home$" "$capture_dir/sync.log"
+grep -q "^SYNC_TARGET=$runtime_home$" "$capture_dir/sync.log"
+grep -q '^PROFILE_ID=demo$' "$capture_dir/heartbeat.log"
+grep -q "^PROFILE_REGISTRY_ROOT=$profile_registry_root$" "$capture_dir/heartbeat.log"
+grep -q "^HOME=$home_dir$" "$capture_dir/heartbeat.log"
+grep -q '^HAS_OPENROUTER_API_KEY=yes$' "$capture_dir/heartbeat.log"
+
+echo "project launchd bootstrap test passed"

package/tools/tests/test-project-remove.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+FLOW_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+PROJECT_REMOVE_BIN="${FLOW_ROOT}/tools/bin/project-remove.sh"
+
+tmpdir="$(mktemp -d)"
+managed_root_one="/tmp/agent-control-plane-remove-demo/test-$$-one"
+managed_root_two="/tmp/agent-control-plane-purge-demo/test-$$-two"
+
+cleanup() {
+  rm -rf "${tmpdir}" "${managed_root_one}" "${managed_root_two}"
+}
+trap cleanup EXIT
+
+write_profile() {
+  local profile_root="${1:?profile root required}"
+  local profile_id="${2:?profile id required}"
+  local repo_root="${3:?repo root required}"
+  local agent_root="${4:?agent root required}"
+  local worktree_root="${5:?worktree root required}"
+  local retained_root="${6:?retained root required}"
+  local workspace_file="${7:?workspace file required}"
+  local runs_root="${agent_root}/runs"
+  local state_root="${agent_root}/state"
+  local history_root="${agent_root}/history"
+
+  mkdir -p "${profile_root}/${profile_id}" "${repo_root}" "${runs_root}" "${state_root}" "${history_root}" "${worktree_root}" "${retained_root}"
+  printf 'notes\n' >"${profile_root}/${profile_id}/README.md"
+  printf '{}\n' >"${workspace_file}"
+  cat >"${profile_root}/${profile_id}/control-plane.yaml" <<EOF
+schema_version: "1"
+id: "${profile_id}"
+repo:
+  slug: "example/${profile_id}"
+  root: "${repo_root}"
+  default_branch: "main"
+runtime:
+  orchestrator_agent_root: "${agent_root}"
+  worktree_root: "${worktree_root}"
+  agent_repo_root: "${repo_root}"
+  runs_root: "${runs_root}"
+  state_root: "${state_root}"
+  history_root: "${history_root}"
+  retained_repo_root: "${retained_root}"
+  vscode_workspace_file: "${workspace_file}"
+execution:
+  coding_worker: "openclaw"
+  openclaw:
+    model: "primary/model"
+    thinking: "adaptive"
+    timeout_seconds: 600
+EOF
+}
+
+runtimectl_log="${tmpdir}/runtimectl.log"
+runtimectl_stub="${tmpdir}/project-runtimectl.sh"
+launchd_uninstall_log="${tmpdir}/launchd-uninstall.log"
+launchd_uninstall_stub="${tmpdir}/uninstall-project-launchd.sh"
+cat >"${runtimectl_stub}" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+printf '%s\n' "\$*" >>"${runtimectl_log}"
+printf 'ACTION=stop\nRUNTIME_STATUS=stopped\n'
+EOF
+chmod +x "${runtimectl_stub}"
+
+cat >"${launchd_uninstall_stub}" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+printf '%s\n' "\$*" >>"${launchd_uninstall_log}"
+printf 'LAUNCHD_UNINSTALL_STATUS=ok\n'
+EOF
+chmod +x "${launchd_uninstall_stub}"
+
+profile_registry_one="${tmpdir}/profiles-one"
+repo_root_one="${tmpdir}/external-repo-one"
+worktree_root_one="${tmpdir}/external-worktrees-one"
+retained_root_one="${tmpdir}/external-retained-one"
+workspace_file_one="${tmpdir}/external-one.code-workspace"
+agent_root_one="${managed_root_one}/runtime/remove-demo"
+
+write_profile "${profile_registry_one}" "remove-demo" "${repo_root_one}" "${agent_root_one}" "${worktree_root_one}" "${retained_root_one}" "${workspace_file_one}"
+
+output_one="$(
+  ACP_PROFILE_REGISTRY_ROOT="${profile_registry_one}" \
+  ACP_PROJECT_REMOVE_RUNTIMECTL_SCRIPT="${runtimectl_stub}" \
+  ACP_PROJECT_REMOVE_LAUNCHD_UNINSTALL_SCRIPT="${launchd_uninstall_stub}" \
+    bash "${PROJECT_REMOVE_BIN}" --profile-id remove-demo
+)"
+
+grep -q 'PROJECT_REMOVE_STATUS=ok' <<<"${output_one}"
+grep -q 'PROFILE_ID=remove-demo' <<<"${output_one}"
+grep -q 'PURGE_PATHS=0' <<<"${output_one}"
+grep -q 'SKIP_STOP=0' <<<"${output_one}"
+grep -q 'stop --profile-id remove-demo' "${runtimectl_log}"
+grep -q -- '--profile-id remove-demo' "${launchd_uninstall_log}"
+[[ ! -e "${profile_registry_one}/remove-demo" ]]
+[[ ! -e "${agent_root_one}" ]]
+[[ -d "${repo_root_one}" ]]
+[[ -d "${worktree_root_one}" ]]
+[[ -d "${retained_root_one}" ]]
+[[ -f "${workspace_file_one}" ]]
+grep -q "SKIPPED_PATHS=.*${repo_root_one}" <<<"${output_one}"
+grep -q "SKIPPED_PATHS=.*${worktree_root_one}" <<<"${output_one}"
+grep -q "SKIPPED_PATHS=.*${retained_root_one}" <<<"${output_one}"
+
+profile_registry_two="${tmpdir}/profiles-two"
+repo_root_two="${tmpdir}/external-repo-two"
+worktree_root_two="${tmpdir}/external-worktrees-two"
+retained_root_two="${tmpdir}/external-retained-two"
+workspace_file_two="${tmpdir}/external-two.code-workspace"
+agent_root_two="${managed_root_two}/runtime/purge-demo"
+
+write_profile "${profile_registry_two}" "purge-demo" "${repo_root_two}" "${agent_root_two}" "${worktree_root_two}" "${retained_root_two}" "${workspace_file_two}"
+
+output_two="$(
+  ACP_PROFILE_REGISTRY_ROOT="${profile_registry_two}" \
+  ACP_PROJECT_REMOVE_RUNTIMECTL_SCRIPT="${runtimectl_stub}" \
+  ACP_PROJECT_REMOVE_LAUNCHD_UNINSTALL_SCRIPT="${launchd_uninstall_stub}" \
+    bash "${PROJECT_REMOVE_BIN}" --profile-id purge-demo --purge-paths --skip-stop
+)"
+
+grep -q 'PROJECT_REMOVE_STATUS=ok' <<<"${output_two}"
+grep -q 'PROFILE_ID=purge-demo' <<<"${output_two}"
+grep -q 'PURGE_PATHS=1' <<<"${output_two}"
+grep -q 'SKIP_STOP=1' <<<"${output_two}"
+[[ ! -e "${profile_registry_two}/purge-demo" ]]
+[[ ! -e "${agent_root_two}" ]]
+[[ ! -e "${repo_root_two}" ]]
+[[ ! -e "${worktree_root_two}" ]]
+[[ ! -e "${retained_root_two}" ]]
+[[ ! -e "${workspace_file_two}" ]]
+! grep -q 'purge-demo' "${runtimectl_log}"
+grep -q -- '--profile-id purge-demo' "${launchd_uninstall_log}"
+grep -q "REMOVED_PATHS=.*${repo_root_two}" <<<"${output_two}"
+grep -q "REMOVED_PATHS=.*${worktree_root_two}" <<<"${output_two}"
+grep -q "REMOVED_PATHS=.*${retained_root_two}" <<<"${output_two}"
+
+if ACP_PROFILE_REGISTRY_ROOT="${profile_registry_two}" \
+  ACP_PROJECT_REMOVE_RUNTIMECTL_SCRIPT="${runtimectl_stub}" \
+  ACP_PROJECT_REMOVE_LAUNCHD_UNINSTALL_SCRIPT="${launchd_uninstall_stub}" \
+  bash "${PROJECT_REMOVE_BIN}" --profile-id purge-demo >/dev/null 2>"${tmpdir}/missing-remove.err"; then
+  echo "expected missing profile remove to fail" >&2
+  exit 1
+fi
+
+grep -q 'profile not installed: purge-demo' "${tmpdir}/missing-remove.err"
+
+echo "project remove test passed"

package/tools/tests/test-project-runtime-supervisor.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+FLOW_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+SUPERVISOR_BIN="${FLOW_ROOT}/tools/bin/project-runtime-supervisor.sh"
+
+tmpdir="$(mktemp -d)"
+supervisor_pid=""
+cleanup() {
+  if [[ -n "${supervisor_pid}" ]]; then
+    kill "${supervisor_pid}" >/dev/null 2>&1 || true
+    wait "${supervisor_pid}" >/dev/null 2>&1 || true
+  fi
+  rm -rf "${tmpdir}"
+}
+trap cleanup EXIT
+
+pid_file="${tmpdir}/runtime-supervisor.pid"
+bootstrap_log="${tmpdir}/bootstrap.log"
+bootstrap_script="${tmpdir}/bootstrap.sh"
+
+cat >"${bootstrap_script}" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+printf 'bootstrap %s\n' "\$(date +%s)" >>"${bootstrap_log}"
+EOF
+chmod +x "${bootstrap_script}"
+
+bash "${SUPERVISOR_BIN}" \
+  --bootstrap-script "${bootstrap_script}" \
+  --pid-file "${pid_file}" \
+  --interval-seconds 1 >/dev/null 2>&1 &
+supervisor_pid="$!"
+
+for _ in 1 2 3 4 5; do
+  if [[ -f "${pid_file}" ]] && [[ -f "${bootstrap_log}" ]] && [[ "$(wc -l <"${bootstrap_log}" | tr -d ' ')" -ge 2 ]]; then
+    break
+  fi
+  sleep 1
+done
+
+test -f "${pid_file}"
+test "$(cat "${pid_file}")" = "${supervisor_pid}"
+test "$(wc -l <"${bootstrap_log}" | tr -d ' ')" -ge 2
+kill -0 "${supervisor_pid}" 2>/dev/null
+
+echo "project runtime supervisor test passed"

package/tools/tests/test-project-runtimectl-launchd.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+FLOW_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+RUNTIMECTL_BIN="${FLOW_ROOT}/tools/bin/project-runtimectl.sh"
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT
+
+profile_registry_root="${tmpdir}/profiles"
+profile_dir="${profile_registry_root}/demo"
+state_root="${tmpdir}/runtime/demo/state"
+launch_agents_dir="${tmpdir}/home/Library/LaunchAgents"
+fake_bin="${tmpdir}/bin"
+launchctl_log="${tmpdir}/launchctl.log"
+launchctl_state="${tmpdir}/launchctl-running"
+label="ai.agent.project.demo"
+plist_path="${launch_agents_dir}/${label}.plist"
+
+mkdir -p "${profile_dir}" "${state_root}" "${launch_agents_dir}" "${fake_bin}"
+
+cat >"${profile_dir}/control-plane.yaml" <<EOF
+schema_version: "1"
+id: "demo"
+repo:
+  slug: "example/demo"
+  root: "${tmpdir}/repo"
+  default_branch: "main"
+runtime:
+  orchestrator_agent_root: "${tmpdir}/runtime/demo"
+  worktree_root: "${tmpdir}/worktrees"
+  agent_repo_root: "${tmpdir}/repo"
+  runs_root: "${tmpdir}/runtime/demo/runs"
+  state_root: "${state_root}"
+  history_root: "${tmpdir}/runtime/demo/history"
+  retained_repo_root: "${tmpdir}/repo"
+  vscode_workspace_file: "${tmpdir}/demo.code-workspace"
+execution:
+  coding_worker: "openclaw"
+  openclaw:
+    model: "primary/model"
+    thinking: "adaptive"
+    timeout_seconds: 900
+EOF
+
+printf '<plist></plist>\n' >"${plist_path}"
+
+cat >"${fake_bin}/launchctl" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+printf '%s\n' "\$*" >>"${launchctl_log}"
+cmd="\${1:-}"
+case "\${cmd}" in
+  print)
+    if [[ -f "${launchctl_state}" ]]; then
+      exit 0
+    fi
+    exit 1
+    ;;
+  bootstrap|kickstart)
+    : >"${launchctl_state}"
+    exit 0
+    ;;
+  bootout)
+    rm -f "${launchctl_state}"
+    exit 0
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+EOF
+chmod +x "${fake_bin}/launchctl"
+
+: >"${launchctl_state}"
+
+status_output="$(
+  ACP_PROFILE_REGISTRY_ROOT="${profile_registry_root}" \
+  ACP_PROJECT_RUNTIME_LAUNCH_AGENTS_DIR="${launch_agents_dir}" \
+  ACP_PROJECT_RUNTIME_LAUNCHCTL_BIN="${fake_bin}/launchctl" \
+  bash "${RUNTIMECTL_BIN}" status --profile-id demo
+)"
+
+grep -q '^RUNTIME_STATUS=stopped$' <<<"${status_output}"
+grep -q '^LAUNCHD_STATE=running$' <<<"${status_output}"
+grep -q "^LAUNCHD_LABEL=${label}$" <<<"${status_output}"
+grep -q "^LAUNCHD_PLIST=${plist_path}$" <<<"${status_output}"
+
+start_output="$(
+  ACP_PROFILE_REGISTRY_ROOT="${profile_registry_root}" \
+  ACP_PROJECT_RUNTIME_LAUNCH_AGENTS_DIR="${launch_agents_dir}" \
+  ACP_PROJECT_RUNTIME_LAUNCHCTL_BIN="${fake_bin}/launchctl" \
+  bash "${RUNTIMECTL_BIN}" start --profile-id demo
+)"
+
+grep -q '^ACTION=start$' <<<"${start_output}"
+grep -q '^START_MODE=launchd$' <<<"${start_output}"
+grep -q '^LAUNCHD_STATE=running$' <<<"${start_output}"
+grep -q "bootout gui/.*/${label}" "${launchctl_log}"
+grep -q "bootstrap gui/.* ${plist_path}" "${launchctl_log}"
+grep -q "kickstart -k gui/.*/${label}" "${launchctl_log}"
+
+stop_output="$(
+  ACP_PROFILE_REGISTRY_ROOT="${profile_registry_root}" \
+  ACP_PROJECT_RUNTIME_LAUNCH_AGENTS_DIR="${launch_agents_dir}" \
+  ACP_PROJECT_RUNTIME_LAUNCHCTL_BIN="${fake_bin}/launchctl" \
+  bash "${RUNTIMECTL_BIN}" stop --profile-id demo
+)"
+
+grep -q '^ACTION=stop$' <<<"${stop_output}"
+grep -q '^LAUNCHD_STOPPED=yes$' <<<"${stop_output}"
+grep -q '^RUNTIME_STATUS=stopped$' <<<"${stop_output}"
+grep -q '^LAUNCHD_STATE=stopped$' <<<"${stop_output}"
+
+echo "project runtimectl launchd test passed"

package/tools/tests/test-project-runtimectl-missing-profile.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+FLOW_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+RUNTIMECTL_BIN="${FLOW_ROOT}/tools/bin/project-runtimectl.sh"
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "${tmpdir}"' EXIT
+
+profile_registry_root="${tmpdir}/profiles"
+mkdir -p "${profile_registry_root}"
+
+if ACP_PROFILE_REGISTRY_ROOT="${profile_registry_root}" \
+  ACP_ALLOW_IMPLICIT_PROFILE_SELECTION=1 \
+  bash "${RUNTIMECTL_BIN}" status --profile-id missing-demo >"${tmpdir}/stdout.log" 2>"${tmpdir}/stderr.log"; then
+  echo "expected missing profile status to fail" >&2
+  exit 1
+fi
+
+grep -q 'profile not installed: missing-demo' "${tmpdir}/stderr.log"
+[[ ! -s "${tmpdir}/stdout.log" ]]
+
+stop_output="$(
+  ACP_PROFILE_REGISTRY_ROOT="${profile_registry_root}" \
+  ACP_ALLOW_IMPLICIT_PROFILE_SELECTION=1 \
+    bash "${RUNTIMECTL_BIN}" stop --profile-id missing-demo
+)"
+
+grep -q 'ACTION=stop' <<<"${stop_output}"
+grep -q 'PROFILE_ID=missing-demo' <<<"${stop_output}"
+grep -q 'RUNTIME_STATUS=not-installed' <<<"${stop_output}"
+grep -q 'CONFIG_YAML=.*/missing-demo/control-plane.yaml' <<<"${stop_output}"
+
+if ACP_PROFILE_REGISTRY_ROOT="${profile_registry_root}" \
+  ACP_ALLOW_IMPLICIT_PROFILE_SELECTION=1 \
+  bash "${RUNTIMECTL_BIN}" start --profile-id missing-demo >"${tmpdir}/start.stdout.log" 2>"${tmpdir}/start.stderr.log"; then
+  echo "expected missing profile start to fail" >&2
+  exit 1
+fi
+
+grep -q 'profile not installed: missing-demo' "${tmpdir}/start.stderr.log"
+[[ ! -s "${tmpdir}/start.stdout.log" ]]
+
+if ACP_PROFILE_REGISTRY_ROOT="${profile_registry_root}" \
+  ACP_ALLOW_IMPLICIT_PROFILE_SELECTION=1 \
+  bash "${RUNTIMECTL_BIN}" restart --profile-id missing-demo >"${tmpdir}/restart.stdout.log" 2>"${tmpdir}/restart.stderr.log"; then
+  echo "expected missing profile restart to fail" >&2
+  exit 1
+fi
+
+grep -q 'profile not installed: missing-demo' "${tmpdir}/restart.stderr.log"
+[[ ! -s "${tmpdir}/restart.stdout.log" ]]
+
+echo "project runtimectl missing profile test passed"

package/tools/tests/test-project-runtimectl-start-falls-back-to-bootstrap.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+FLOW_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+RUNTIMECTL_BIN="${FLOW_ROOT}/tools/bin/project-runtimectl.sh"
+
+tmpdir="$(mktemp -d)"
+cleanup() {
+  rm -rf "${tmpdir}"
+}
+trap cleanup EXIT
+
+profile_registry_root="${tmpdir}/profiles"
+profile_dir="${profile_registry_root}/demo"
+runs_root="${tmpdir}/runtime/demo/runs"
+state_root="${tmpdir}/runtime/demo/state"
+fake_bin="${tmpdir}/bin"
+kick_log="${tmpdir}/kick.log"
+bootstrap_log="${tmpdir}/bootstrap.log"
+mkdir -p "${profile_dir}" "${fake_bin}" "${tmpdir}/repo" "${tmpdir}/worktrees" "${tmpdir}/runtime/demo"
+
+cat >"${profile_dir}/control-plane.yaml" <<EOF
+schema_version: "1"
+id: "demo"
+repo:
+  slug: "example/demo"
+  root: "${tmpdir}/repo"
+  default_branch: "main"
+runtime:
+  orchestrator_agent_root: "${tmpdir}/runtime/demo"
+  worktree_root: "${tmpdir}/worktrees"
+  agent_repo_root: "${tmpdir}/repo"
+  runs_root: "${runs_root}"
+  state_root: "${state_root}"
+  history_root: "${tmpdir}/runtime/demo/history"
+  retained_repo_root: "${tmpdir}/repo"
+  vscode_workspace_file: "${tmpdir}/demo.code-workspace"
+execution:
+  coding_worker: "openclaw"
+  openclaw:
+    model: "primary/model"
+    thinking: "adaptive"
+    timeout_seconds: 900
+EOF
+
+cat >"${fake_bin}/kick-scheduler.sh" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+printf 'kick profile=%s delay=%s\n' "\${ACP_PROJECT_ID:-}" "\${1:-}" >>"${kick_log}"
+printf 'KICK_STATUS=scheduled\nPID=99999\n'
+EOF
+chmod +x "${fake_bin}/kick-scheduler.sh"
+
+cat >"${fake_bin}/bootstrap.sh" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+printf 'bootstrap profile=%s\n' "\${ACP_PROJECT_ID:-}" >>"${bootstrap_log}"
+mkdir -p "${state_root}/heartbeat-loop.lock"
+sleep 60 >/dev/null 2>&1 &
+child_pid="\$!"
+printf '%s\n' "\$child_pid" >"${state_root}/heartbeat-loop.lock/pid"
+wait "\$child_pid"
+EOF
+chmod +x "${fake_bin}/bootstrap.sh"
+
+start_output="$(
+  ACP_PROFILE_REGISTRY_ROOT="${profile_registry_root}" \
+  ACP_PROJECT_RUNTIME_KICK_SCRIPT="${fake_bin}/kick-scheduler.sh" \
+  ACP_PROJECT_RUNTIME_BOOTSTRAP_SCRIPT="${fake_bin}/bootstrap.sh" \
+  ACP_PROJECT_RUNTIME_LAUNCHCTL_BIN="/nonexistent" \
+  ACP_PROJECT_RUNTIME_START_WAIT_SECONDS=1 \
+    bash "${RUNTIMECTL_BIN}" start --profile-id demo --delay-seconds 0
+)"
+
+grep -q 'ACTION=start' <<<"${start_output}"
+grep -q 'PROFILE_ID=demo' <<<"${start_output}"
+grep -q 'START_MODE=kick-scheduler-fallback-supervisor' <<<"${start_output}"
+grep -q 'KICK_STATUS=scheduled' <<<"${start_output}"
+grep -q 'FALLBACK_SUPERVISOR_PID=' <<<"${start_output}"
+grep -q 'kick profile=demo delay=0' "${kick_log}"
+
+for _ in 1 2 3 4 5; do
+  if [[ -f "${bootstrap_log}" ]] && grep -q 'bootstrap profile=demo' "${bootstrap_log}"; then
+    break
+  fi
+  sleep 1
+done
+
+grep -q 'bootstrap profile=demo' "${bootstrap_log}"
+
+status_output="$(
+  ACP_PROFILE_REGISTRY_ROOT="${profile_registry_root}" \
+  ACP_PROJECT_RUNTIME_KICK_SCRIPT="${fake_bin}/kick-scheduler.sh" \
+  ACP_PROJECT_RUNTIME_BOOTSTRAP_SCRIPT="${fake_bin}/bootstrap.sh" \
+  ACP_PROJECT_RUNTIME_LAUNCHCTL_BIN="/nonexistent" \
+    bash "${RUNTIMECTL_BIN}" status --profile-id demo
+)"
+
+grep -q 'RUNTIME_STATUS=running' <<<"${status_output}"
+grep -q 'SUPERVISOR_PID=' <<<"${status_output}"
+
+ACP_PROFILE_REGISTRY_ROOT="${profile_registry_root}" \
+ACP_PROJECT_RUNTIME_KICK_SCRIPT="${fake_bin}/kick-scheduler.sh" \
+ACP_PROJECT_RUNTIME_BOOTSTRAP_SCRIPT="${fake_bin}/bootstrap.sh" \
+ACP_PROJECT_RUNTIME_LAUNCHCTL_BIN="/nonexistent" \
+  bash "${RUNTIMECTL_BIN}" stop --profile-id demo --wait-seconds 1 >/dev/null
+
+echo "project runtimectl bootstrap fallback test passed"

package/tools/tests/test-project-runtimectl-status-reports-supervisor-as-heartbeat-parent.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+FLOW_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+RUNTIMECTL_BIN="${FLOW_ROOT}/tools/bin/project-runtimectl.sh"
+
+tmpdir="$(mktemp -d)"
+supervisor_pid=""
+heartbeat_pid=""
+cleanup() {
+  if [[ -n "${heartbeat_pid}" ]]; then
+    kill "${heartbeat_pid}" >/dev/null 2>&1 || true
+    wait "${heartbeat_pid}" >/dev/null 2>&1 || true
+  fi
+  if [[ -n "${supervisor_pid}" ]]; then
+    kill "${supervisor_pid}" >/dev/null 2>&1 || true
+    wait "${supervisor_pid}" >/dev/null 2>&1 || true
+  fi
+  rm -rf "${tmpdir}"
+}
+trap cleanup EXIT
+
+profile_registry_root="${tmpdir}/profiles"
+profile_dir="${profile_registry_root}/demo"
+runs_root="${tmpdir}/runtime/demo/runs"
+state_root="${tmpdir}/runtime/demo/state"
+heartbeat_lock_dir="${state_root}/heartbeat-loop.lock"
+mkdir -p "${profile_dir}" "${runs_root}" "${heartbeat_lock_dir}"
+
+cat >"${profile_dir}/control-plane.yaml" <<EOF
+schema_version: "1"
+id: "demo"
+repo:
+  slug: "example/demo"
+  root: "${tmpdir}/repo"
+  default_branch: "main"
+runtime:
+  orchestrator_agent_root: "${tmpdir}/runtime/demo"
+  worktree_root: "${tmpdir}/worktrees"
+  agent_repo_root: "${tmpdir}/repo"
+  runs_root: "${runs_root}"
+  state_root: "${state_root}"
+  history_root: "${tmpdir}/runtime/demo/history"
+  retained_repo_root: "${tmpdir}/repo"
+  vscode_workspace_file: "${tmpdir}/demo.code-workspace"
+execution:
+  coding_worker: "openclaw"
+  openclaw:
+    model: "primary/model"
+    thinking: "adaptive"
+    timeout_seconds: 900
+EOF
+
+supervisor_script="${tmpdir}/project-runtime-supervisor.sh"
+child_pid_file="${tmpdir}/heartbeat-child.pid"
+cat >"${supervisor_script}" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+sleep 60 >/dev/null 2>&1 &
+child_pid=\$!
+printf '%s\n' "\${child_pid}" >"${child_pid_file}"
+wait "\${child_pid}"
+EOF
+chmod +x "${supervisor_script}"
+
+bash "${supervisor_script}" >/dev/null 2>&1 &
+supervisor_pid="$!"
+
+for _ in $(seq 1 50); do
+  if [[ -s "${child_pid_file}" ]]; then
+    break
+  fi
+  sleep 0.1
+done
+
+heartbeat_pid="$(tr -d '[:space:]' <"${child_pid_file}")"
+if [[ -z "${heartbeat_pid}" ]]; then
+  echo "failed to capture heartbeat child pid" >&2
+  exit 1
+fi
+
+printf '%s\n' "${heartbeat_pid}" >"${heartbeat_lock_dir}/pid"
+printf '%s\n' "${supervisor_pid}" >"${state_root}/runtime-supervisor.pid"
+
+status_output="$(
+  ACP_PROFILE_REGISTRY_ROOT="${profile_registry_root}" \
+  ACP_PROJECT_RUNTIME_LAUNCHCTL_BIN="/nonexistent" \
+    bash "${RUNTIMECTL_BIN}" status --profile-id demo
+)"
+
+grep -q "HEARTBEAT_PID=${heartbeat_pid}" <<<"${status_output}"
+grep -q "HEARTBEAT_PARENT_PID=${supervisor_pid}" <<<"${status_output}"
+grep -q "SUPERVISOR_PID=${supervisor_pid}" <<<"${status_output}"
+
+echo "project runtimectl status reports supervisor as heartbeat parent test passed"