agent-control-plane 0.1.9 → 0.1.13

package/tools/bin/issue-publish-localization-guard.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  issue-publish-localization-guard.sh --worktree <path> --base-ref <git-ref>
+
+Fail fast when an issue branch updates locale resources but still leaves obvious
+hardcoded user-facing strings in the touched UI files.
+EOF
+}
+
+worktree=""
+base_ref=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --worktree) worktree="${2:-}"; shift 2 ;;
+    --base-ref) base_ref="${2:-}"; shift 2 ;;
+    --help|-h) usage; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+if [[ -z "$worktree" || -z "$base_ref" ]]; then
+  usage >&2
+  exit 1
+fi
+
+if [[ ! -d "$worktree" ]]; then
+  echo "missing worktree: $worktree" >&2
+  exit 1
+fi
+
+changed_files="$(
+  git -C "$worktree" diff --name-only --diff-filter=ACMR "${base_ref}...HEAD"
+)"
+
+CHANGED_FILES="${changed_files}" WORKTREE="${worktree}" node <<'EOF'
+const fs = require('fs');
+const path = require('path');
+
+const changedFiles = String(process.env.CHANGED_FILES || '')
+  .split('\n')
+  .map((file) => file.trim())
+  .filter(Boolean);
+const worktree = String(process.env.WORKTREE || '');
+
+const localeFiles = changedFiles.filter((file) =>
+  /^packages\/i18n\/src\/resources\/[^/]+\.json$/.test(file),
+);
+if (localeFiles.length === 0) {
+  process.stdout.write('LOCALIZATION_GUARD_STATUS=skipped-no-locale-files\n');
+  process.exit(0);
+}
+
+const uiFiles = changedFiles.filter((file) =>
+  /^(?:apps\/web\/|apps\/mobile\/|packages\/ui\/).+\.[cm]?[jt]sx?$/.test(file),
+);
+if (uiFiles.length === 0) {
+  process.stdout.write('LOCALIZATION_GUARD_STATUS=skipped-no-ui-files\n');
+  process.exit(0);
+}
+
+const suspiciousPatterns = [
+  {
+    reason: 'validation_literal',
+    test: (line) =>
+      /\.(?:min|max|length|email|regex|nonempty)\([^)]*,\s*['"`][^'"`]*[A-Za-z][^'"`]*['"`]/.test(line),
+  },
+  {
+    reason: 'string_prop',
+    test: (line) =>
+      /\b(?:title|description|actionLabel|aria-label|placeholder)\s*=\s*['"][^'{"][^'"]*[A-Za-z][^'"]*['"]/.test(
+        line,
+      ),
+  },
+  {
+    reason: 'object_label_literal',
+    test: (line) =>
+      /\blabel\s*:\s*['"][A-Za-z][^'"]*['"]/.test(line),
+  },
+];
+
+const ignoreLine = (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return true;
+  if (/^\s*\/\//.test(trimmed)) return true;
+  if (/\bt\(/.test(trimmed)) return true;
+  if (/\buseSafeTranslation\b|\buseTranslation\b|\bi18nKey=/.test(trimmed)) return true;
+  if (/^import\s/.test(trimmed)) return true;
+  return false;
+};
+
+const findings = [];
+for (const relativeFile of uiFiles) {
+  const absoluteFile = path.join(worktree, relativeFile);
+  if (!fs.existsSync(absoluteFile)) continue;
+  const lines = fs.readFileSync(absoluteFile, 'utf8').split(/\r?\n/);
+  lines.forEach((line, index) => {
+    if (ignoreLine(line)) return;
+    for (const pattern of suspiciousPatterns) {
+      if (pattern.test(line)) {
+        findings.push({
+          file: relativeFile,
+          line: index + 1,
+          reason: pattern.reason,
+          text: line.trim(),
+        });
+        return;
+      }
+    }
+  });
+}
+
+if (findings.length === 0) {
+  process.stdout.write('LOCALIZATION_GUARD_STATUS=ok\n');
+  process.stdout.write(`LOCALE_RESOURCE_COUNT=${localeFiles.length}\n`);
+  process.stdout.write(`UI_FILE_COUNT=${uiFiles.length}\n`);
+  process.exit(0);
+}
+
+const lines = [
+  'Localization guard blocked branch publication.',
+  '',
+  'The branch updates locale resources but still leaves obvious hardcoded user-facing strings in touched UI files.',
+  '',
+  'Why it was blocked:',
+];
+for (const finding of findings.slice(0, 20)) {
+  lines.push(`- ${finding.reason}: ${finding.file}:${finding.line} -> ${finding.text}`);
+}
+lines.push(
+  '',
+  'Required next step:',
+  '- move the remaining user-facing literals behind translation keys before publishing this issue branch',
+);
+
+process.stderr.write(`${lines.join('\n')}\n`);
+process.exit(44);
+EOF

package/tools/bin/project-launchd-bootstrap.sh

@@ -4,13 +4,14 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 FLOW_SKILL_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd)"
 HOME_DIR="${ACP_PROJECT_RUNTIME_HOME_DIR:-${HOME:-}}"
-SOURCE_HOME="${ACP_PROJECT_RUNTIME_SOURCE_HOME:-$(cd "${FLOW_SKILL_DIR}/../../.." && pwd)}"
+SOURCE_HOME="${ACP_PROJECT_RUNTIME_SOURCE_HOME:-}"
 RUNTIME_HOME="${ACP_PROJECT_RUNTIME_RUNTIME_HOME:-${HOME_DIR}/.agent-runtime/runtime-home}"
 PROFILE_REGISTRY_ROOT="${ACP_PROJECT_RUNTIME_PROFILE_REGISTRY_ROOT:-${ACP_PROFILE_REGISTRY_ROOT:-${HOME_DIR}/.agent-runtime/control-plane/profiles}}"
 PROFILE_ID="${ACP_PROJECT_RUNTIME_PROFILE_ID:-${ACP_PROJECT_ID:-${AGENT_PROJECT_ID:-}}}"
 ENV_FILE="${ACP_PROJECT_RUNTIME_ENV_FILE:-${PROFILE_REGISTRY_ROOT}/${PROFILE_ID}/runtime.env}"
 BASE_PATH="${ACP_PROJECT_RUNTIME_PATH:-/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin}"
 SYNC_SCRIPT="${ACP_PROJECT_RUNTIME_SYNC_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/sync-shared-agent-home.sh}"
+ENSURE_SYNC_SCRIPT="${ACP_PROJECT_RUNTIME_ENSURE_SYNC_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/ensure-runtime-sync.sh}"
 RUNTIME_HEARTBEAT_SCRIPT="${ACP_PROJECT_RUNTIME_HEARTBEAT_SCRIPT:-${RUNTIME_HOME}/skills/openclaw/agent-control-plane/tools/bin/heartbeat-safe-auto.sh}"
 ALWAYS_SYNC="${ACP_PROJECT_RUNTIME_ALWAYS_SYNC:-0}"
 
@@ -37,12 +38,24 @@ if [[ -f "${ENV_FILE}" ]]; then
   set +a
 fi
 
-if [[ ! -x "${SYNC_SCRIPT}" ]]; then
-  echo "project launchd bootstrap missing sync script: ${SYNC_SCRIPT}" >&2
+if [[ ! -x "${ENSURE_SYNC_SCRIPT}" && ! -x "${SYNC_SCRIPT}" ]]; then
+  echo "project launchd bootstrap missing sync helper: ${ENSURE_SYNC_SCRIPT}" >&2
   exit 65
 fi
 
-if [[ "${ALWAYS_SYNC}" == "1" || ! -x "${RUNTIME_HEARTBEAT_SCRIPT}" ]]; then
+if [[ -x "${ENSURE_SYNC_SCRIPT}" ]]; then
+  ensure_args=(--runtime-home "${RUNTIME_HOME}" --quiet)
+  if [[ -n "${SOURCE_HOME}" ]]; then
+    ensure_args=(--source-home "${SOURCE_HOME}" "${ensure_args[@]}")
+  fi
+  if [[ "${ALWAYS_SYNC}" == "1" ]]; then
+    ensure_args=(--force "${ensure_args[@]}")
+  fi
+  bash "${ENSURE_SYNC_SCRIPT}" "${ensure_args[@]}"
+elif [[ "${ALWAYS_SYNC}" == "1" || ! -x "${RUNTIME_HEARTBEAT_SCRIPT}" ]]; then
+  if [[ -z "${SOURCE_HOME}" ]]; then
+    SOURCE_HOME="${FLOW_SKILL_DIR}"
+  fi
   bash "${SYNC_SCRIPT}" "${SOURCE_HOME}" "${RUNTIME_HOME}" >/dev/null
 fi
 

package/tools/bin/project-runtime-supervisor.sh

@@ -47,10 +47,16 @@ trap '' HUP
 
 first_pass="1"
 while true; do
+  printf '[%s] supervisor bootstrap start pid=%s script=%s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "$$" "${bootstrap_script}" >&2
   if [[ "${first_pass}" == "1" && "${delay_seconds}" != "0" ]]; then
     sleep "${delay_seconds}"
   fi
   first_pass="0"
-  "${bootstrap_script}" >/dev/null 2>&1 || true
+  if "${bootstrap_script}"; then
+    printf '[%s] supervisor bootstrap end status=0 pid=%s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "$$" >&2
+  else
+    bootstrap_status=$?
+    printf '[%s] supervisor bootstrap end status=%s pid=%s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "${bootstrap_status}" "$$" >&2
+  fi
   sleep "${interval_seconds}"
 done

package/tools/bin/project-runtimectl.sh

@@ -8,7 +8,7 @@ source "${SCRIPT_DIR}/flow-config-lib.sh"
 usage() {
   cat <<'EOF'
 Usage:
-  project-runtimectl.sh <status|start|stop|restart> --profile-id <id> [options]
+  project-runtimectl.sh <status|start|stop|restart|sync> --profile-id <id> [options]
 
 Manage runtime processes for one installed profile.
 
@@ -16,6 +16,7 @@ Options:
   --profile-id <id>      Profile id to manage
   --delay-seconds <n>    Delay for start via kick-scheduler (default: 0)
   --wait-seconds <n>     Wait for stop to settle before SIGKILL (default: 10)
+  --force                Force a runtime sync refresh when using `sync`
   --help                 Show this help
 EOF
 }
@@ -30,19 +31,21 @@ shift || true
 profile_id_override=""
 delay_seconds="0"
 wait_seconds="10"
+force_sync="0"
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --profile-id) profile_id_override="${2:-}"; shift 2 ;;
     --delay-seconds) delay_seconds="${2:-}"; shift 2 ;;
     --wait-seconds) wait_seconds="${2:-}"; shift 2 ;;
