autonomous-sdlc-harness 0.4.1 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autonomous-sdlc-harness",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "The outer loop of the autonomous SDLC harness: init, doctor, config and daemon management for the harness Claude Code plugin, plus opt-in local docs retrieval.",
   "license": "Apache-2.0",
   "author": "firu-daniel",

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

@@ -17,9 +17,12 @@
 # That also makes moot GitHub's disabling of scheduled workflows in a public
 # repository after 60 days without activity.
 #
-# UNVERIFIED: whether GITHUB_TOKEN with `actions: write` may enable and disable
-# a workflow. If it may not, the pausing job's `paused` notification says
-# auto-resume is unavailable, and the run waits for
+# Gate 12 round 2, on 2026-09-29, verified that `gh workflow disable` succeeds
+# under GITHUB_TOKEN with `actions: write`: a hand-started tick logged
+# `poll: no branch is waiting; disabled harness-resume.yml`, and the workflow's
+# state became `disabled_manually`. UNVERIFIED: the enable, because no job
+# ended on a usage pause. If it is refused, the pausing job's `paused`
+# notification says auto-resume is unavailable, and the run waits for
 # /autonomous-sdlc-harness:branch-resume.
 #
 # THE INTERVAL IS YOURS TO EDIT. On a private repository every tick is billed
@@ -56,6 +59,19 @@
 #                                     HARNESS_REMOTE_STOP, HARNESS_PUSH_URL,
 #                                     POLL_STATE_ARTIFACT_NAME
 #   cli/src/config/model.ts           DEFAULTS.scriptsDir, DEFAULTS.stateDir
+#
+# ACTION PINS.
+#   actions/checkout@v5
+#   actions/upload-artifact@v6
+# Each is the lowest major whose own action.yml declares `runs.using: node24`,
+# per a maintainer's lookups of each action's action.yml and release notes on
+# 2026-09-29T08:21Z (UTC). Each of those majors' release notes requires Actions
+# Runner 2.327.1 or newer; a GitHub-hosted runner already has it, and a
+# self-hosted one must run it (docs/remote-execution.md, section 8). A major
+# tag, not a commit sha: both are GitHub's own `actions/` organisation, the
+# owner of the runner and GITHUB_TOKEN this job already trusts, and a major tag
+# takes the action's own patch and security releases where a sha would freeze
+# your copy. Pin shas in your copy if you want them.
 
 name: harness-resume
 
@@ -89,7 +105,7 @@ jobs:
       HARNESS_PUSH_URL: ${{ secrets.HARNESS_PUSH_URL }}
     steps:
       - name: Check out the default branch
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           ref: ${{ github.event.repository.default_branch }}
 
@@ -115,7 +131,7 @@ jobs:
 
       - name: Upload the poller state
         if: always() && env.POLL_STATE_DIR != ''
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: harness-poll-state
           path: ${{ env.POLL_STATE_DIR }}

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

@@ -38,6 +38,22 @@
 #                                     runtime sits in `retrieval/`
 #   cli/src/retrieval/runtime.ts      RETRIEVAL_CACHE_DIRNAME, that `retrieval/`
 #
+# ACTION PINS.
+#   actions/checkout@v5
+#   actions/setup-node@v5
+#   actions/cache/restore@v5
+#   actions/cache@v5
+#   actions/upload-artifact@v6
+# Each is the lowest major whose own action.yml declares `runs.using: node24`,
+# per a maintainer's lookups of each action's action.yml and release notes on
+# 2026-09-29T08:21Z (UTC). Each of those majors' release notes requires Actions
+# Runner 2.327.1 or newer; a GitHub-hosted runner already has it, and a
+# self-hosted one must run it (docs/remote-execution.md, section 8). A major
+# tag, not a commit sha: every action here is GitHub's own `actions/`
+# organisation, the owner of the runner and GITHUB_TOKEN this job already
+# trusts, and a major tag takes the action's own patch and security releases
+# where a sha would freeze your copy. Pin shas in your copy if you want them.
+#
 # WHAT IT READS.
 #   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:
@@ -72,12 +88,12 @@
 # the step timeout. The job-level timeout-minutes is the self-hosted limit; a
 # hosted job is stopped at its own limit whatever that says.
 #
-# WHY THE TIMEOUT IS COMPUTED INTO GITHUB_ENV. Whether a step's timeout-minutes
-# accepts an expression over `runner.environment` could not be checked against
-# GitHub's workflow-syntax documentation when this file was written (no network
-# access), so the first step computes every budget value from
-# `runner.environment` into GITHUB_ENV, and the harness step reads a single
-# `env` value. Gate 12 records the real behaviour.
+# WHY THE TIMEOUT IS COMPUTED INTO GITHUB_ENV. The first step computes every
+# budget value from `runner.environment` into GITHUB_ENV, so the harness step's
+# timeout-minutes reads a single `env` value rather than an expression over the
+# runner kind. Gate 12 round 2, on 2026-09-29, found every harness-run.yml run
+# accepted and its `Run the harness` step run: the expression-valued
+# timeout-minutes is accepted.
 #
 # THE PLUGIN PIN. `claude plugin marketplace add --help` and
 # `claude plugin install --help` (Claude Code 2.1.282) offer no ref or version:
@@ -88,17 +104,19 @@
 # rendered CLI version.
 #
 # WHY retention-days IS SET. The `harness-state` bundle is the only remote copy
-# of a run's clarifications and carried counts; a run parked or paused longer
-# than its retention cannot be answered and loses those counts. 400 is the
+# of a run's clarifications, uncommitted planning drafts and carried counts; a
+# run parked or paused longer than its retention cannot be answered and loses
+# those drafts and counts. 400 is the
 # largest retention any repository can configure, and `actions/upload-artifact`
 # caps a larger `retention-days` at the repository's own maximum, so the value
 # means "as long as this repository allows" — the same bound as leaving it
 # unset. It is explicit so that lowering it is a visible edit. The real bound is
 # the repository's Artifact and log retention setting, which
-# `autonomous-sdlc-harness doctor --check-github` reads. The cap (rather than a
-# rejection) is carried from the action's `@actions/artifact` retention code
-# and could not be re-checked against its v4 README when this file was written
-# (no network access); Gate 12 records the real behaviour.
+# `autonomous-sdlc-harness doctor --check-github` reads. Gate 12 round 2, on
+# 2026-09-29, observed the cap rather than a rejection on `actions/upload-artifact@v4`:
+# the artifact's `expires_at` fell 90 days after its creation, with the
+# repository's artifact-and-log-retention at {"days":90,"maximum_allowed_days":400}.
+# That was v4; the v6 pinned above has not yet been observed by a gate round.
 
 name: harness-run
 run-name: harness ${{ inputs.action }} ${{ inputs.branch }}
@@ -248,7 +266,7 @@ jobs:
 
       - name: Check out the run's branch
         if: env.HARNESS_STOPPED != '1'
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           ref: ${{ inputs.branch }}
           fetch-depth: 0
@@ -280,9 +298,11 @@ jobs:
 
       - name: Set up Node
         if: env.HARNESS_STOPPED != '1'
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: '22'
+          # v5 caches by package.json's packageManager; the job installs nothing through npm's cache, and a lockfile-less repository must not fail this step.
+          package-manager-cache: false
 
       - name: Install the claude CLI when absent
         if: env.HARNESS_STOPPED != '1'
@@ -327,7 +347,7 @@ jobs:
 
       - name: Restore the docs-retrieval cache
         if: env.HARNESS_STOPPED != '1' && steps.config.outputs.retrieval == 'true'
-        uses: actions/cache/restore@v4
+        uses: actions/cache/restore@v5
         with:
           path: ${{ env.HARNESS_RETRIEVAL_CACHE }}
           key: harness-retrieval-${{ runner.os }}-${{ env.HARNESS_CLI_VERSION }}
