autonomous-sdlc-harness 0.5.0 → 0.6.0

package/templates/github/workflows/harness-run.yml

@@ -41,6 +41,33 @@
 #   cli/src/machine/paths.ts          machineCacheDir, under which the retrieval
 #                                     runtime sits in `retrieval/`
 #   cli/src/retrieval/runtime.ts      RETRIEVAL_CACHE_DIRNAME, that `retrieval/`
+#   remote-run.sh (the scriptsDir copy) RUN_JOB_NAME (`run`): the `run` job has no
+#                                     `name:`, so GitHub names it by its key,
+#                                     and the settledness test reads that
+#                                     job's status by that name
+#   harness-control.yml               the concurrency group
+#                                     `harness-review-<branch>`, shared by its
+#                                     review jobs and the `collect` job here
+#
+# THE COLLECT JOB. When a run ends, `remote-run.sh collect` starts the next
+# user-review round from every review requesting changes that `control`
+# answered "collected" while the run was in flight, so a reviewer waits at most
+# for that run and never resubmits. It is a job of its own, not a step of
+# `run`, for two reasons: a step cannot hold a concurrency group, and this one
+# must share `harness-review-<branch>` with harness-control.yml's review jobs so
+# the two never place a round at once; and the settledness test reads "the
+# `run` job is completed", which no step inside that job could see. Under
+# `!cancelled()` a failed `run` job still reaches it, and the run's state bundle
+# decides whether the run ended or only paused or parked; a cancelled or
+# stopped run skips it. The group name mirrors harness-control.yml's, and
+# RUN_JOB_NAME in remote-run.sh mirrors the `run` job's key (DECLARED MIRRORS
+# above). It reads no secret: its own token pushes the round, dispatches it and
+# comments. It checks out the default branch, as harness-control.yml's review
+# jobs do, never the run's branch: `collect` fetches that branch itself and
+# `review` cuts its own working copy of it, which create-worktree.sh refuses
+# for a branch already checked out. Its step is `continue-on-error` for the
+# report step's reason below: scripts older than this file carry no `collect`
+# verb.
 #
 # ACTION PINS.
 #   actions/checkout@v5
@@ -62,7 +89,9 @@
 #   Secrets: CLAUDE_CODE_OAUTH_TOKEN and/or ANTHROPIC_API_KEY (one is required;
 #     billing follows the API key when both are set), HARNESS_GIT_TOKEN (optional:
 #     a personal or App token, so the job's pushes trigger your own CI, which
-#     GITHUB_TOKEN pushes never do), HARNESS_PUSH_URL (optional notifications).
+#     GITHUB_TOKEN pushes never do; it also opens the run's draft pull request,
+#     so your CI runs on it without an approval click), HARNESS_PUSH_URL
+#     (optional notifications).
 #   Variables: HARNESS_RUNNER, HARNESS_REMOTE_STOP (any value stops every job
 #     before it launches anything), HARNESS_STEP_TIMEOUT_MINUTES,
 #     HARNESS_SELF_PAUSE_AFTER_MINUTES, HARNESS_MAX_CHAIN, and the watcher
@@ -71,6 +100,20 @@
 #   harness.config.json, at run time: `scriptsDir` and whether docs retrieval
 #     applies. No configured value is frozen into this file.
 #
+# THE PERMISSIONS. A workflow-level `permissions:` block sets every permission
+# it does not list to `none`, so each one the job uses is listed:
+#   contents       to push the branch
+#   actions        to dispatch, poll and enable the poller
+#   issues         to comment and set labels on the issue and the pull request,
+#                  which both use the issues API
+#   pull-requests  to open the draft pull request and label it
+#
+# WHY THE REPORT STEP MAY FAIL. `Open the pull request and report` runs
+# `remote-run.sh deliver` after the push, so the pull request's head carries the
+# run's last commit. It is `continue-on-error`: a repository that re-rendered
+# this file without `init --force` still runs scripts with no `deliver` verb,
+# and a finished run must not be marked failed for its report.
+#
 # THE SELF-PAUSE POINT, MEASURED. On a hosted runner the job drops its own PAUSE
 # REMOTE_SELF_PAUSE_AFTER_SECS after it started, the run yields at its next
 # dispatch boundary, and `remote-run.sh continue` chains a new job.