+    --force) force_sync="1"; shift ;;
     --help|-h) usage; exit 0 ;;
     *) echo "Unknown argument: $1" >&2; usage >&2; exit 64 ;;
   esac
 done
 
 case "${subcommand}" in
-  status|start|stop|restart) ;;
+  status|start|stop|restart|sync) ;;
   *)
     echo "Unknown subcommand: ${subcommand}" >&2
     usage >&2
@@ -92,16 +95,21 @@ REPO_SLUG="$(flow_resolve_repo_slug "${CONFIG_YAML}")"
 RUNS_ROOT="$(flow_resolve_runs_root "${CONFIG_YAML}")"
 STATE_ROOT="$(flow_resolve_state_root "${CONFIG_YAML}")"
 SUPERVISOR_PID_FILE="${STATE_ROOT}/runtime-supervisor.pid"
+SUPERVISOR_LOG_FILE="${STATE_ROOT}/runtime-supervisor.log"
 PROFILE_ID_SLUG="$(printf '%s' "${PROFILE_ID}" | tr -c 'A-Za-z0-9._-' '-')"
 BOOTSTRAP_SCRIPT="${ACP_PROJECT_RUNTIME_BOOTSTRAP_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/project-launchd-bootstrap.sh}"
 KICK_SCRIPT="${ACP_PROJECT_RUNTIME_KICK_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/kick-scheduler.sh}"
 SUPERVISOR_SCRIPT="${ACP_PROJECT_RUNTIME_SUPERVISOR_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/project-runtime-supervisor.sh}"
