autonomous-sdlc-harness 0.5.0 → 0.6.1

package/templates/scripts/docs-search-server.sh

@@ -1,7 +1,6 @@
 #!/usr/bin/env bash
 # docs-search-server.sh — start the docs-retrieval MCP server for the checkout
-# this script sits in, by `exec`ing the machine-shared retrieval runtime's
-# `docs serve`.
+# this script sits in, on the backend `docs.retrievalBackend` selects.
 #
 # WHO RUNS IT. The agent runner, from the `harness-docs` entry `init` writes into
 # `.mcp.json` when `docs.retrieval` is on — never a dispatched agent's Bash call,
@@ -9,29 +8,52 @@
 # `agentInvocable: false` and the generated permission profile carries no entry
 # for it.
 #
-# STDOUT BELONGS TO THE MCP TRANSPORT. Nothing here may print to stdout before
-# the `exec`: a stray byte there is a malformed frame for the client. Every
-# diagnostic goes to stderr.
+# STDOUT BELONGS TO THE MCP TRANSPORT. Nothing here may print to stdout: a stray
+# byte there is a malformed frame for the client. Every diagnostic goes to
+# stderr.
 #
-# THE RUNTIME IS THE ONLY THING THIS RUNS, with no fallback to any other
-# installation: a committed `.mcp.json` cannot know where an adopter's own CLI
-# lives. `doctor`'s `retrieval-dependencies` check and `init`'s install both key
-# on the same entry file this script tests. `PATH` is settled through the
-# library's fallback list before the `exec`, because the starter is the agent
-# runner rather than a login shell.
+# WHICH SERVER. Two backends, chosen by `docs.retrievalBackend` read at run
+# time, with no fallback between them and no fallback to any other
+# installation. The key is read ONLY WHEN `phases.docs` and `docs.retrieval` are
+# both `true` (`hr_docs_retrieval_applies`, the shell mirror of
+# `retrievalApplies`): `init` merges `.mcp.json` and removes nothing, so this
+# entry outlives turning retrieval off, and with the gate closed the TypeScript
+# runtime is `exec`ed whatever the key holds. `typescript`, or the key absent,
+# `exec`s the machine-shared runtime's `docs serve`; `doctor`'s
+# `retrieval-dependencies` check and `init`'s install both key on the same entry
+# file this script tests. `python` starts the Python package's stdio server.
+# This script checks no database and runs no `self-check`: grading the backend's
+# prerequisites is `doctor`'s. `PATH` is settled through the library's fallback
+# list first, because the starter is the agent runner rather than a login shell.
+#
+# WHY THE PYTHON BRANCH IS NOT `exec`ED. Its failure must surface as exit 3,
+# which an `exec` could not report. It runs as a child with stdin passed
+# explicitly, and a `TERM` or an `INT` the launcher receives is passed on to it
+# as `TERM`, the signal the server stops on: bash starts a background child with
+# `SIGINT` ignored when job control is off, and Python installs no handler over
+# an ignored `SIGINT`, so an `INT` passed on as itself would never arrive.
 #
 # MIRRORS — a change to any owner below is an edit here too:
 #   `retrieval/runtime` and `node_modules/autonomous-sdlc-harness/dist/cli.js`
 #     mirror `RETRIEVAL_CACHE_DIRNAME`, `RETRIEVAL_RUNTIME_DIRNAME` and
 #     `RUNTIME_CLI_RELATIVE` in `cli/src/retrieval/runtime.ts`;
-#   `hr_cache_dir` mirrors `machineCacheDir()` in `cli/src/machine/paths.ts`.
+#   `hr_cache_dir` mirrors `machineCacheDir()` in `cli/src/machine/paths.ts`;
+#   `harness-docs-retrieval`, `serve-mcp`, `HARNESS_DOCS_RETRIEVAL_DATABASE_URL`,
+#     the default connection string and exit 3 mirror `PYTHON_RETRIEVAL_COMMAND`,
+#     `PYTHON_SERVE_SUB_COMMAND`, `PYTHON_DATABASE_URL_VARIABLE`,
+#     `PYTHON_DEFAULT_DATABASE_URL` and `PYTHON_BACKEND_UNAVAILABLE_EXIT` in
+#     `cli/src/retrieval/pythonBackend.ts`.
 #
 # Exit contract:
-#   1    no runtime entry at the resolved path, no cache directory to resolve
-#        it under, or no repository at this script's location; stderr names
-#        which
-#   N    otherwise `docs serve`'s own status, through `exec`; a failure to
-#        source the library exits non-zero before that, on stderr only
+#   0    the Python backend exited 0
+#   1    no repository at this script's location; `docs.retrievalBackend`
+#        outside the enum; or, on the TypeScript backend, no runtime entry at
+#        the resolved path or no cache directory to resolve it under; stderr
+#        names which
+#   3    the Python backend is selected but cannot serve: its command does not
+#        resolve on `PATH`, or it exited non-zero; stderr names which
+#   N    on the TypeScript backend, `docs serve`'s own status, through `exec`; a
+#        failure to source the library exits non-zero before that, on stderr only
 
 set -euo pipefail
 
@@ -50,6 +72,55 @@ if ! root="$(hr_repo_root "$script_dir")"; then
   exit 1
 fi
 
+backend=typescript
+config_status=0
+hr_config_load "$root" || config_status=$?
+if [ "$config_status" -eq 2 ]; then
+  echo "docs-search-server: $root/harness.config.json could not be read, so the default backend (typescript) was taken" >&2
+elif [ "$config_status" -eq 0 ] && hr_docs_retrieval_applies "$root"; then
+  backend_status=0
+  backend="$(hr_docs_retrieval_backend "$root")" || backend_status=$?
+  if [ "$backend_status" -ne 0 ]; then
+    echo "docs-search-server: docs.retrievalBackend in $root/harness.config.json is neither \`typescript\` nor \`python\`; set one of them, then run \`npx autonomous-sdlc-harness doctor\`" >&2
+    exit 1
+  fi
+fi
+
+if [ "$backend" = python ]; then
+  if ! command -v harness-docs-retrieval >/dev/null 2>&1; then
+    echo "docs-search-server: the Python backend is selected but \`harness-docs-retrieval\` does not resolve on PATH (interpreter or package missing); see docs/retrieval.md and run \`npx autonomous-sdlc-harness doctor\`" >&2
+    exit 3
+  fi
+  if [ -z "${HARNESS_DOCS_RETRIEVAL_DATABASE_URL-}" ]; then
+    HARNESS_DOCS_RETRIEVAL_DATABASE_URL='postgresql://harness:harness@127.0.0.1:5432/docs_retrieval'
+  fi
+  export HARNESS_DOCS_RETRIEVAL_DATABASE_URL
+
+  # A background job's stdin is /dev/null unless it is passed explicitly.
+  harness-docs-retrieval serve-mcp --repo "$root" <&0 &
+  child=$!
+  trapped=0
+  trap 'trapped=1; kill -TERM "$child" 2>/dev/null || true' TERM
+  trap 'trapped=1; kill -TERM "$child" 2>/dev/null || true' INT
+
+  # A trapped signal interrupts `wait` before the child's status is collected, so wait again. 127
+  # means the first `wait` had already collected it.
+  child_status=0
+  wait "$child" || child_status=$?
+  while [ "$trapped" -eq 1 ]; do
+    trapped=0
+    again=0
+    wait "$child" 2>/dev/null || again=$?
+    [ "$again" -eq 127 ] || child_status=$again
+  done
+
+  if [ "$child_status" -eq 0 ]; then
+    exit 0
+  fi
+  echo "docs-search-server: the Python backend exited with status $child_status before or while serving; the line above (\`harness-docs-retrieval: …\`) names why; run \`npx autonomous-sdlc-harness doctor\`" >&2
+  exit 3
+fi
+
 if ! cache_dir="$(hr_cache_dir)"; then
   echo "docs-search-server: neither XDG_CACHE_HOME nor HOME is set, so the retrieval runtime cannot be located" >&2
   exit 1

package/templates/scripts/lib/harness-run-lib.sh

@@ -3,7 +3,9 @@
 # the repository it is operating on, reads that repository's
 # `harness.config.json` at run time, answers "is this branch protected?",
 # routes an inbox filename to its engine and branch (`hr_inbox_route_var`),
-# derives a branch name from a title (`hr_derive_branch`), places a dropped
+# derives a branch name from a title (`hr_derive_branch`), judges whether a
+# path lies strictly inside the state directory's scratch directory
+# (`hr_scratch_path_var`), places a dropped
 # artifact in a working copy and commits and pushes it, and derives the
 # anchors (main checkout, work root, worktree directory, repo slug,
 # state-dir paths) the scripts would otherwise each re-derive slightly