@@ -183,6 +226,8 @@ on:
 permissions:
   contents: write
   actions: write
+  issues: write
+  pull-requests: write
 
 defaults:
   run:
@@ -420,6 +465,13 @@ jobs:
           overwrite: true
           retention-days: 400
 
+      - name: Open the pull request and report
+        if: ${{ !cancelled() && env.SCRIPTS_DIR != '' }}
+        continue-on-error: true
+        env:
+          HARNESS_PR_TOKEN: ${{ secrets.HARNESS_GIT_TOKEN }}
+        run: bash "$SCRIPTS_DIR/remote-run.sh" deliver "$HARNESS_INPUT_BRANCH" "$RUNNER_TEMP/harness-state"
+
       - name: Continue, wait or stop
         if: ${{ !cancelled() && env.SCRIPTS_DIR != '' }}
         run: bash "$SCRIPTS_DIR/remote-run.sh" continue "$HARNESS_INPUT_BRANCH" "$RUNNER_TEMP/harness-state"
@@ -430,6 +482,53 @@ jobs:
           export HARNESS_REPO_SLUG="$HARNESS_REMOTE_SLUG"
           bash "$SCRIPTS_DIR/autonomous-notify.sh" failed "$HARNESS_INPUT_BRANCH" "" \
             "job cancelled: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" || true
+          bash "$SCRIPTS_DIR/remote-run.sh" report failed "$HARNESS_INPUT_BRANCH" --note "the job was cancelled: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" || true
+
+  collect:
+    needs: run
+    if: ${{ inputs.action == 'run' && !cancelled() }}
+    runs-on: ${{ vars.HARNESS_RUNNER || 'ubuntu-latest' }}
+    concurrency:
+      group: harness-review-${{ inputs.branch }}
+      cancel-in-progress: false
+    env:
+      GH_TOKEN: ${{ github.token }}
+      HARNESS_REMOTE_SLUG: ${{ github.repository }}
+      HARNESS_INPUT_BRANCH: ${{ inputs.branch }}
+      HARNESS_REMOTE_STOP: ${{ vars.HARNESS_REMOTE_STOP }}
+      HARNESS_TRIGGER_ALLOWED_BOTS: ${{ vars.HARNESS_TRIGGER_ALLOWED_BOTS }}
+    steps:
+      - name: Check out the default branch for collecting
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          token: ${{ github.token }}
+          fetch-depth: 0
+
+      - name: Check for jq and gh before collecting
+        run: |
+          missing=""
+          for tool in jq gh; do
+            command -v "$tool" >/dev/null 2>&1 || missing="$missing $tool"
+          done
+          if [ -n "$missing" ]; then
+            echo "::error::this runner lacks:$missing. Install them on the self-hosted runner, or use a GitHub-hosted one."
+            exit 1
+          fi
+
+      - name: Read the configuration for collecting
+        run: |
+          scripts_dir=$(jq -r '.scriptsDir // "scripts"' harness.config.json)
+          echo "SCRIPTS_DIR=${scripts_dir%/}" >> "$GITHUB_ENV"
+
+      - name: Set the git identity for collecting
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Start the next round from collected reviews
+        continue-on-error: true
+        run: bash "$SCRIPTS_DIR/remote-run.sh" collect "$HARNESS_INPUT_BRANCH"
 
   warm:
     if: inputs.action == 'warm'

package/templates/github/workflows/harness-trigger.yml

@@ -20,7 +20,8 @@
 #   issues, type `labeled` only, never `opened`: labelling an issue at creation
 #     raises `labeled` too, so listening to both would start twice
 #     (docs/github-integration-research.md, T1). The job runs only for the
