agent-control-plane 0.1.12 → 0.1.13

package/hooks/heartbeat-hooks.sh

@@ -15,6 +15,8 @@ FLOW_TOOLS_DIR="${FLOW_SKILL_DIR}/tools/bin"
 DETACHED_LAUNCH_BIN="${FLOW_TOOLS_DIR}/agent-project-detached-launch"
 RESIDENT_ISSUE_LOOP_BIN="${FLOW_TOOLS_DIR}/start-resident-issue-loop.sh"
 REPO_SLUG="$(flow_resolve_repo_slug "${CONFIG_YAML}")"
+AGENT_REPO_ROOT="$(flow_resolve_agent_repo_root "${CONFIG_YAML}")"
+DEFAULT_BRANCH="$(flow_resolve_default_branch "${CONFIG_YAML}")"
 STATE_ROOT="$(flow_resolve_state_root "${CONFIG_YAML}")"
 PENDING_LAUNCH_DIR="${ACP_PENDING_LAUNCH_DIR:-${F_LOSNING_PENDING_LAUNCH_DIR:-${STATE_ROOT}/pending-launches}}"
 AGENT_PR_PREFIXES_JSON="$(flow_managed_pr_prefixes_json "${CONFIG_YAML}")"
@@ -24,6 +26,51 @@ AGENT_EXCLUSIVE_LABEL="${AGENT_EXCLUSIVE_LABEL:-agent-exclusive}"
 CODING_WORKER="${ACP_CODING_WORKER:-${F_LOSNING_CODING_WORKER:-codex}}"
 HEARTBEAT_ISSUE_JSON_CACHE_DIR="${TMPDIR:-/tmp}/heartbeat-issue-json.$$"
 