+ENSURE_SYNC_SCRIPT="${ACP_PROJECT_RUNTIME_ENSURE_SYNC_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/ensure-runtime-sync.sh}"
 UPDATE_LABELS_SCRIPT="${ACP_PROJECT_RUNTIME_UPDATE_LABELS_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/agent-github-update-labels}"
 TMUX_BIN="${ACP_PROJECT_RUNTIME_TMUX_BIN:-$(command -v tmux || true)}"
 LAUNCHCTL_BIN="${ACP_PROJECT_RUNTIME_LAUNCHCTL_BIN:-$(command -v launchctl || true)}"
 LAUNCH_AGENTS_DIR="${ACP_PROJECT_RUNTIME_LAUNCH_AGENTS_DIR:-${HOME}/Library/LaunchAgents}"
 LAUNCHD_LABEL="${ACP_PROJECT_RUNTIME_LAUNCHD_LABEL:-ai.agent.project.${PROFILE_ID_SLUG}}"
 LAUNCHD_PLIST="${ACP_PROJECT_RUNTIME_LAUNCHD_PLIST:-${LAUNCH_AGENTS_DIR}/${LAUNCHD_LABEL}.plist}"
+SOURCE_HOME="${ACP_PROJECT_RUNTIME_SOURCE_HOME:-}"
+RUNTIME_HOME="${ACP_PROJECT_RUNTIME_RUNTIME_HOME:-$(resolve_runtime_home)}"
+SYNC_STAMP_FILE="${RUNTIME_HOME}/.agent-control-plane-runtime-sync.env"
 
 case "${delay_seconds}" in
   ''|*[!0-9]*) echo "--delay-seconds must be numeric" >&2; exit 64 ;;