-#     label the HARNESS_TRIGGER_LABEL variable names (`harness` when unset);
+#     label the HARNESS_TRIGGER_LABEL variable names (`sdlc-harness` when
+#     unset), and passes the job that same label, never an empty one;
 #     every other label yields a skipped job, which runs no runner and bills
 #     nothing (docs/remote-execution.md, `### Verified in Gate 12 round 2`).
 #   repository_dispatch, type `harness-task`: the entry for any other adapter
@@ -66,7 +67,7 @@
 # DECLARED MIRRORS — a rename on either side is an edit to both:
 #   cli/src/remote/githubActions.ts   WORKFLOW_TRIGGER_FILE, HARNESS_RUNNER,
 #                                     HARNESS_REMOTE_STOP, HARNESS_TRIGGER_LABEL,
-#                                     DEFAULT_TRIGGER_LABEL (`harness`),
+#                                     DEFAULT_TRIGGER_LABEL (`sdlc-harness`),
 #                                     HARNESS_TRIGGER_ALLOWED_BOTS,
 #                                     TRIGGER_DISPATCH_EVENT_TYPE (`harness-task`)
 #   cli/src/config/model.ts           DEFAULTS.scriptsDir
@@ -103,13 +104,13 @@ defaults:
 
 jobs:
   trigger:
-    if: github.event_name == 'repository_dispatch' || github.event.label.name == (vars.HARNESS_TRIGGER_LABEL || 'harness')
+    if: github.event_name == 'repository_dispatch' || github.event.label.name == (vars.HARNESS_TRIGGER_LABEL || 'sdlc-harness')
     runs-on: ${{ vars.HARNESS_RUNNER || 'ubuntu-latest' }}
     env:
       GH_TOKEN: ${{ github.token }}
       HARNESS_REMOTE_STOP: ${{ vars.HARNESS_REMOTE_STOP }}
       HARNESS_REMOTE_SLUG: ${{ github.repository }}
-      HARNESS_TRIGGER_LABEL: ${{ vars.HARNESS_TRIGGER_LABEL }}
+      HARNESS_TRIGGER_LABEL: ${{ vars.HARNESS_TRIGGER_LABEL || 'sdlc-harness' }}
       HARNESS_TRIGGER_ALLOWED_BOTS: ${{ vars.HARNESS_TRIGGER_ALLOWED_BOTS }}
     steps:
       - name: Check out the default branch

package/templates/scripts/README.md

@@ -2,4 +2,4 @@
 
 The project-command wrapper scripts `init` writes into the configured `scriptsDir`: type-check, test and dev-server, configured through `commands.*` in `harness.config.json`, and deploy, configured through `deploy.command` on the separate `deploy` object — so no build tool and no hosting provider is hardcoded anywhere in the harness. They exist as scripts rather than as raw command lines because an unattended run's permission profile can allow-list a literal script path far more safely than an arbitrary command, which is why `commands.<key>` holds the **wrapper invocation** `bash <scriptsDir>/<name>.sh` — the literal the profile allow-lists — while the **raw** command line lives inside the script. Which raw line that is follows one precedence, and it is what keeps the pair from being circular: a raw command line already sitting in `commands.<key>` wins, because an adopter who edited it there meant it — and that state is **reported** rather than silently blessed, since the raw line is not the value the permission profile allow-lists: `init` names it as it writes the wrapper from it, `config set` names it as the value is stored, and `doctor`'s `command-wrappers` check grades it on every later run; otherwise, when that key holds this wrapper's own invocation — the normal state after a first `init` — the body is the line stack detection produced; and when neither resolves, the body names what to fix — the key to set, or for `deploy`, which detection never supplies, this script itself — and exits non-zero rather than appearing to have run a check it never ran. Two states get no wrapper at all, and therefore no allow entry: a key still holding the placeholder `init` writes for a command it could not detect, and `commands.typecheck` holding the `<none>` sentinel — the first is unfinished and is the one that asks the adopter to do something about it, the second is the answer that this repository has no such command and asks for nothing. **Each script prints its own verdict line**, so a caller never appends an exit-code probe to it: that compound form is exactly what stalls an unattended run on a permission prompt — except `start-dev-server.sh`, which has no verdict to give because it starts a long-running process. Every wrapper anchors itself to its own checkout before it runs and forwards whatever arguments it was given to the **last** command of its raw line — whether that command accepts a bare path or name filter is a property of the command, not of the wrapper, so a line ending in a sub-command's own flags takes none; `docs/cli.md` §5 is the full contract.
 