@@ -77,9 +79,12 @@
 #      files under the eight planning paths `hr_remote_planning_paths` assigns;
 #      outside it, only the caller-named `<out_dir>` (its `planning/` included)
 #      of `hr_remote_bundle_write` and the caller-named `<out_json>`
-#      of `hr_remote_status_write`. Written only by `hr_remote_status_write`,
-#      `hr_remote_bundle_write` and `hr_remote_bundle_restore`, and nothing
-#      there but a writer's own failed temp file is ever removed.
+#      of `hr_remote_status_write`. The move-aside directory receives the
+#      clarification directory and `PAUSE_PROGRESS.md`, both moved there by
+#      `hr_remote_move_aside` alone. Written only by `hr_remote_status_write`,
+#      `hr_remote_bundle_write`, `hr_remote_bundle_restore` and
+#      `hr_remote_move_aside`, and nothing there but a writer's own failed temp
+#      file is ever removed.
 #   4. THE ARTIFACT PLACEMENT writes one artifact into a working copy. Fence:
 #      the caller-named `<worktree>/<rel>`, its parent directories and that
 #      path's index entry, plus whatever the two caller-named wrappers do.
@@ -93,7 +98,7 @@
 #
 # A caller that calls no `hr_lane_*`, `hr_registry_init`, `hr_registry_set`,
 # `hr_remote_record_init`, `hr_registry_lock`, `hr_registry_unlock`, `hr_remote_status_write`,
-# `hr_remote_bundle_write`, `hr_remote_bundle_restore`, `hr_place_artifact`,
+# `hr_remote_bundle_write`, `hr_remote_bundle_restore`, `hr_remote_move_aside`, `hr_place_artifact`,
 # `hr_commit_placed` or `hr_push_landed` function still gets a library that only reads. The
 # lane's ceilings are the only environment values here that carry policy, because
 # the lane is machine-scoped and has no configuration key to carry them; each is
@@ -209,7 +214,8 @@
 # `HR_LANE_OWNER_AT` and `HR_LANE_BROKEN_OWNER`, and the remote state bundle's
 # names, which `hr_remote_names_var` assigns, with `HR_REMOTE_PLANNING_PATHS`
 # (`hr_remote_planning_paths`) and `HR_REMOTE_PLANNING_PLACED` /
-# `HR_REMOTE_PLANNING_KEPT` (`hr_remote_bundle_restore`). Every one of them is assigned
+# `HR_REMOTE_PLANNING_KEPT` (`hr_remote_bundle_restore`) and `HR_REMOTE_ASIDE`
+# (`hr_remote_move_aside`). Every one of them is assigned
 # before it is read by the function that owns it, so an inherited value from a
 # parent process is overwritten rather than believed.
 #