@@ -377,7 +397,7 @@ jobs:
 
       - name: Upload the state bundle
         if: always() && env.SCRIPTS_DIR != ''
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: harness-state
           path: ${{ runner.temp }}/harness-state
@@ -411,7 +431,7 @@ jobs:
 
       - name: Check out the dispatched ref
         if: env.HARNESS_STOPPED != '1'
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Read the configuration
         id: config
@@ -430,13 +450,15 @@ jobs:
 
       - name: Set up Node
         if: env.HARNESS_STOPPED != '1' && steps.config.outputs.retrieval == 'true'
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: '22'
+          # As in the run job: no npm cache is used, and a lockfile-less repository must not fail this step.
+          package-manager-cache: false
 
       - name: Restore and save the docs-retrieval cache
         if: env.HARNESS_STOPPED != '1' && steps.config.outputs.retrieval == 'true'
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ${{ env.HARNESS_RETRIEVAL_CACHE }}
           key: harness-retrieval-${{ runner.os }}-${{ env.HARNESS_CLI_VERSION }}

package/templates/scripts/autonomous-watcher.sh

@@ -1272,7 +1272,9 @@ notify() {
 #                       bundle still says `running`, or a finished run left no
 #                       bundle, and `expired`, a registry-only value it derives
 #                       when a finished run's bundle has expired (the job can no
-#                       longer take an answer, and the carried counts are lost);
+#                       longer take an answer, and the carried counts and any
+#                       planning drafts not yet committed that it carried are
+#                       lost);
 #                       `status.json` never carries either. Both map to
 #                       `paused` rather than `failed` because a `failed` record
 #                       has no resume path, while the ledger on the branch is

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

@@ -67,9 +67,11 @@
 #   3. THE REMOTE STATE BUNDLE writes the files its format lists. Fence: inside
 #      `<root>/<state_dir>/` (resolved through `hr_state_dir`), only
 #      `autonomous_logs/remote_status.json`, `clarifications/<branch>/`,
-#      `PAUSE_PROGRESS.md`, `.flow_walker_state` and the move-aside directory
-#      `autonomous_logs/remote_superseded/`; outside it, only the caller-named
-#      `<out_dir>` of `hr_remote_bundle_write` and the caller-named `<out_json>`
+#      `PAUSE_PROGRESS.md`, `.flow_walker_state`, the move-aside directory
+#      `autonomous_logs/remote_superseded/` and, only where nothing exists yet,
+#      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.
@@ -183,7 +185,9 @@
 # `HR_LANE_RANK`, `HR_LANE_STATE`, `HR_LANE_RESUME_AT`, `HR_LANE_OBSERVED_AT`,
 # `HR_LANE_OBSERVED_REPO`, `HR_LANE_OWNER_SLUG`, `HR_LANE_OWNER_PID`,
 # `HR_LANE_OWNER_AT` and `HR_LANE_BROKEN_OWNER`, and the remote state bundle's
-# names, which `hr_remote_names_var` assigns. Every one of them is assigned
+# 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
 # before it is read by the function that owns it, so an inherited value from a
 # parent process is overwritten rather than believed.
 #
@@ -1327,18 +1331,43 @@ hr_registry_branches() {
 #   <bundle>/PAUSE_PROGRESS.md           when present
 #   <bundle>/flow_walker_state           <state_dir>/.flow_walker_state, WITHOUT its dot
 #   <bundle>/run.log                     <state_dir>/autonomous_logs/<branch>.log; never restored
+#   <bundle>/planning/<path>             each of these under <state_dir>, when present:
+#                                          story_plans/<branch>_story_plan.md
+#                                          task_plans/<branch>
+#                                          ui_test_plans/<branch>_ui_test_plan.md
+#                                          ui_test_plans/<branch>
+#                                          task_plan_reviews/<branch>
+#                                          business_parity_reviews/<branch>
+#                                          architecture_reviews/<branch>
+#                                          ui_test_plan_reviews/<branch>
 #
 # The walker state loses its dot because `actions/upload-artifact` skips hidden
-# files by default. NOTHING IN THE BUNDLE IS EVER COMMITTED: every file in it is
-# gitignored machine-local state, and the remote-status and move-aside paths sit
-# under `autonomous_logs/`, whose ignore rule already covers them.
+# files by default. THE BUNDLE ITSELF IS NEVER COMMITTED. Every file outside
+# `planning/` is gitignored machine-local state, and the remote-status and
+# move-aside paths sit under `autonomous_logs/`, whose ignore rule already
+# covers them. The files under `planning/` are untracked drafts that the flow
+# commits itself at its P1/P3 convergence; the bundle only carries them.
+#
+# THE PLANNING PATHS ARE A MIRROR of the contracts that write and stage them:
+# `plugin/instructions/task_plan_writing_instructions_autonomous.md` →
+# `## Override 3` and `## Override 4` staging lists, and
+# `<scripts_dir>/flows/task_plan_writing.graph.json` → each node's `findingsFolder`. A path
+# added there is an edit to `hr_remote_planning_paths`. Only planning is
+# carried because the walker's one graph is `task_plan_writing.graph.json`;
+# implementation-phase per-unit review folders never span a pause, which waits
+# for a clean tracked tree. `HR_REMOTE_STATE_SCHEMA` stays `'1'`: `planning/`
+# is additive, an older reader ignores it, and a newer reader of an older
+# bundle finds none.
 #
 # WHO READS EACH FILE. `status.json`: `remote-run.sh sync` / `status` (into the
 # local registry), `continue` / `poll` (the decision, `chain`, the reset time)
 # and the next job's seed. The clarification directory and `PAUSE_PROGRESS.md`:
 # the next job, and the user's local mirror. The walker state: the next job
-# only. `run.log`: the user only — `sync` copies it to the main checkout's logs
-# directory itself, and no restore places it.
+# only. `planning/`: the next job only, never a mirror — an untracked draft left
+# in the mirror would make its later fast-forward to `origin/<branch>` refuse,
+# because the draft's own convergence commit adds the same path. `run.log`: the
+# user only — `sync` copies it to the main checkout's logs directory itself,
+# and no restore places it.
 #
 # `status.json` — schema `HR_REMOTE_STATE_SCHEMA`; every value a JSON string:
 #   schema                  a reader that does not recognise it treats the bundle as absent
@@ -1372,6 +1401,27 @@ hr_remote_names_var() {
   HR_REMOTE_LOGS_DIR='autonomous_logs'
   HR_REMOTE_STATUS_SOURCE="$HR_REMOTE_LOGS_DIR/remote_status.json"
   HR_REMOTE_SUPERSEDED_DIR="$HR_REMOTE_LOGS_DIR/remote_superseded"
+  HR_REMOTE_PLANNING_DIR='planning'
+}
+
+# hr_remote_planning_paths <branch>
+#
+# Assigns `HR_REMOTE_PLANNING_PATHS`: the eight planning paths of the format
+# above, relative to <state_dir>, newline-separated, no trailing slash. 1 with
+# an empty value for an empty <branch>.
+hr_remote_planning_paths() {
+  local branch="${1-}"
+  HR_REMOTE_PLANNING_PATHS=''
+  [ -n "$branch" ] || return 1
+  HR_REMOTE_PLANNING_PATHS="story_plans/${branch}_story_plan.md
+task_plans/$branch
+ui_test_plans/${branch}_ui_test_plan.md
+ui_test_plans/$branch
+task_plan_reviews/$branch
+business_parity_reviews/$branch
+architecture_reviews/$branch
+ui_test_plan_reviews/$branch"
+  return 0
 }
 
 # hr_remote_status_write <registry_file> <branch> <out_json> <decision> <detail>
@@ -1475,10 +1525,12 @@ hr_remote_status_get() {
 # <root>'s configured state directory. `status.json` is the job's own
 # `autonomous_logs/remote_status.json` when present; otherwise it is written
 # from <branch>'s registry record with decision `stop`, because a job that never
-# wrote its status never decided to continue. 0 written; 1 a missing argument,
+# wrote its status never decided to continue. Each planning path present is
+# copied under `planning/`, whether or not the branch tracks it: the restore
+# never overwrites, so a tracked copy is inert. 0 written; 1 a missing argument,
 # a non-empty <out_dir> or a failed copy; 2 <root>'s configuration unresolvable.
 hr_remote_bundle_write() {
-  local root="${1-}" branch="${2-}" registry="${3-}" out="${4-}" state base clarify
+  local root="${1-}" branch="${2-}" registry="${3-}" out="${4-}" state base clarify rel dst
   [ -n "$root" ] && [ -n "$branch" ] && [ -n "$registry" ] && [ -n "$out" ] || return 1
   state=$(hr_state_dir "$root") || return 2
   hr_remote_names_var
@@ -1511,15 +1563,36 @@ hr_remote_bundle_write() {
   if [ -f "$base/$HR_REMOTE_LOGS_DIR/$branch.log" ]; then
     cp "$base/$HR_REMOTE_LOGS_DIR/$branch.log" "$out/$HR_REMOTE_LOG_FILE" 2>/dev/null || return 1
   fi
+  hr_remote_planning_paths "$branch" || return 1
+  while IFS= read -r rel; do
+    dst="$out/$HR_REMOTE_PLANNING_DIR/$rel"
+    if [ -f "$base/$rel" ]; then
+      mkdir -p "${dst%/*}" 2>/dev/null || return 1
+      cp "$base/$rel" "$dst" 2>/dev/null || return 1
+    elif [ -d "$base/$rel" ]; then
+      mkdir -p "${dst%/*}" 2>/dev/null || return 1
+      cp -R "$base/$rel" "$dst" 2>/dev/null || return 1
+    fi
+  done <<EOF
+$HR_REMOTE_PLANNING_PATHS
+EOF
   return 0
 }
 
 # hr_remote_bundle_restore <bundle_dir> <root> <branch> <mode>
 #
 # <mode> `job` places the clarification directory, `PAUSE_PROGRESS.md`, the
-# walker state (back under its dotted name) and `status.json` (as
-# `autonomous_logs/remote_status.json`); `mirror` places the first two only. The
-# run log is placed by neither.
+# walker state (back under its dotted name), the planning drafts and
+# `status.json` (as `autonomous_logs/remote_status.json`); `mirror` places the
+# first two only. The run log is placed by neither.
+#
+# A PLANNING DRAFT NEVER OVERWRITES. A regular file under `planning/` whose
+# path lies in `HR_REMOTE_PLANNING_PATHS` and has no `..` segment is placed only
+# where nothing exists, counted in `HR_REMOTE_PLANNING_PLACED`; one whose target
+# exists is left byte-identical — the checkout's copy is the branch's committed
+# record — and counted in `HR_REMOTE_PLANNING_KEPT`. A symlink, a non-regular
+# entry or a path outside the set counts in neither. Both are `0` at entry and
+# 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
@@ -1535,7 +1608,9 @@ hr_remote_bundle_write() {
 # <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
+  local state base named target epoch aside n tmp pdir file rel p inset
+  HR_REMOTE_PLANNING_PLACED=0
+  HR_REMOTE_PLANNING_KEPT=0
   [ -n "$bundle" ] && [ -n "$root" ] && [ -n "$branch" ] || return 1
   case "$mode" in
     job|mirror) ;;
@@ -1575,6 +1650,37 @@ hr_remote_bundle_restore() {
     mkdir -p "$base" 2>/dev/null || return 1
     cp "$bundle/$HR_REMOTE_WALKER_FILE" "$base/$HR_REMOTE_WALKER_SOURCE" 2>/dev/null || return 1
   fi
+  pdir="$bundle/$HR_REMOTE_PLANNING_DIR"
+  if [ -d "$pdir" ] && [ ! -L "$pdir" ]; then
+    hr_remote_planning_paths "$branch" || return 1
+    # Process substitution, not a pipe: the loop must run in this shell so the
+    # counters and `return 1` reach the caller.
+    while IFS= read -r file; do
+      # Re-tested per line: a name holding a newline arrives split and fails here.
+      [ -f "$file" ] && [ ! -L "$file" ] || continue
+      rel=${file#"$pdir"/}
+      case "/$rel/" in
+        */../*) continue ;;
+      esac
+      inset=0
+      while IFS= read -r p; do
+        case "$rel" in
+          "$p"|"$p"/*) inset=1; break ;;
+        esac
+      done <<EOF
+$HR_REMOTE_PLANNING_PATHS
+EOF
+      [ "$inset" = 1 ] || continue
+      if [ -e "$base/$rel" ] || [ -L "$base/$rel" ]; then
+        HR_REMOTE_PLANNING_KEPT=$((HR_REMOTE_PLANNING_KEPT + 1))
+        continue
+      fi
+      target="$base/$rel"
+      mkdir -p "${target%/*}" 2>/dev/null || return 1
+      cp "$file" "$target" 2>/dev/null || return 1
+      HR_REMOTE_PLANNING_PLACED=$((HR_REMOTE_PLANNING_PLACED + 1))
+    done < <(find "$pdir" -type f 2>/dev/null)
+  fi
   mkdir -p "$base/$HR_REMOTE_LOGS_DIR" 2>/dev/null || return 1
   tmp=$(mktemp "$base/$HR_REMOTE_STATUS_SOURCE.tmp.XXXXXX" 2>/dev/null) || return 1
   if cp "$bundle/$HR_REMOTE_STATUS_FILE" "$tmp" 2>/dev/null \

package/templates/scripts/remote-run.sh

@@ -71,11 +71,15 @@
 # past a run with none, and stopping at one whose artifact has expired, since
 # an older copy would be staler state. An expired one restores nothing: under
 # --resume answer it exits 2; otherwise it prints a `::warning::` line naming
-# the run, the expiry and the lost counts and clarification history, and the
-# job continues from the committed ledger. An unexpired one it downloads to `<state_dir>/autonomous_logs/remote_download/<branch>/<id>/`
+# the run, the expiry and the lost counts, clarification history and
+# uncommitted planning drafts, and the job continues from the committed ledger. An unexpired one it downloads to `<state_dir>/autonomous_logs/remote_download/<branch>/<id>/`
 # (skipped when that directory already holds its status.json); and restores it
 # in `job` mode — on every --resume kind, `none` included, because a reused
-# branch keeps its clarification history. Then, under --resume answer, it
+# branch keeps its clarification history. A job-mode restore also places the
+# bundle's `planning/` drafts at their paths under the state directory, never
+# over a file the checkout already has, and when it placed or kept any prints
+# `placed <n> planning file(s) for <branch>; kept <n> the checkout already
+# carries`. Then, under --resume answer, it
 # writes each `"<n>": "<text>"` entry to `clarifications/<branch>/answer_<n>.md`
 # with the exact bytes, after checking every entry first; and with
 # `HARNESS_INPUT_PARK_LOOP_CLEAR` exactly `true` it sets `park_loop_cycles` to
@@ -230,7 +234,8 @@
 #      `mirror` mode into the record's `worktree`, `run.log` copied to the main
 #      checkout's `autonomous_logs/<branch>.remote.log`, and `status`,
 #      `pause_reason`, `usage_resume_at`, `park_loop_cycles`, `remote_run_id`,
-#      `remote_run_url`, `remote_detail` and `remote_synced_at` written
+#      `remote_run_url`, `remote_detail` and `remote_synced_at` written. A
+#      `mirror` restore places no planning draft
 #   4. no artifact, while some bundle exists (`remote_run_id` is set, or an
 #      older finished run carries one): a job that died before its upload.
 #      `paused` / `killed`, `remote_run_id` / `remote_run_url` re-pointed at
@@ -294,7 +299,8 @@
 # `<state_dir>/autonomous_logs/remote_download/<branch>/<id>/` and
 # `<branch>.remote.log` in the main checkout, plus the mirror restore
 # `hr_remote_bundle_restore` performs in the record's `worktree`; for
-# `restore`, that download directory, the job restore, `answer_<n>.md` and the
+# `restore`, that download directory, the job restore (the planning drafts
+# among it), `answer_<n>.md` and the
 # `park_loop_cycles` rewrite of `remote_status.json`, all in the job's
 # checkout; for `save`, <out_dir> and the step summary; for `poll`, its
 # download directories and `<state_dir>/autonomous_logs/poll_state/previous/`
@@ -363,7 +369,8 @@
 #   flow_walker_state) and GITHUB_RUN_ID set to another id:
 #   restore    bash scripts/remote-run.sh restore feat_x --resume none   -> 0; the
 #              checkout carries clarifications/feat_x/question_1.md,
-#              .flow_walker_state and autonomous_logs/remote_status.json
+#              .flow_walker_state and autonomous_logs/remote_status.json, and
+#              places the bundle's planning/ drafts where the checkout has none
 #   answer     HARNESS_INPUT_ANSWERS='{"1":"Use B.\n"}' ... --resume answer -> 0;
 #              clarifications/feat_x/answer_1.md holds exactly `Use B.` + newline
 #   no question  HARNESS_INPUT_ANSWERS='{"2":"x"}' ... --resume answer
@@ -381,7 +388,7 @@
 #              -> prints the expired line, "$r" byte-identical
 #   save       bash scripts/remote-run.sh save feat_x /tmp/b -> 0; /tmp/b holds
 #              status.json, clarifications/feat_x/, flow_walker_state (and
-#              PAUSE_PROGRESS.md, run.log when present); with
+#              PAUSE_PROGRESS.md, run.log, planning/ when present); with
 #              GITHUB_STEP_SUMMARY=/tmp/s, /tmp/s gains the status table
 #   never started  no remote_status.json and no registry: save -> 0, /tmp/b
 #              empty
@@ -1140,7 +1147,7 @@ verb_restore() {
   if [ "$PREV_RUN_STATE" = expired ]; then
     [ "$resume" != answer ] \
       || restore_refuse "the state bundle of run $id expired on $BUNDLE_EXPIRES_AT, so its questions can no longer be answered here: resume from the committed ledger with $RESUME_HINT $branch, or re-drop the task; nothing written"
-    echo "::warning::remote-run.sh: the state bundle of run $id expired on $BUNDLE_EXPIRES_AT: the park-loop, auto-resume and stall counts and the clarification history it carried are lost; this job continues from the committed ledger"
+    echo "::warning::remote-run.sh: the state bundle of run $id expired on $BUNDLE_EXPIRES_AT: the park-loop, auto-resume and stall counts, the clarification history and any planning drafts not yet committed that it carried are lost; this job continues from the committed ledger"
   elif [ -z "$id" ]; then
     [ "$resume" != answer ] \
       || restore_refuse "--resume answer, but no finished run of $branch carries a state bundle; nothing written"
@@ -1163,7 +1170,11 @@ verb_restore() {
     fi
     hr_remote_bundle_restore "$download" "$root" "$branch" job
     case $? in
-      0) echo "remote-run.sh: restored the bundle of run $id into $root" ;;
+      0)
+        echo "remote-run.sh: restored the bundle of run $id into $root"
+        [ $((HR_REMOTE_PLANNING_PLACED + HR_REMOTE_PLANNING_KEPT)) -eq 0 ] \
+          || echo "remote-run.sh: placed $HR_REMOTE_PLANNING_PLACED planning file(s) for $branch; kept $HR_REMOTE_PLANNING_KEPT the checkout already carries"
+        ;;
       2) restore_refuse "the bundle in '$download' is unrecognised for $branch; nothing restored" ;;
       *) restore_fail "restoring '$download' into '$root' failed" ;;
     esac