-**The other family in this directory is not generated.** The run watcher, its restart wrapper, the notifier and its stream formatter, the commit / push / branch-refresh / worktree / cleanup wrappers, the scratch runner, the flow walker `flow-walker.sh` with its gate library `lib/flow-walker-gates.sh` and the planning flow's graph `flows/task_plan_writing.graph.json`, the test-suite runner `run-test-suite.sh`, the docs-retrieval server launcher, `remote-run.sh` (sends a remote run's dispatch, pause, warm-up and stop to GitHub; run by the watcher, the remote job and a person) and the shared library at `lib/harness-run-lib.sh` are copied byte for byte into the same `scriptsDir`, because each reads `harness.config.json` *at run time* rather than carrying a value frozen in when `init` ran — a guard whose protected-branch set was baked into a file at generation time enforces the wrong set the moment that list changes, and does it silently. They therefore carry no `{{token}}` at all. `cli/src/generators/outerLoopScripts.ts` declares that set and marks which of its rows an agent may invoke; `cli/scripts/README.md` records why they live under `scriptsDir` rather than in the installed package. **One of them runs a file it is given:** `scratch-run.sh` runs an agent's language probe or mutation check in the interpreter that file's extension names, and refuses any argument that does not resolve inside `<state_dir>/scratch/`. **Two of them are run by the orchestrating session:** `flow-walker.sh` prints the next routing step of the planning flow and keeps machine-local state at `<state_dir>/.flow_walker_state`; `run-test-suite.sh` is run once per Run gates phase, runs the configured test command, writes its output to a per-round log under `<state_dir>/test_run_logs/` and prints only `pass` or `fail <log path>`. **One of them is started by neither the watcher nor an agent:** `docs-search-server.sh` is started by the agent runner from `.mcp.json` when `docs.retrieval` is on, and `exec`s the machine-shared retrieval runtime's `docs serve`.
+**The other family in this directory is not generated.** The run watcher, its restart wrapper, the notifier and its stream formatter, the commit / push / branch-refresh / worktree / cleanup wrappers, the scratch runner, the flow walker `flow-walker.sh` with its gate library `lib/flow-walker-gates.sh` and the planning flow's graph `flows/task_plan_writing.graph.json`, the test-suite runner `run-test-suite.sh`, the docs-retrieval server launcher, `remote-run.sh` (sends a remote run's dispatch, pause, warm-up and stop to GitHub; run by the watcher, the remote job and a person) and the shared library at `lib/harness-run-lib.sh` are copied byte for byte into the same `scriptsDir`, because each reads `harness.config.json` *at run time* rather than carrying a value frozen in when `init` ran — a guard whose protected-branch set was baked into a file at generation time enforces the wrong set the moment that list changes, and does it silently. They therefore carry no `{{token}}` at all. `cli/src/generators/outerLoopScripts.ts` declares that set and marks which of its rows an agent may invoke; `cli/scripts/README.md` records why they live under `scriptsDir` rather than in the installed package. **One of them runs a file it is given:** `scratch-run.sh` runs an agent's language probe or mutation check in the interpreter that file's extension names, and refuses any argument that does not resolve inside `<state_dir>/scratch/`. **Two of them are run by the orchestrating session:** `flow-walker.sh` prints the next routing step of the planning flow and keeps machine-local state at `<state_dir>/.flow_walker_state`; `run-test-suite.sh` is run once per Run gates phase, runs the configured test command, writes its output to a per-round log under `<state_dir>/test_run_logs/` and prints only `pass` or `fail <log path>`. **One of them is started by neither the watcher nor an agent:** `docs-search-server.sh` is started by the agent runner from `.mcp.json` when `docs.retrieval` is on, and starts the backend `docs.retrievalBackend` selects: it `exec`s the machine-shared retrieval runtime's `docs serve` by default, or runs the Python package's `harness-docs-retrieval serve-mcp` when the key is `python` (its header carries the full exit contract).