@@ -160,17 +168,13 @@ join_by_comma() {
 runtime_started() {
   local heartbeat=""
   local shared_loop=""
-  local controller_pid=""
-  local active_session=""
   local supervisor=""
 
   heartbeat="$(heartbeat_pid)"
   shared_loop="$(shared_loop_pid)"
-  controller_pid="$(collect_controller_pids | head -n 1 || true)"
-  active_session="$(collect_active_tmux_sessions | head -n 1 || true)"
   supervisor="$(supervisor_pid)"
 
-  [[ -n "${heartbeat}" || -n "${shared_loop}" || -n "${controller_pid}" || -n "${active_session}" || -n "${supervisor}" ]]
+  [[ -n "${heartbeat}" || -n "${shared_loop}" || -n "${supervisor}" ]]
 }
 
 wait_for_runtime_start() {
@@ -186,6 +190,13 @@ wait_for_runtime_start() {
   return 1
 }
 
+sync_stamp_value() {
+  local key="${1:?key required}"
+  [[ -f "${SYNC_STAMP_FILE}" ]] || return 1
+  awk -F= -v target="${key}" '$1 == target {print $2; exit}' "${SYNC_STAMP_FILE}" 2>/dev/null \
+    | sed -e "s/^'//" -e "s/'$//"
+}
+
 tmux_session_exists() {
   local session="${1:-}"
   [[ -n "${TMUX_BIN}" && -n "${session}" ]] || return 1
@@ -331,6 +342,9 @@ print_status() {
   local active_session_count="0"
   local pending_count="0"
   local launchd_state=""
+  local runtime_sync_status=""
+  local runtime_sync_updated_at=""
+  local runtime_sync_fingerprint=""
 
   heartbeat="$(heartbeat_pid)"
   shared_loop="$(shared_loop_pid)"
@@ -352,6 +366,9 @@ print_status() {
   fi
 
   launchd_state="$(launchd_service_state)"
+  runtime_sync_status="$(sync_stamp_value "SYNC_STATUS" || true)"
+  runtime_sync_updated_at="$(sync_stamp_value "UPDATED_AT" || true)"
+  runtime_sync_fingerprint="$(sync_stamp_value "SOURCE_FINGERPRINT" || true)"
 
   printf 'PROFILE_ID=%s\n' "${PROFILE_ID}"
   printf 'CONFIG_YAML=%s\n' "${CONFIG_YAML}"
@@ -372,6 +389,10 @@ print_status() {
   printf 'CONTROLLER_PIDS=%s\n' "$(printf '%s\n' "${controller_pids}" | join_by_comma)"
   printf 'ACTIVE_TMUX_SESSIONS=%s\n' "$(printf '%s\n' "${active_sessions}" | join_by_comma)"
   printf 'PENDING_LAUNCH_PIDS=%s\n' "$(printf '%s\n' "${pending_pids}" | join_by_comma)"
+  printf 'SYNC_STAMP_FILE=%s\n' "${SYNC_STAMP_FILE}"
+  printf 'RUNTIME_SYNC_STATUS=%s\n' "${runtime_sync_status}"
+  printf 'RUNTIME_SYNC_UPDATED_AT=%s\n' "${runtime_sync_updated_at}"
+  printf 'RUNTIME_SYNC_FINGERPRINT=%s\n' "${runtime_sync_fingerprint}"
 }
 
 terminate_pid_list() {
@@ -499,6 +520,7 @@ stop_runtime() {
 start_runtime() {
   local kick_output=""
   local fallback_pid=""
+  local fallback_log_file="${SUPERVISOR_LOG_FILE}"
   local start_timeout="${ACP_PROJECT_RUNTIME_START_WAIT_SECONDS:-${wait_seconds}}"
   local runtime_started_after_kick="0"
   local supervisor_spawned="0"
@@ -537,14 +559,26 @@ start_runtime() {
 
   if [[ "${runtime_started_after_kick}" != "1" && -z "$(supervisor_pid)" ]]; then
     mkdir -p "${STATE_ROOT}"
-    nohup env ACP_PROJECT_ID="${PROFILE_ID}" AGENT_PROJECT_ID="${PROFILE_ID}" \
-      bash "${SUPERVISOR_SCRIPT}" \
-        --bootstrap-script "${BOOTSTRAP_SCRIPT}" \
-        --pid-file "${SUPERVISOR_PID_FILE}" \
-        --delay-seconds "${delay_seconds}" \
-        --interval-seconds "${ACP_PROJECT_RUNTIME_SUPERVISOR_INTERVAL_SECONDS:-15}" \
-        </dev/null >/dev/null 2>&1 &
-    fallback_pid="$!"
+    : >"${fallback_log_file}"
+    if command -v setsid >/dev/null 2>&1; then
+      setsid env ACP_PROJECT_ID="${PROFILE_ID}" AGENT_PROJECT_ID="${PROFILE_ID}" \
+        bash "${SUPERVISOR_SCRIPT}" \
+          --bootstrap-script "${BOOTSTRAP_SCRIPT}" \
+          --pid-file "${SUPERVISOR_PID_FILE}" \
+          --delay-seconds "${delay_seconds}" \
+          --interval-seconds "${ACP_PROJECT_RUNTIME_SUPERVISOR_INTERVAL_SECONDS:-15}" \
+          </dev/null >>"${fallback_log_file}" 2>&1 &
+      fallback_pid="$!"
+    else
+      nohup env ACP_PROJECT_ID="${PROFILE_ID}" AGENT_PROJECT_ID="${PROFILE_ID}" \
+        bash "${SUPERVISOR_SCRIPT}" \
+          --bootstrap-script "${BOOTSTRAP_SCRIPT}" \
+          --pid-file "${SUPERVISOR_PID_FILE}" \
+          --delay-seconds "${delay_seconds}" \
+          --interval-seconds "${ACP_PROJECT_RUNTIME_SUPERVISOR_INTERVAL_SECONDS:-15}" \
+          </dev/null >>"${fallback_log_file}" 2>&1 &
+      fallback_pid="$!"
+    fi
     supervisor_spawned="1"
     wait_for_runtime_start "${start_timeout}" || true
   fi
@@ -563,9 +597,35 @@ start_runtime() {
   printf '%s\n' "${kick_output}"
   if [[ -n "${fallback_pid}" ]]; then
     printf 'FALLBACK_SUPERVISOR_PID=%s\n' "${fallback_pid}"
+    printf 'FALLBACK_SUPERVISOR_LOG=%s\n' "${fallback_log_file}"
   fi
 }
 
+sync_runtime() {
+  local ensure_output=""
+  local ensure_args=()
+
+  if [[ ! -x "${ENSURE_SYNC_SCRIPT}" ]]; then
+    echo "missing runtime sync helper: ${ENSURE_SYNC_SCRIPT}" >&2
+    exit 65
+  fi
+
+  ensure_args=(--runtime-home "${RUNTIME_HOME}")
+  if [[ -n "${SOURCE_HOME}" ]]; then
+    ensure_args=(--source-home "${SOURCE_HOME}" "${ensure_args[@]}")
+  fi
+  if [[ "${force_sync}" == "1" ]]; then
+    ensure_args=(--force "${ensure_args[@]}")
+    ensure_output="$(bash "${ENSURE_SYNC_SCRIPT}" "${ensure_args[@]}")"
+  else
+    ensure_output="$(bash "${ENSURE_SYNC_SCRIPT}" "${ensure_args[@]}")"
+  fi
+
+  printf 'ACTION=sync\n'
+  printf 'PROFILE_ID=%s\n' "${PROFILE_ID}"
+  printf '%s\n' "${ensure_output}"
+}
+
 case "${subcommand}" in
   status)
     print_status
@@ -583,4 +643,7 @@ case "${subcommand}" in
     start_runtime
     print_status
     ;;
+  sync)
+    sync_runtime
+    ;;
 esac

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

@@ -31,6 +31,7 @@ fi
 
 CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
 AGENT_REPO_ROOT="$(flow_resolve_agent_repo_root "${CONFIG_YAML}")"
+WORKTREE_ROOT="$(flow_resolve_worktree_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}"
@@ -46,6 +47,9 @@ 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)"
+resolved_worktree=""
+actual_branch=""
+rotated_worktree=""
 
 if ! git -C "${WORKTREE}" rev-parse --git-dir >/dev/null 2>&1; then
   echo "invalid managed worktree: ${WORKTREE}" >&2
@@ -69,6 +73,48 @@ fi
 
 "${PREPARE_SCRIPT}" "${WORKTREE}" >/dev/null
 
+if ! git -C "${WORKTREE}" rev-parse --git-dir >/dev/null 2>&1; then
+  echo "invalid managed worktree after reuse: ${WORKTREE}" >&2
+  exit 1
+fi
+
+resolved_worktree="$(cd "${WORKTREE}" 2>/dev/null && pwd -P || true)"
+if [[ -z "${resolved_worktree}" || ! -d "${resolved_worktree}" ]]; then
+  echo "reused worktree path is unavailable: ${WORKTREE}" >&2
+  exit 1
+fi
+WORKTREE="${resolved_worktree}"
+
+if [[ -n "${WORKTREE_ROOT}" ]]; then
+  mkdir -p "${WORKTREE_ROOT}"
+  rotated_worktree="${WORKTREE_ROOT}/issue-${ISSUE_ID}-${stamp}"
+  if [[ "${resolved_worktree}" != "${rotated_worktree}" ]]; then
+    if [[ -e "${rotated_worktree}" ]]; then
+      echo "rotated worktree path already exists: ${rotated_worktree}" >&2
+      exit 1
+    fi
+    git -C "${AGENT_REPO_ROOT}" worktree move "${resolved_worktree}" "${rotated_worktree}" >/dev/null
+    WORKTREE="${rotated_worktree}"
+    resolved_worktree="$(cd "${WORKTREE}" 2>/dev/null && pwd -P || true)"
+    if [[ -z "${resolved_worktree}" || ! -d "${resolved_worktree}" ]]; then
+      echo "rotated worktree path is unavailable: ${WORKTREE}" >&2
+      exit 1
+    fi
+    WORKTREE="${resolved_worktree}"
+  fi
+fi
+
+if ! git -C "${AGENT_REPO_ROOT}" worktree list --porcelain | grep -Fqx "worktree ${resolved_worktree}"; then
+  echo "reused worktree is no longer registered: ${resolved_worktree}" >&2
+  exit 1
+fi
+
+actual_branch="$(git -C "${WORKTREE}" branch --show-current 2>/dev/null || true)"
+if [[ -z "${actual_branch}" || "${actual_branch}" != "${branch_name}" ]]; then
+  echo "reused worktree branch mismatch: expected ${branch_name} got ${actual_branch:-<none>}" >&2
+  exit 1
+fi
+
 printf 'WORKTREE=%s\n' "${WORKTREE}"
 printf 'BRANCH=%s\n' "${branch_name}"
 printf 'BASE_REF=%s\n' "${BASE_REF}"