@@ -594,9 +600,10 @@ hr_config_load() {
   # which is what lets an explicitly EMPTY list read as a configured set rather
   # than as an absent one.
   #
-  # A `phases.*` value that is not a boolean is emitted as `invalid`, so the
-  # string `"true"` — which `tostring` would otherwise make indistinguishable
-  # from `true` — reaches `hr_phase_enabled` as a value it refuses (2).
+  # A `phases.*` or `docs.retrieval` value that is not a boolean is emitted as
+  # `invalid`, so the string `"true"` — which `tostring` would otherwise make
+  # indistinguishable from `true` — reaches `hr_phase_enabled` or
+  # `hr_docs_retrieval_applies` as a value it refuses (2).
   out=$(jq -n -r '
     def s($k; $v):
       if $v == null then empty
@@ -631,6 +638,8 @@ hr_config_load() {
       s("phases.qa";             try (.phases.qa     | if type == "boolean" or . == null then . else "invalid" end) catch null),
       s("phases.docs";           try (.phases.docs   | if type == "boolean" or . == null then . else "invalid" end) catch null),
       s("execution.target";      try .execution.target     catch null),
+      s("docs.retrievalBackend"; try .docs.retrievalBackend catch null),
+      s("docs.retrieval";        try (.docs.retrieval | if type == "boolean" or . == null then . else "invalid" end) catch null),
       s("forge";                 try .forge                catch null),
       s("protectedBranches.present";
         try (if (.protectedBranches | type) == "array" then "1" else null end) catch null),
@@ -918,6 +927,53 @@ hr_forge() {
   return 2
 }
 
+# Whether the docs phase's retrieval step runs: `phases.docs` and
+# `docs.retrieval` both `true`. The shell mirror of `cli/src/config/model.ts` →
+# `retrievalApplies`: change the predicate there and here together. PRINTS
+# NOTHING: the answer is the status, as `hr_phase_enabled`'s is. 0 = both
+# `true`; 1 = either `false` or unset; 2 = the configuration is unresolvable or
+# either value is not a boolean — refused rather than guessed about.
+hr_docs_retrieval_applies() {
+  local root="${1-}" status
+  hr_phase_enabled "$root" docs
+  status=$?
+  [ "$status" -eq 0 ] || return "$status"
+  hr_cfg_scalar_var "docs.retrieval" || return 1
+  case "$HR_CFG_VALUE" in
+    true) return 0 ;;
+    false) return 1 ;;
+  esac
+  return 2
+}
+
+# `docs.retrievalBackend` — which runtime the docs-retrieval index uses:
+# `typescript` or `python`. THE ONE READER OF THE KEY IN THIS FAMILY, and the
+# shell mirror of `cli/src/config/model.ts` → `RETRIEVAL_BACKENDS` /
+# `DEFAULT_RETRIEVAL_BACKEND`: change the enum there and here together. Schema
+# default `typescript`, so an absent key prints `typescript` and 1 is never
+# returned; a `docs` parent of the wrong type (`"docs": "x"`) reads as absent
+# too, because `hr_config_load`'s `try … catch` nulls that key alone — refusing
+# that shape is the schema's job. 2 — printing nothing — when the configuration
+# is unresolvable or the value is outside the enum, a refusal rather than a
+# guess. It does NOT consult `phases.docs` / `docs.retrieval`: the key is read
+# only inside the gate, so a caller asks `hr_docs_retrieval_applies` first and
+# calls this only on its status 0.
+hr_docs_retrieval_backend() {
+  local root="${1-}"
+  hr_config_load "$root" || return 2
+  if ! hr_cfg_scalar_var "docs.retrievalBackend"; then
+    printf 'typescript\n'
+    return 0
+  fi
+  case "$HR_CFG_VALUE" in
+    typescript|python)
+      printf '%s\n' "$HR_CFG_VALUE"
+      return 0
+      ;;
+  esac
+  return 2
+}
+
 # ---------------------------------------------------------------------------
 # Inbox routing — the one owner of the drop filename patterns.
 # ---------------------------------------------------------------------------
@@ -1140,6 +1196,92 @@ hr_state_path() {
   fi
 }
 