package/templates/scripts/autonomous-watcher.sh

@@ -376,7 +376,12 @@
 #     and the next job no `resumed` for it: a chained continuation is not an
 #     event the user acts on. classify_run_exit's `paused` arm notifies only a
 #     `user` pause; job mode sends the others once it has decided. Their titles
-#     carry HARNESS_REMOTE_SLUG when set.
+#     carry HARNESS_REMOTE_SLUG when set. Each job-mode event except `failed` is
+#     also passed to `remote-run.sh report` as it happens, and `failed` once,
+#     when the job ends `failed`; `report` comments on the run's pull request or
+#     issue and moves its state label when `forge` is `github`; `autonomous-notify.sh`
+#     is unchanged, and `completed` is reported by the workflow's `deliver` step
+#     after the push.
 #   * THE INTERACTIVE-TEST PHASE IS SKIPPED, not run: a runner has no browser
 #     wiring, application dependencies or QA credentials for it. With
 #     `phases.qa` true, the task and user_review launch prompts gain one clause
@@ -1150,12 +1155,33 @@ unset USAGE_LANE_ENABLED_RETIRED
 # Every lifecycle event goes out through here, so a notifier that is missing or
 # not executable costs one log line instead of ending a pass. Best-effort by
 # contract: the notifier itself never fails its caller.
+# JOB MODE ONLY: the event is also passed to `remote-run.sh report` via
+# job_report. `failed` is not reported here: run_job reports it once its
+# automatic resumes are ruled out.
 notify() {
   if [ ! -x "$NOTIFY" ]; then
     log "notify: '$NOTIFY' is not executable — '${1:-?}' event for '${2:-?}' not delivered"
+  else
+    "$NOTIFY" "$@" || true
+  fi
+  [ "$JOB_MODE" = 1 ] || return 0
+  [ "${1:-}" != "failed" ] || return 0
+  job_report "$1" "$2" "${3:-}"
+}
+
+# job_report <event> <branch> [<log>] — the only route to GitHub. The detail is
+# withheld: it names local slash commands, and `report` words its comment from
+# the registry record itself.
+job_report() {
+  if [ ! -r "$REMOTE_RUN" ]; then
+    log "notify: '$REMOTE_RUN' is not readable — '${1:-?}' event for '${2:-?}' not reported on GitHub"
     return 0
   fi
-  "$NOTIFY" "$@" || true
+  if [ -n "${3:-}" ]; then
+    bash "$REMOTE_RUN" report "$1" "$2" --repo "$MAIN_REPO" >>"$3" 2>&1 || true
+  else
+    bash "$REMOTE_RUN" report "$1" "$2" --repo "$MAIN_REPO" >/dev/null 2>&1 || true
+  fi
 }
 
 # -----------------------------------------------------------------------------
@@ -4222,6 +4248,7 @@ run_job() {
   # A reason recorded for a pause the run finished before honouring.
   [ "$final" = "paused" ] || registry_set "$branch" pause_reason ""
   [ -n "$detail" ] || detail="the run ended $final in this job"
+  [ "$final" != "failed" ] || job_report failed "$branch" "$log_path"
   job_write_status "$branch" "$remote_status" "$decision" "$detail"
   echo "job: $final $decision"
   exit 0

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