+heartbeat_issue_retry_state_file() {
+  local issue_id="${1:?issue id required}"
+  printf '%s/retries/issues/%s.env\n' "${STATE_ROOT}" "${issue_id}"
+}
+
+heartbeat_reason_requires_baseline_change() {
+  local reason="${1:-}"
+  case "${reason}" in
+    verification-guard-blocked|no-publishable-commits|no-publishable-delta)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+heartbeat_current_baseline_head_sha() {
+  local head_sha=""
+  if [[ -d "${AGENT_REPO_ROOT}" ]]; then
+    head_sha="$(git -C "${AGENT_REPO_ROOT}" rev-parse --verify --quiet "origin/${DEFAULT_BRANCH}" 2>/dev/null || true)"
+    if [[ -z "${head_sha}" ]]; then
+      head_sha="$(git -C "${AGENT_REPO_ROOT}" rev-parse --verify --quiet "${DEFAULT_BRANCH}" 2>/dev/null || true)"
+    fi
+  fi
+  printf '%s\n' "${head_sha}"
+}
+
+heartbeat_retry_reason_is_baseline_blocked() {
+  local issue_id="${1:?issue id required}"
+  local reason="${2:-}"
+  local state_file baseline_head current_head
+
+  heartbeat_reason_requires_baseline_change "${reason}" || return 1
+  state_file="$(heartbeat_issue_retry_state_file "${issue_id}")"
+  [[ -f "${state_file}" ]] || return 1
+
+  baseline_head="$(awk -F= '/^BASELINE_HEAD_SHA=/{print substr($0, index($0, "=") + 1); exit}' "${state_file}" 2>/dev/null | tr -d '\r' || true)"
+  [[ -n "${baseline_head}" ]] || return 1
+  current_head="$(heartbeat_current_baseline_head_sha)"
+  [[ -n "${current_head}" ]] || return 1
+
+  [[ "${baseline_head}" == "${current_head}" ]]
+}
+
 heartbeat_issue_json_cached() {
   local issue_id="${1:?issue id required}"
   local cache_file=""
@@ -152,6 +199,9 @@ heartbeat_issue_blocked_recovery_reason() {
   retry_out="$("${FLOW_TOOLS_DIR}/retry-state.sh" issue "$issue_id" get 2>/dev/null || true)"
   retry_reason="$(awk -F= '/^LAST_REASON=/{print $2}' <<<"${retry_out:-}")"
   if [[ -n "${retry_reason:-}" && "${retry_reason}" != "issue-worker-blocked" ]]; then
+    if heartbeat_retry_reason_is_baseline_blocked "${issue_id}" "${retry_reason}"; then
+      return 0
+    fi
     printf '%s\n' "$retry_reason"
     return 0
   fi

package/hooks/issue-reconcile-hooks.sh

@@ -12,7 +12,9 @@ ADAPTER_BIN_DIR="${FLOW_SKILL_DIR}/bin"
 FLOW_TOOLS_DIR="${FLOW_SKILL_DIR}/tools/bin"
 REPO_SLUG="$(flow_resolve_repo_slug "${CONFIG_YAML}")"
 AGENT_ROOT="$(flow_resolve_agent_root "${CONFIG_YAML}")"
+AGENT_REPO_ROOT="$(flow_resolve_agent_repo_root "${CONFIG_YAML}")"
 STATE_ROOT="$(flow_resolve_state_root "${CONFIG_YAML}")"
+DEFAULT_BRANCH="$(flow_resolve_default_branch "${CONFIG_YAML}")"
 RUNS_ROOT="$(flow_resolve_runs_root "${CONFIG_YAML}")"
 BLOCKED_RECOVERY_STATE_DIR="${STATE_ROOT}/blocked-recovery-issues"
 
@@ -26,6 +28,49 @@ issue_clear_blocked_recovery_state() {
   rm -f "${BLOCKED_RECOVERY_STATE_DIR}/${ISSUE_ID}.env" 2>/dev/null || true
 }
 
+issue_retry_state_file() {
+  printf '%s/retries/issues/%s.env\n' "${STATE_ROOT}" "${ISSUE_ID}"
+}
+
+issue_reason_requires_baseline_change() {
+  local reason="${1:-}"
+  case "${reason}" in
+    verification-guard-blocked|no-publishable-commits|no-publishable-delta)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+issue_current_baseline_head_sha() {
+  local head_sha=""
+  if [[ -d "${AGENT_REPO_ROOT}" ]]; then
+    head_sha="$(git -C "${AGENT_REPO_ROOT}" rev-parse --verify --quiet "origin/${DEFAULT_BRANCH}" 2>/dev/null || true)"
+    if [[ -z "${head_sha}" ]]; then
+      head_sha="$(git -C "${AGENT_REPO_ROOT}" rev-parse --verify --quiet "${DEFAULT_BRANCH}" 2>/dev/null || true)"
+    fi
+  fi
+  printf '%s\n' "${head_sha}"
+}
+
+issue_record_retry_baseline_gate() {
+  local reason="${1:-}"
+  local state_file head_sha tmp_file
+
+  issue_reason_requires_baseline_change "${reason}" || return 0
+  state_file="$(issue_retry_state_file)"
+  [[ -f "${state_file}" ]] || return 0
+  head_sha="$(issue_current_baseline_head_sha)"
+  [[ -n "${head_sha}" ]] || return 0
+
+  tmp_file="$(mktemp)"
+  grep -v '^BASELINE_HEAD_SHA=' "${state_file}" >"${tmp_file}" || true
+  printf 'BASELINE_HEAD_SHA=%s\n' "${head_sha}" >>"${tmp_file}"
+  mv "${tmp_file}" "${state_file}"
+}
+
 issue_has_schedule_cadence() {
   local issue_json issue_body
   issue_json="$(flow_github_issue_view_json "${REPO_SLUG}" "${ISSUE_ID}" 2>/dev/null || true)"
@@ -155,6 +200,7 @@ issue_schedule_retry() {
     return 0
   fi
   "${FLOW_TOOLS_DIR}/retry-state.sh" issue "$ISSUE_ID" schedule "$reason" >/dev/null || true
+  issue_record_retry_baseline_gate "${reason}"
 }
 
 issue_mark_ready() {

package/npm/bin/agent-control-plane.js

@@ -156,7 +156,7 @@ function createExecutionContext(stage) {
 }
 
 function runScriptWithContext(context, scriptRelativePath, forwardedArgs, options = {}) {
-  const scriptPath = path.join(packageRoot, scriptRelativePath);
+  const scriptPath = options.scriptPath || path.join(packageRoot, scriptRelativePath);
   const stdio = options.stdio || "inherit";
   const result = spawnSync("bash", [scriptPath, ...forwardedArgs], {
     stdio,
@@ -175,11 +175,78 @@ function runScriptWithContext(context, scriptRelativePath, forwardedArgs, option
   };
 }
 
+function resolvePersistentSourceHome(context) {
+  if (process.env.ACP_PROJECT_RUNTIME_SOURCE_HOME) {
+    return process.env.ACP_PROJECT_RUNTIME_SOURCE_HOME;
+  }
+  if (fs.existsSync(path.join(packageRoot, ".git"))) {
+    return packageRoot;
+  }
+  return context.runtimeHome;
+}
+
+function runtimeSkillRoot(context) {
+  return path.join(context.runtimeHome, "skills", "openclaw", skillName);
+}
+
+function createRuntimeExecutionContext(context) {
+  const stableSkillRoot = runtimeSkillRoot(context);
+  const persistentSourceHome = resolvePersistentSourceHome(context);
+  const runtimeScriptEnv = {
+    ACP_PROJECT_RUNTIME_SYNC_SCRIPT:
+      context.env.ACP_PROJECT_RUNTIME_SYNC_SCRIPT || path.join(stableSkillRoot, "tools", "bin", "sync-shared-agent-home.sh"),
+    ACP_PROJECT_RUNTIME_ENSURE_SYNC_SCRIPT:
+      context.env.ACP_PROJECT_RUNTIME_ENSURE_SYNC_SCRIPT || path.join(stableSkillRoot, "tools", "bin", "ensure-runtime-sync.sh"),
+    ACP_PROJECT_RUNTIME_BOOTSTRAP_SCRIPT:
+      context.env.ACP_PROJECT_RUNTIME_BOOTSTRAP_SCRIPT || path.join(stableSkillRoot, "tools", "bin", "project-launchd-bootstrap.sh"),
+    ACP_PROJECT_RUNTIME_SUPERVISOR_SCRIPT:
+      context.env.ACP_PROJECT_RUNTIME_SUPERVISOR_SCRIPT || path.join(stableSkillRoot, "tools", "bin", "project-runtime-supervisor.sh"),
+    ACP_PROJECT_RUNTIME_KICK_SCRIPT:
+      context.env.ACP_PROJECT_RUNTIME_KICK_SCRIPT || path.join(stableSkillRoot, "tools", "bin", "kick-scheduler.sh")
+  };
+  return {
+    ...context,
+    stableSkillRoot,
+    persistentSourceHome,
+    env: {
+      ...context.env,
+      SHARED_AGENT_HOME: context.runtimeHome,
+      AGENT_CONTROL_PLANE_ROOT: stableSkillRoot,
+      ACP_ROOT: stableSkillRoot,
+      AGENT_FLOW_SOURCE_ROOT: stableSkillRoot,
+      ACP_PROJECT_INIT_SOURCE_HOME: persistentSourceHome,
+      ACP_PROJECT_RUNTIME_SOURCE_HOME: persistentSourceHome,
+      ACP_DASHBOARD_SOURCE_HOME: persistentSourceHome,
+      ...runtimeScriptEnv
+    }
+  };
+}
+
+function syncRuntimeHome(context, options = {}) {
+  const result = runScriptWithContext(context, "tools/bin/sync-shared-agent-home.sh", [], {
+    stdio: options.stdio || "inherit"
+  });
+  if (result.status !== 0) {
+    throw new Error("failed to sync runtime home before command execution");
+  }
+}
+
 function runCommand(scriptRelativePath, forwardedArgs) {
   const stage = stageSharedHome();
   const context = createExecutionContext(stage);
 
   try {
+    if (scriptRelativePath !== "tools/bin/sync-shared-agent-home.sh") {
+      syncRuntimeHome(context, { stdio: "inherit" });
+      const runtimeContext = createRuntimeExecutionContext(context);
+      const runtimeScriptPath = path.join(runtimeContext.stableSkillRoot, scriptRelativePath);
+      const result = runScriptWithContext(runtimeContext, scriptRelativePath, forwardedArgs, {
+        stdio: "inherit",
+        scriptPath: runtimeScriptPath
+      });
+      return result.status;
+    }
+
     const result = runScriptWithContext(context, scriptRelativePath, forwardedArgs, { stdio: "inherit" });
     return result.status;
   } finally {
@@ -1470,8 +1537,8 @@ async function maybeRunFinalSetupFixups(options, scopedContext, config, currentS
       runtimeStartReason = `doctor-${doctorKv.DOCTOR_STATUS || "not-ok"}`;
     } else {
       actions.push("runtime-start");
-      runSetupStep(scopedContext, "Start the runtime", "tools/bin/project-runtimectl.sh", ["start", "--profile-id", config.profileId]);
-      const runtimeStatusOutput = runSetupStep(scopedContext, "Read back runtime status", "tools/bin/project-runtimectl.sh", ["status", "--profile-id", config.profileId]);
+      runSetupStep(scopedContext, "Start the runtime", "tools/bin/project-runtimectl.sh", ["start", "--profile-id", config.profileId], { useRuntimeCopy: true });
+      const runtimeStatusOutput = runSetupStep(scopedContext, "Read back runtime status", "tools/bin/project-runtimectl.sh", ["status", "--profile-id", config.profileId], { useRuntimeCopy: true });
       runtimeStatusKv = parseKvOutput(runtimeStatusOutput);
       runtimeStartStatus = "ok";
       runtimeStartReason = "";
@@ -1480,7 +1547,7 @@ async function maybeRunFinalSetupFixups(options, scopedContext, config, currentS
 
   if (config.installLaunchd && process.platform === "darwin" && launchdInstallStatus !== "ok" && runtimeStartStatus === "ok") {
     actions.push("launchd-install");
-    runSetupStep(scopedContext, "Install macOS autostart", "tools/bin/install-project-launchd.sh", ["--profile-id", config.profileId]);
+    runSetupStep(scopedContext, "Install macOS autostart", "tools/bin/install-project-launchd.sh", ["--profile-id", config.profileId], { useRuntimeCopy: true });
     launchdInstallStatus = "ok";
     launchdInstallReason = "";
   }
@@ -1603,7 +1670,21 @@ async function collectSetupConfig(options, context) {
 
 function runSetupStep(context, title, scriptRelativePath, args, options = {}) {
   console.log(`\n== ${title} ==`);
-  const result = runScriptWithContext(context, scriptRelativePath, args, { stdio: "pipe", env: options.env, cwd: options.cwd });
+  let executionContext = context;
+  let scriptPath = undefined;
+
+  if (options.useRuntimeCopy) {
+    syncRuntimeHome(context, { stdio: "pipe" });
+    executionContext = createRuntimeExecutionContext(context);
+    scriptPath = path.join(executionContext.stableSkillRoot, scriptRelativePath);
+  }
+
+  const result = runScriptWithContext(executionContext, scriptRelativePath, args, {
+    stdio: "pipe",
+    env: options.env,
+    cwd: options.cwd,
+    scriptPath
+  });
   if (result.status !== 0) {
     printFailureDetails(result);
     throw new Error(`${title} failed`);
@@ -1868,8 +1949,8 @@ async function runSetupFlow(forwardedArgs) {
         runtimeStartReason = "gh-auth-not-ready";
         console.log("runtime start skipped: GitHub CLI is not authenticated yet. Run `gh auth login` and start the runtime afterwards.");
       } else {
-        runSetupStep(scopedContext, "Start the runtime", "tools/bin/project-runtimectl.sh", ["start", "--profile-id", config.profileId]);
-        const runtimeStatusOutput = runSetupStep(scopedContext, "Read back runtime status", "tools/bin/project-runtimectl.sh", ["status", "--profile-id", config.profileId]);
+        runSetupStep(scopedContext, "Start the runtime", "tools/bin/project-runtimectl.sh", ["start", "--profile-id", config.profileId], { useRuntimeCopy: true });
+        const runtimeStatusOutput = runSetupStep(scopedContext, "Read back runtime status", "tools/bin/project-runtimectl.sh", ["status", "--profile-id", config.profileId], { useRuntimeCopy: true });
         runtimeStatusKv = parseKvOutput(runtimeStatusOutput);
         runtimeStartStatus = "ok";
         runtimeStartReason = "";
@@ -1886,7 +1967,7 @@ async function runSetupFlow(forwardedArgs) {
         launchdInstallReason = "runtime-not-started";
         console.log("launchd install skipped: runtime was not started successfully in this setup run.");
       } else {
-        runSetupStep(scopedContext, "Install macOS autostart", "tools/bin/install-project-launchd.sh", ["--profile-id", config.profileId]);
+        runSetupStep(scopedContext, "Install macOS autostart", "tools/bin/install-project-launchd.sh", ["--profile-id", config.profileId], { useRuntimeCopy: true });
         launchdInstallStatus = "ok";
         launchdInstallReason = "";
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Help a repo keep GitHub-driven coding agents running reliably without constant human babysitting",
   "homepage": "https://github.com/ducminhnguyen0319/agent-control-plane",
   "bugs": {

package/tools/bin/agent-project-run-codex-session

@@ -167,6 +167,8 @@ printf -v codex_bin_q '%q' "$codex_bin"
 printf -v runner_bin_q '%q' "$runner_bin"
 printf -v safe_profile_q '%q' "$safe_profile"
 printf -v bypass_profile_q '%q' "$bypass_profile"
+helper_bin_dir="${artifact_dir}/worker-bin"
+printf -v helper_bin_dir_q '%q' "$helper_bin_dir"
 
 {
   printf 'TASK_KIND=%s\n' "$task_kind_q"
@@ -274,6 +276,61 @@ cat >"$inner_script" <<EOF
 set -euo pipefail
 ${runtime_exports}
 ${context_exports}cd ${worktree_realpath_q}
+bootstrap_codex_helper_env() {
+  local helper_bin_dir=${helper_bin_dir_q}
+  local openspec_shim=""
+
+  mkdir -p "\${helper_bin_dir}"
+
+  if [[ -d ${worktree_realpath_q}/node_modules/.bin ]]; then
+    export PATH="${worktree_realpath_q}/node_modules/.bin:\${PATH}"
+  fi
+  export PATH="\${helper_bin_dir}:\${PATH}"
+
+  if command -v openspec >/dev/null 2>&1; then
+    return 0
+  fi
+
+  if [[ ! -d ${worktree_realpath_q}/openspec ]]; then
+    return 0
+  fi
+
+  openspec_shim="\${helper_bin_dir}/openspec"
+  cat >"\${openspec_shim}" <<'SHIM'
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="\${ACP_REPO_ROOT:-\${F_LOSNING_REPO_ROOT:-\$(pwd)}}"
+openspec_root="\${repo_root}/openspec"
+
+if [[ ! -d "\${openspec_root}" ]]; then
+  echo "openspec directory not found: \${openspec_root}" >&2
+  exit 1
+fi
+
+command_name="\${1:-}"
+case "\${command_name}" in
+  list)
+    shift || true
+    if [[ "\${1:-}" == "--specs" ]]; then
+      find "\${openspec_root}/specs" -mindepth 1 -maxdepth 1 -type d 2>/dev/null \
+        | xargs -n1 basename 2>/dev/null \
+        | sort
+      exit 0
+    fi
+    find "\${openspec_root}/changes" -mindepth 1 -maxdepth 1 -type d ! -name archive 2>/dev/null \
+      | xargs -n1 basename 2>/dev/null \
+      | sort
+    exit 0
+    ;;
+  *)
+    echo "openspec shim only supports 'list' and 'list --specs'; use direct file reads for other operations" >&2
+    exit 64
+    ;;
+esac
+SHIM
+  chmod +x "\${openspec_shim}"
+}
 reset_sandbox_run_dir() {
   mkdir -p ${sandbox_run_dir_q}
   find ${sandbox_run_dir_q} -mindepth 1 -maxdepth 1 -exec rm -rf {} + 2>/dev/null || true
@@ -331,6 +388,7 @@ record_final_git_state() {
   } >>"\${tmp_file}"
   mv "\${tmp_file}" ${meta_file_q}
 }
+bootstrap_codex_helper_env
 reset_sandbox_run_dir
 set +e
 bash ${runner_bin_q} \\

package/tools/bin/branch-verification-guard.sh

@@ -108,6 +108,7 @@ const dependencyInputsChanged = files.some(isDependencyManifest);
 const apiTouched = productNonTestFiles.some((file) => /^apps\/api\//.test(file));
 const webTouched = productNonTestFiles.some((file) => /^apps\/web\//.test(file));
 const mobileTouched = productNonTestFiles.some((file) => /^apps\/mobile\//.test(file));
+const apiProductFiles = productNonTestFiles.filter((file) => /^apps\/api\//.test(file));
 const packageNames = [
   ...new Set(
     productNonTestFiles
@@ -199,11 +200,23 @@ const changedTestCoverage = changedTestFiles.map((file) => {
   return { file, anchors, covered };
 });
 const missingChangedTestFiles = changedTestCoverage.filter(({ covered }) => !covered);
+const apiChangedTests = changedTestCoverage.filter(({ file }) => /^apps\/api\//.test(file));
 
 const rootTypecheck = hasCommand(/\bpnpm (?:run )?typecheck\b/, /\bturbo\b.*\btypecheck\b/);
 const rootBuild = hasCommand(/\bpnpm (?:run )?build\b/, /\bturbo\b.*\bbuild\b/);
 const rootLint = hasCommand(/\bpnpm (?:run )?lint\b/, /\bturbo\b.*\blint\b/);
 const rootTest = hasCommand(/\bpnpm (?:run )?test\b/, /\bturbo\b.*\btest\b/);
+const scopedApiTypecheck =
+  hasScopedCommand(apiScopePattern, /\btypecheck\b/, /\btsc --noemit\b/, /\btsc --noemit\b/);
+const scopedApiConfidence =
+  hasScopedCommand(apiScopePattern, /\blint\b/, /\bbuild\b/, /\btest\b/, /\bjest\b/, /\bvitest\b/);
+const apiNarrowSliceTargetedCoverage =
+  apiProductFiles.length > 0 &&
+  apiProductFiles.length <= 2 &&
+  apiProductFiles.every((file) => /(?:^|\/)(?:services?|utils?|helpers?|policies?)\/|(?:\.service|\.util|\.helper|\.policy)\.[cm]?[jt]s$/.test(file)) &&
+  apiChangedTests.length > 0 &&
+  apiChangedTests.every(({ covered }) => covered) &&
+  scopedApiConfidence;
 
 const reasons = [];
 if (passedCommands.length === 0) {
@@ -242,10 +255,10 @@ if (localeTouched) {
 }
 
 if (apiTouched) {
-  if (!(hasScopedCommand(apiScopePattern, /\btypecheck\b/, /\btsc --noemit\b/, /\btsc --noemit\b/) || rootTypecheck)) {
+  if (!(scopedApiTypecheck || rootTypecheck || apiNarrowSliceTargetedCoverage)) {
     reasons.push('missing API typecheck or repo typecheck for API changes');
   }
-  if (!(hasScopedCommand(apiScopePattern, /\blint\b/, /\bbuild\b/, /\btest\b/, /\bjest\b/, /\bvitest\b/) || rootBuild || rootLint || rootTest)) {
+  if (!(scopedApiConfidence || rootBuild || rootLint || rootTest)) {
     reasons.push('missing API confidence verification (lint, build, or test) for API changes');
   }
 }

package/tools/bin/ensure-runtime-sync.sh

@@ -84,6 +84,11 @@ resolve_source_skill_dir() {
   local skill_name=""
   local root="${1:?source home required}"
 
+  if flow_is_skill_root "${root}"; then
+    printf '%s\n' "${root}"
+    return 0
+  fi
+
   for skill_name in "$(flow_canonical_skill_name)" "$(flow_compat_skill_alias)"; do
     [[ -n "${skill_name}" ]] || continue
     candidate="${root}/skills/openclaw/${skill_name}"
@@ -93,11 +98,6 @@ resolve_source_skill_dir() {
     fi
   done
 
-  if flow_is_skill_root "${root}"; then
-    printf '%s\n' "${root}"
-    return 0
-  fi
-
   return 1
 }
 

package/tools/bin/start-issue-worker.sh

@@ -727,38 +727,48 @@ for (const line of body.split(/\r?\n/).slice(0, 40)) {
   }
 }
 
-if (commands.length === 0 && repoRoot) {
-  const packageJsonPath = path.join(repoRoot, 'package.json');
-  if (fs.existsSync(packageJsonPath)) {
-    try {
-      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
-      if (packageJson?.scripts?.test) {
-        if (fs.existsSync(path.join(repoRoot, 'pnpm-lock.yaml'))) {
-          addCommand('pnpm test');
-        } else if (fs.existsSync(path.join(repoRoot, 'yarn.lock'))) {
-          addCommand('yarn test');
-        } else {
-          addCommand('npm test');
+  if (commands.length === 0 && repoRoot) {
+    const packageJsonPath = path.join(repoRoot, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+      try {
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+        if (packageJson?.scripts?.smoke) {
+          addCommand('# If this cycle changes smoke runners, CLI entrypoints, or operator commands, also run the matching smoke command from the repo instructions.');
         }
+      } catch (_error) {
+        // Ignore parse errors and fall through to generic guidance.
       }
-    } catch (_error) {
-      // Ignore parse errors and fall through to generic guidance.
     }
   }
-}
 
-if (commands.length === 0) {
-  addCommand('pnpm test');
-}
+  if (commands.length === 0) {
+    addCommand('# Pick the narrowest relevant local verification for the files you touch.');
+    addCommand('# Do not default to repo-wide pnpm test unless the issue body explicitly requires it.');
+    addCommand('# Examples:');
+    addCommand('# pnpm --filter @<repo>/api test -- --runInBand <target-spec>');
+    addCommand('# pnpm --filter @<repo>/api typecheck');
+    addCommand('# pnpm --filter @<repo>/web test -- --run <target-spec>');
+    addCommand('# pnpm --filter @<repo>/web typecheck');
+    addCommand('# pnpm --filter @<repo>/mobile test -- --runInBand <target-spec>');
+    addCommand('# pnpm --filter @<repo>/mobile typecheck');
+    addCommand('# pnpm --filter @<repo>/<package> test -- --run <target-spec>');
+    addCommand('# pnpm --filter @<repo>/<package> typecheck');
+    addCommand('# After each successful command, record it with record-verification.sh exactly as shown below.');
+  }
 
 const escapeDoubleQuotes = (value) => value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
 const snippet = commands
-  .map((command) =>
-    command + '\n' +
-    'bash "$ACP_FLOW_TOOLS_DIR/record-verification.sh" --run-dir "$ACP_RUN_DIR" --status pass --command "' +
-    escapeDoubleQuotes(command) +
-    '"',
-  )
+  .map((command) => {
+    if (command.startsWith('#')) {
+      return command;
+    }
+    return (
+      command + '\n' +
+      'bash "$ACP_FLOW_TOOLS_DIR/record-verification.sh" --run-dir "$ACP_RUN_DIR" --status pass --command "' +
+      escapeDoubleQuotes(command) +
+      '"'
+    );
+  })
   .join('\n\n');
 
 process.stdout.write(snippet);

package/tools/bin/sync-shared-agent-home.sh

@@ -32,12 +32,21 @@ if [[ ! -d "${FLOW_SKILL_SOURCE}" && -n "${COMPAT_FLOW_SKILL_ALIAS}" ]]; then
 fi
 
 FLOW_SKILL_SOURCE="$(cd "${FLOW_SKILL_SOURCE}" && pwd -P)"
+SOURCE_HOME="$(cd "${SOURCE_HOME}" && pwd -P)"
+
+remove_tree_force() {
+  local target="${1:-}"
+  [[ -n "${target}" ]] || return 0
+  [[ -e "${target}" || -L "${target}" ]] || return 0
+  chmod -R u+w "${target}" 2>/dev/null || true
+  rm -rf "${target}" 2>/dev/null || true
+}
 
 sync_tree_copy_mode() {
   local source_dir="${1:?source dir required}"
   local target_dir="${2:?target dir required}"
   [[ -d "${source_dir}" ]] || return 0
-  rm -rf "${target_dir}"
+  remove_tree_force "${target_dir}"
   mkdir -p "${target_dir}"
   (
     cd "${source_dir}"
@@ -57,13 +66,15 @@ sync_tree_into_target() {
 }
 
 sync_skill_copies() {
-  sync_tree_into_target "${FLOW_SKILL_SOURCE}" "${SOURCE_FLOW_CANONICAL_ALIAS}"
-  sync_tree_into_target "${FLOW_SKILL_SOURCE}" "${FLOW_SKILL_TARGET}"
-
-  if [[ -n "${SOURCE_FLOW_COMPAT_ALIAS}" ]]; then
-    sync_tree_into_target "${FLOW_SKILL_SOURCE}" "${SOURCE_FLOW_COMPAT_ALIAS}"
+  if ! flow_is_skill_root "${SOURCE_HOME}"; then
+    sync_tree_into_target "${FLOW_SKILL_SOURCE}" "${SOURCE_FLOW_CANONICAL_ALIAS}"
+    if [[ -n "${SOURCE_FLOW_COMPAT_ALIAS}" ]]; then
+      sync_tree_into_target "${FLOW_SKILL_SOURCE}" "${SOURCE_FLOW_COMPAT_ALIAS}"
+    fi
   fi
 
+  sync_tree_into_target "${FLOW_SKILL_SOURCE}" "${FLOW_SKILL_TARGET}"
+
   if [[ -n "${TARGET_FLOW_COMPAT_ALIAS}" ]]; then
     sync_tree_into_target "${FLOW_SKILL_SOURCE}" "${TARGET_FLOW_COMPAT_ALIAS}"
   fi
@@ -200,18 +211,21 @@ sync_tree_rsync() {
 }
 
 reset_runtime_skill_targets() {
-  rm -rf "${FLOW_SKILL_TARGET}"
+  remove_tree_force "${FLOW_SKILL_TARGET}"
   if [[ -n "${TARGET_FLOW_COMPAT_ALIAS}" ]]; then
-    rm -rf "${TARGET_FLOW_COMPAT_ALIAS}"
+    remove_tree_force "${TARGET_FLOW_COMPAT_ALIAS}"
   fi
 }
 
 reset_source_skill_targets() {
+  if flow_is_skill_root "${SOURCE_HOME}"; then
+    return 0
+  fi
   if [[ "${FLOW_SKILL_SOURCE}" != "${SOURCE_FLOW_CANONICAL_ALIAS}" ]]; then
-    rm -rf "${SOURCE_FLOW_CANONICAL_ALIAS}"
+    remove_tree_force "${SOURCE_FLOW_CANONICAL_ALIAS}"
   fi
   if [[ -n "${SOURCE_FLOW_COMPAT_ALIAS}" && "${FLOW_SKILL_SOURCE}" != "${SOURCE_FLOW_COMPAT_ALIAS}" ]]; then
-    rm -rf "${SOURCE_FLOW_COMPAT_ALIAS}"
+    remove_tree_force "${SOURCE_FLOW_COMPAT_ALIAS}"
   fi
 }
 

package/tools/templates/issue-prompt-template.md

@@ -22,7 +22,10 @@ Follow this order:
    bash "$ACP_FLOW_TOOLS_DIR/create-follow-up-issue.sh" --parent {ISSUE_ID} --title "..." --body-file /tmp/follow-up.md
    ```
 3. Implement the smallest root-cause fix in this worktree only.
-4. Run verification and record every successful command with `record-verification.sh`.
+4. Run the narrowest relevant local verification for the files you changed, and record every successful command with `record-verification.sh`.
+
+- Do not default to repo-wide verification such as `pnpm test` unless the issue body explicitly requires it.
+- If unrelated repo-wide suites are already red, keep the cycle focused on targeted verification for your slice and let the host verification guard decide whether publication is safe.
 
 ```bash
 {ISSUE_VERIFICATION_COMMAND_SNIPPET}