+# Judge whether <path> resolves STRICTLY INSIDE `<root>/<state_dir>/scratch/`.
+# Usage: hr_scratch_path_var <root> <path> [<base>]
+#
+# Two callers, differing only in what they do with an accepted path:
+# `scratch-run.sh` executes a file there and `remote-run.sh discard` removes a
+# directory there. So this reports a keyword in `HR_SCRATCH_WHY` and leaves every
+# message and exit code to its caller.
+#
+# The rule, stated once:
+#   - `..` is refused ANYWHERE in the argument, not only as a whole segment —
+#     strictly stronger, and free, because nothing in that directory depends on
+#     a file's name. Then any character outside `A-Za-z0-9._/-` is refused. Both
+#     tests run on <path> as the caller received it, before anything resolves.
+#   - A relative <path> resolves against <base> when given, else <root>; an
+#     absolute one is taken as given.
+#   - Both sides of the comparison are resolved PHYSICALLY (`cd … && pwd -P`), so
+#     a symlinked directory planted inside the scratch tree cannot widen the
+#     fence. The target's parent must be the scratch directory or beneath it, and
+#     a basename of `.` (the scratch directory itself) is refused.
+#   - A target that is itself a symlink is refused rather than followed: its
+#     destination is outside this judgement. The target need not exist.
+#
+# Clears the other four, then sets: `HR_SCRATCH_SUBDIR` (`scratch`, mirroring the `scratch` row
+# of `STATE_DIR_ENTRIES` in `cli/src/generators/stateDir.ts`), `HR_SCRATCH_DIR`
+# (physical), `HR_SCRATCH_PARENT` (physical), `HR_SCRATCH_TARGET`
+# (`<parent>/<basename>`, the path a caller acts on) and `HR_SCRATCH_WHY`.
+# Status / `HR_SCRATCH_WHY`:
+#   0  accepted (WHY empty)
+#   1  refused — `dotdot`, `charset`, `outside`, `itself`, `symlink`
+#   2  the target's parent does not resolve — `no-parent`
+#   3  the scratch directory cannot be located — `no-config`, `no-scratch`
+#   4  <root> or <path> is empty — `usage`
+hr_scratch_path_var() {
+  local root="${1-}" path="${2-}" base="${3-}" scratch candidate name
+  HR_SCRATCH_DIR=""
+  HR_SCRATCH_PARENT=""
+  HR_SCRATCH_TARGET=""
+  HR_SCRATCH_WHY=""
+  HR_SCRATCH_SUBDIR='scratch'
+  if [ -z "$root" ] || [ -z "$path" ]; then
+    HR_SCRATCH_WHY="usage"
+    return 4
+  fi
+  case "$path" in
+    *..*) HR_SCRATCH_WHY="dotdot"; return 1 ;;
+  esac
+  case "$path" in
+    *[!A-Za-z0-9._/-]*) HR_SCRATCH_WHY="charset"; return 1 ;;
+  esac
+  scratch=$(hr_state_path "$root" "$HR_SCRATCH_SUBDIR")
+  if [ "$?" -ne 0 ] || [ -z "$scratch" ]; then
+    HR_SCRATCH_WHY="no-config"
+    return 3
+  fi
+  HR_SCRATCH_DIR=$(cd "$scratch" 2>/dev/null && pwd -P)
+  if [ -z "$HR_SCRATCH_DIR" ]; then
+    HR_SCRATCH_WHY="no-scratch"
+    return 3
+  fi
+  [ -n "$base" ] || base="$root"
+  case "$path" in
+    /*) candidate="$path" ;;
+    *) candidate="${base%/}/$path" ;;
+  esac
+  HR_SCRATCH_PARENT=$(cd "$(dirname "$candidate")" 2>/dev/null && pwd -P)
+  if [ -z "$HR_SCRATCH_PARENT" ]; then
+    HR_SCRATCH_WHY="no-parent"
+    return 2
+  fi
+  case "$HR_SCRATCH_PARENT" in
+    "$HR_SCRATCH_DIR" | "$HR_SCRATCH_DIR"/*) ;;
+    *) HR_SCRATCH_WHY="outside"; return 1 ;;
+  esac
+  name=$(basename "$candidate")
+  if [ "$name" = "." ]; then
+    HR_SCRATCH_WHY="itself"
+    return 1
+  fi
+  HR_SCRATCH_TARGET="$HR_SCRATCH_PARENT/$name"
+  if [ -L "$HR_SCRATCH_TARGET" ]; then
+    HR_SCRATCH_WHY="symlink"
+    return 1
+  fi
+  return 0
+}
+
 # The machine-local settings directory — one place an operator keeps values that
 # vary per machine rather than per repository, which is why it is not a config
 # key and not a repository file. Return 1 when there is no home to anchor it to.
@@ -1442,8 +1584,10 @@ hr_remote_record_init() {
 #   limit and readable in the Actions run list. GitHub documents no ref limit.
 #
 # THIS SECTION ONLY READS. It fetches nothing and creates no branch or file; a
-# caller that wants `origin` fresh fetches first. A registry is read only when
-# it already exists, because `hr_registry_get` creates an absent one.
+# caller that wants `origin` fresh fetches first. Given a <gh_cli>, it also asks
+# GitHub one read per candidate — the run workflow's runs under that name — and
+# still writes nothing. A registry is read only when it already exists, because
+# `hr_registry_get` creates an absent one.
 # ---------------------------------------------------------------------------
 
 # The two limits the rule above names.
@@ -1525,11 +1669,37 @@ EOF
   return 0
 }
 
-# Judge <name> against the listings `hr_branch_taken_lists_var` last read. The
-# answers and `HR_TAKEN_WHY` are `hr_branch_name_taken`'s.
+# hr_branch_run_history <root> <gh_cli> <name> — 0 when the run workflow
+# (`HR_REMOTE_WORKFLOW_RUN_FILE`) lists a run under <name>, 1 when it lists
+# none, 2 when <gh_cli> cannot run, exits non-zero, or answers anything but a
+# JSON array. Sets no `HR_` variable: the names are assigned inside the
+# subshell that `cd`s to <root>.
+#
+# GitHub keeps a deleted branch's runs listed under its name, and a later run
+# of that name inherits them: Gate 12 round 5 found run `36569531374` of the
+# deleted `feat_invoices` (`docs/development.md` → Gate 12 → Round 5, finding
+# 1). One bounded read per candidate, not one listing of every branch, because
+# a bounded all-branch listing could miss an old name. Bash 3.2 and jq 1.5.
+hr_branch_run_history() {
+  local root="${1-}" gh_cli="${2-}" name="${3-}" answer verdict
+  [ -n "$root" ] && [ -n "$gh_cli" ] && [ -n "$name" ] || return 2
+  answer=$(cd "$root" 2>/dev/null && hr_remote_names_var &&
+    "$gh_cli" run list --workflow "$HR_REMOTE_WORKFLOW_RUN_FILE" --branch "$name" --limit 1 --json databaseId 2>/dev/null) || return 2
+  verdict=$(printf '%s' "$answer" | jq -r 'if type == "array" then (if length > 0 then "history" else "none" end) else "other" end' 2>/dev/null) || return 2
+  case "$verdict" in
+    history) return 0 ;;
+    none) return 1 ;;
+  esac
+  return 2
+}
+
+# Judge <name> against the listings `hr_branch_taken_lists_var` last read, then,
+# given a <gh_cli>, against the run workflow's history — last, so the free local
+# checks answer first. The answers and `HR_TAKEN_WHY` are
+# `hr_branch_name_taken`'s.
 hr_branch_taken_judge() {
   local LC_ALL=C
-  local root="${1-}" name="${2-}" registry="${3-}" lower status nl
+  local root="${1-}" name="${2-}" registry="${3-}" gh_cli="${4-}" lower status nl
   nl='
 '
   HR_TAKEN_WHY=""
@@ -1557,18 +1727,29 @@ hr_branch_taken_judge() {
     HR_TAKEN_WHY="a run registry record"
     return 0
   fi
+  if [ -n "$gh_cli" ]; then
+    status=0
+    hr_branch_run_history "$root" "$gh_cli" "$name" || status=$?
+    case "$status" in
+      0) HR_TAKEN_WHY="a run of the run workflow listed under that name"; return 0 ;;
+      1) ;;
+      *) HR_TAKEN_WHY="the run history of $name could not be listed"; return 2 ;;
+    esac
+  fi
   return 1
 }
 
-# hr_branch_name_taken <root> <name> [<registry>] — 0 taken, 1 free, 2 cannot
-# tell. Sets `HR_TAKEN_WHY` to a short phrase naming the collision or the
-# failure. Taken: a protected name; a branch on `origin`, compared
-# case-insensitively; a local branch; under `<state_dir>` on
-# `origin/<defaultBranch>`, a directory named <name> or a file
-# `<name>_task_prompt.md`, `<name>_story_plan.md` or `<name>_docs.md` — which a
-# merged and deleted branch still leaves; a record in an existing <registry>.
+# hr_branch_name_taken <root> <name> [<registry>] [<gh_cli>] — 0 taken, 1 free,
+# 2 cannot tell. Sets `HR_TAKEN_WHY` to a short phrase naming the collision or
+# the failure. A caller with no registry passes `""` before <gh_cli>. Taken: a
+# protected name; a branch on `origin`, compared case-insensitively; a local
+# branch; under `<state_dir>` on `origin/<defaultBranch>`, a directory named
+# <name> or a file `<name>_task_prompt.md`, `<name>_story_plan.md` or
+# `<name>_docs.md` — which a merged and deleted branch still leaves; a record in
+# an existing <registry>; given a <gh_cli>, any run of the run workflow listed
+# under <name> (`hr_branch_run_history`), whose listing failing is a 2.
 hr_branch_name_taken() {
-  local root="${1-}" name="${2-}" registry="${3-}"
+  local root="${1-}" name="${2-}" registry="${3-}" gh_cli="${4-}"
   HR_TAKEN_WHY=""
   if [ -z "$root" ] || [ -z "$name" ]; then
     HR_TAKEN_WHY="no branch name to judge"
@@ -1576,20 +1757,21 @@ hr_branch_name_taken() {
   fi
   hr_config_load "$root" || :
   hr_branch_taken_lists_var "$root" || return 2
-  hr_branch_taken_judge "$root" "$name" "$registry"
+  hr_branch_taken_judge "$root" "$name" "$registry" "$gh_cli"
 }
 
-# hr_derive_branch <root> <text> <fallback> [<registry>] — print the derived name
-# and return 0; return 2, printing nothing, when a `taken` judgement could not
-# tell or no base routes back to itself; return 3, printing nothing, when every
-# suffix through `HR_BRANCH_SUFFIX_MAX` is taken. Never a guessed name.
+# hr_derive_branch <root> <text> <fallback> [<registry>] [<gh_cli>] — print the
+# derived name and return 0; return 2, printing nothing, when a `taken`
+# judgement could not tell or no base routes back to itself; return 3, printing
+# nothing, when every suffix through `HR_BRANCH_SUFFIX_MAX` is taken. Never a
+# guessed name. <gh_cli> reaches every judgement as `hr_branch_name_taken`'s.
 #
 # THE BASE MUST ROUTE BACK TO ITSELF: `hr_inbox_route_var` on each drop filename
 # a run of that name produces has to give the base as its branch, so no derived
 # name makes the inbox patterns ambiguous. A base that does not is replaced by
 # <fallback> once.
 hr_derive_branch() {
-  local root="${1-}" text="${2-}" fallback="${3-}" registry="${4-}"
+  local root="${1-}" text="${2-}" fallback="${3-}" registry="${4-}" gh_cli="${5-}"
   local base="" candidate suffix routes n status
   hr_branch_limits_var
   candidate=$(hr_branch_slug "$text") || candidate="$fallback"
@@ -1615,7 +1797,7 @@ hr_derive_branch() {
   n=1
   while :; do
     status=0
-    hr_branch_taken_judge "$root" "$candidate" "$registry" || status=$?
+    hr_branch_taken_judge "$root" "$candidate" "$registry" "$gh_cli" || status=$?
     case "$status" in
       1) printf '%s\n' "$candidate"; return 0 ;;
       2) return 2 ;;
@@ -1704,8 +1886,9 @@ hr_push_landed() {
 # names. Every name below is a variable `hr_remote_names_var` assigns, and it
 # also assigns `HR_REMOTE_WORKFLOW_RUN_FILE`, the run workflow's file name, for
 # the GitHub-route producers `hr_github_answer_route` and
-# `hr_github_resume_route`. Those two are mirrors of the header's table; no
-# function spells either one, or any other name here.
+# `hr_github_resume_route` and for the run-history probe `hr_branch_run_history`.
+# Those two are mirrors of the header's table; no function spells either one,
+# or any other name here.
 #
 #   <bundle>/status.json                 the job's record, fixed schema below
 #   <bundle>/clarifications/<branch>/    the whole branch directory, answered/ included
@@ -2000,6 +2183,45 @@ EOF
   return 0
 }
 
+# hr_remote_move_aside <root> <rel_path>
+#
+# Moves `<root>/<state_dir>/<rel_path>`, a file or a directory, with one `mv`
+# into `autonomous_logs/remote_superseded/<epoch>/<rel_path>` (`<epoch>-<n>`,
+# the first `n` = 1, 2, … where that path is free, when an earlier move took
+# that second), creating the parents and removing nothing. On success
+# `HR_REMOTE_ASIDE` holds the absolute destination; it is empty at entry.
+#
+# 0 moved; 1 a missing argument, a <rel_path> that is absolute or has a `..`
+# segment, or a failed `mkdir` / `mv`; 2 — touching nothing — <root>'s
+# configuration is unresolvable; 3 — touching nothing — no source exists.
+hr_remote_move_aside() {
+  local root="${1-}" rel="${2-}" state base epoch aside n
+  HR_REMOTE_ASIDE=''
+  [ -n "$root" ] && [ -n "$rel" ] || return 1
+  case "$rel" in
+    /*) return 1 ;;
+  esac
+  case "/$rel/" in
+    */../*) return 1 ;;
+  esac
+  state=$(hr_state_dir "$root") || return 2
+  hr_remote_names_var
+  base="${root%/}/$state"
+  [ -e "$base/$rel" ] || [ -L "$base/$rel" ] || return 3
+  epoch=$(date +%s)
+  aside="$base/$HR_REMOTE_SUPERSEDED_DIR/$epoch"
+  n=0
+  while [ -e "$aside/$rel" ] || [ -L "$aside/$rel" ]; do
+    n=$((n + 1))
+    aside="$base/$HR_REMOTE_SUPERSEDED_DIR/$epoch-$n"
+  done
+  aside="$aside/$rel"
+  mkdir -p "${aside%/*}" 2>/dev/null || return 1
+  mv "$base/$rel" "$aside" 2>/dev/null || return 1
+  HR_REMOTE_ASIDE=$aside
+  return 0
+}
+
 # hr_remote_bundle_restore <bundle_dir> <root> <branch> <mode>
 #
 # <mode> `job` places the clarification directory, `PAUSE_PROGRESS.md`, the
@@ -2016,20 +2238,18 @@ EOF
 # stay `0` in `mirror` mode.
 #
 # THE CLARIFICATION DIRECTORY IS REPLACED WHOLESALE, AND NOTHING IS DELETED. An
-# existing target is moved aside with one `mv` into
-# `autonomous_logs/remote_superseded/<epoch>/clarifications/<branch>` (`<epoch>-<n>`
-# when an earlier restore took that second) before the
-# bundle's copy goes in, so a stale local pair cannot survive and no recursive
-# removal is ever shelled out. A bundle carrying no clarification directory
-# leaves the target alone: in a mirror it may hold an answer not yet relayed.
-#
-# 0 restored; 1 a missing argument, an unknown <mode> or a failed copy; 2 —
-# touching nothing — when the bundle is unrecognised (no readable `status.json`,
-# a schema other than `HR_REMOTE_STATE_SCHEMA`, or a `branch` other than
-# <branch>) or <root>'s configuration is unresolvable.
+# existing target is moved aside by `hr_remote_move_aside` before the bundle's
+# copy goes in, so a stale local pair cannot survive and no recursive removal is
+# ever shelled out. A bundle carrying no clarification directory leaves the
+# target alone: in a mirror it may hold an answer not yet relayed.
+#
+# 0 restored; 1 a missing argument, an unknown <mode>, a failed move aside or a
+# failed copy; 2 — touching nothing — when the bundle is unrecognised (no
+# readable `status.json`, a schema other than `HR_REMOTE_STATE_SCHEMA`, or a
+# `branch` other than <branch>) or <root>'s configuration is unresolvable.
 hr_remote_bundle_restore() {
   local bundle="${1-}" root="${2-}" branch="${3-}" mode="${4-}"
-  local state base named target epoch aside n tmp pdir file rel p inset
+  local state base named target tmp pdir file rel p inset
   HR_REMOTE_PLANNING_PLACED=0
   HR_REMOTE_PLANNING_KEPT=0
   [ -n "$bundle" ] && [ -n "$root" ] && [ -n "$branch" ] || return 1
@@ -2047,16 +2267,7 @@ hr_remote_bundle_restore() {
   if [ -d "$bundle/$HR_REMOTE_CLARIFY_DIR/$branch" ]; then
     target="$base/$HR_REMOTE_CLARIFY_DIR/$branch"
     if [ -e "$target" ]; then
-      epoch=$(date +%s)
-      aside="$base/$HR_REMOTE_SUPERSEDED_DIR/$epoch"
-      n=0
-      while [ -e "$aside/$HR_REMOTE_CLARIFY_DIR/$branch" ]; do
-        n=$((n + 1))
-        aside="$base/$HR_REMOTE_SUPERSEDED_DIR/$epoch-$n"
-      done
-      aside="$aside/$HR_REMOTE_CLARIFY_DIR/$branch"
-      mkdir -p "${aside%/*}" 2>/dev/null || return 1
-      mv "$target" "$aside" 2>/dev/null || return 1
+      hr_remote_move_aside "$root" "$HR_REMOTE_CLARIFY_DIR/$branch" || return 1
     fi
     mkdir -p "${target%/*}" 2>/dev/null || return 1
     cp -R "$bundle/$HR_REMOTE_CLARIFY_DIR/$branch" "$target" 2>/dev/null || return 1