autonomous-sdlc-harness 0.6.4 → 0.6.6

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

@@ -113,20 +113,23 @@
 #     The credential secrets and HARNESS_GIT_TOKEN are read only by later steps.
 #
 # 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.
+#   actions/checkout          v5.1.0
+#   actions/setup-node        v5.0.0
+#   actions/cache/restore     v5.1.0
+#   actions/cache             v5.1.0
+#   actions/upload-artifact   v6.0.0
+# Each `uses:` names the full commit sha of the release on the comment line
+# above it. Each release is in 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 sha, not a tag: a tag is mutable, and this job holds the Claude
+# credential and write tokens. A pin moves when
+# `npx autonomous-sdlc-harness@<version> init --upgrade-workflows` re-renders
+# this file at a newer release's pins; a hand bump replaces the sha and its
+# comment line together. The version stays on its own line, never trailing the
+# `uses:` value: a value carrying ` #` is never a plain scalar.
 #
 # WHAT IT READS.
 #   Secrets: CLAUDE_CODE_OAUTH_TOKEN and/or ANTHROPIC_API_KEY (one is required;
@@ -145,13 +148,52 @@
 #   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 run's pull request, update it and label it
+# THE PERMISSIONS. `permissions: {}` at workflow level grants nothing, and each
+# job's own block sets every permission it does not list to `none`. Each grant
+# is what that job's own steps run:
+#   wrong-ref  none           it fails the dispatch from its step's `env:` alone
+#   run        contents       push-branch.sh pushes the branch
+#              actions        remote-run.sh `restore` downloads the previous
+#                             bundle, `continue` dispatches and enables the poller
+#              issues         lifecycle comments and state labels, on the issue
+#                             and the pull request, which both use the issues API
+#              pull-requests  remote-run.sh `open` and `deliver` open, update and
+#                             label the run's pull request
+#   collect    contents       `collect` runs `review`, whose hr_push_landed
+#                             pushes the round through push-branch.sh
+#              actions        the settledness read lists runs and downloads the
+#                             bundle; `review` dispatches the round (verb_dispatch)
+#              issues         forge_report's `round` and `not_started` comments
+#                             and labels, collect_notify's comment, and the label
+#                             create forge_set_state retries with
+#              pull-requests  forge_pr_var and round_collect read the pull
+#                             request's reviews and comments, and `round` runs
+#                             `gh pr ready --undo` on a ready pull request
+#   warm       contents read  the checkout. Its actions/cache restore and save
+#                             use the runner's cache token, not GITHUB_TOKEN, and
+#                             its `init` calls no GitHub API
+# A grant narrower than a job's need fails only on GitHub, never locally.
+#
+# THE CHECKOUT CREDENTIAL. The `warm` checkout sets `persist-credentials: false`:
+# that job pushes nothing. The `run` and `collect` checkouts keep the credential
+# persisted, because both push through push-branch.sh with it (`run` with
+# HARNESS_GIT_TOKEN or the job token, `collect` with the job token), so
+# zizmor's `artipacked` finding stands on those two. The one upload, `Upload
+# the state bundle`, takes its path from the runner's temp directory, outside
+# GITHUB_WORKSPACE, so no artifact carries the checkout's .git/config. An edit
+# keeps it so: never point an upload-artifact `path:` inside the workspace while
+# a checkout persists its credential.
+#
+# THE CLAUDE CLI. `Install the claude CLI when absent` installs
+# @anthropic-ai/claude-code unpinned, and only when the runner has no `claude`.
+# The latest is wanted: the agent runner tracks the model API, and
+# harness-control.yml installs it the same way but is never re-rendered by
+# `--upgrade-workflows` (cli/src/generators/githubWorkflows.ts, choice 5), so a
+# version frozen into the templates would stay frozen there. zizmor's
+# `adhoc-packages` finding stands on it, and pinning does not clear it: it flags
+# `npm install -g @anthropic-ai/claude-code@2.1.284` too, measured 2026-10-09.
+# The audit-silent alternatives, `npx --yes` and `curl | bash`, are the same
+# install with less integrity checking.
 #
 # 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
@@ -279,11 +321,7 @@ on:
         type: number
         default: 0
 
-permissions:
-  contents: write
-  actions: write
-  issues: write
-  pull-requests: write
+permissions: {}
 
 defaults:
   run:
@@ -293,6 +331,7 @@ jobs:
   wrong-ref:
     if: (inputs.action == 'run' || inputs.action == 'pause') && github.ref_name != inputs.branch
     runs-on: ${{ vars.HARNESS_RUNNER || 'ubuntu-latest' }}
+    permissions: {}
     steps:
       - name: Refuse a dispatch from another ref
         env:
@@ -305,6 +344,11 @@ jobs:
   run:
     if: inputs.action == 'run' && github.ref_name == inputs.branch
     runs-on: ${{ vars.HARNESS_RUNNER || 'ubuntu-latest' }}
+    permissions:
+      contents: write
+      actions: write
+      issues: write
+      pull-requests: write
     # The self-hosted job limit, 5 days; a hosted job stops at its own limit.
     timeout-minutes: 7200
     concurrency:
@@ -434,7 +478,8 @@ jobs:
 
       - name: Check out the run's branch
         if: env.HARNESS_STOPPED != '1'
-        uses: actions/checkout@v5
+        # actions/checkout v5.1.0
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
         with:
           ref: ${{ inputs.branch }}
           fetch-depth: 0
@@ -466,7 +511,8 @@ jobs:
 
       - name: Set up Node
         if: env.HARNESS_STOPPED != '1'
-        uses: actions/setup-node@v5
+        # actions/setup-node v5.0.0
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444
         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.
@@ -522,7 +568,8 @@ jobs:
 
       - name: Restore the docs-retrieval cache
         if: env.HARNESS_STOPPED != '1' && steps.config.outputs.retrieval == 'true'
-        uses: actions/cache/restore@v5
+        # actions/cache/restore v5.1.0
+        uses: actions/cache/restore@caa296126883cff596d87d8935842f9db880ef25
         with:
           path: ${{ env.HARNESS_RETRIEVAL_CACHE }}
           key: harness-retrieval-${{ runner.os }}-${{ env.HARNESS_CLI_VERSION }}
@@ -582,7 +629,8 @@ jobs:
 
       - name: Upload the state bundle
         if: always() && env.SCRIPTS_DIR != ''
-        uses: actions/upload-artifact@v6
+        # actions/upload-artifact v6.0.0
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
         with:
           name: harness-state
           path: ${{ runner.temp }}/harness-state
@@ -612,6 +660,11 @@ jobs:
     needs: run
     if: ${{ inputs.action == 'run' && !cancelled() && github.ref_name == inputs.branch }}
     runs-on: ${{ vars.HARNESS_RUNNER || 'ubuntu-latest' }}
+    permissions:
+      contents: write
+      actions: write
+      issues: write
+      pull-requests: write
     concurrency:
       group: harness-review-${{ inputs.branch }}
       cancel-in-progress: false
@@ -669,7 +722,8 @@ jobs:
           exit 1
 
       - name: Check out the default branch for collecting
-        uses: actions/checkout@v5
+        # actions/checkout v5.1.0
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
         with:
           ref: ${{ github.event.repository.default_branch }}
           token: ${{ github.token }}
@@ -703,6 +757,8 @@ jobs:
   warm:
     if: inputs.action == 'warm'
     runs-on: ${{ vars.HARNESS_RUNNER || 'ubuntu-latest' }}
+    permissions:
+      contents: read
     env:
       HARNESS_CLI_VERSION: '{{cliVersion}}'
       HARNESS_REMOTE_STOP: ${{ vars.HARNESS_REMOTE_STOP }}
@@ -716,7 +772,10 @@ jobs:
 
       - name: Check out the dispatched ref
         if: env.HARNESS_STOPPED != '1'
-        uses: actions/checkout@v5
+        # actions/checkout v5.1.0
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
+        with:
+          persist-credentials: false
 
       - name: Read the configuration
         id: config
@@ -735,7 +794,8 @@ jobs:
 
       - name: Set up Node
         if: env.HARNESS_STOPPED != '1' && steps.config.outputs.retrieval == 'true'
-        uses: actions/setup-node@v5
+        # actions/setup-node v5.0.0
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444
         with:
           node-version: '22'
           # As in the run job: no npm cache is used, and a lockfile-less repository must not fail this step.
@@ -743,7 +803,8 @@ jobs:
 
       - name: Restore and save the docs-retrieval cache
         if: env.HARNESS_STOPPED != '1' && steps.config.outputs.retrieval == 'true'
-        uses: actions/cache@v5
+        # actions/cache v5.1.0
+        uses: actions/cache@caa296126883cff596d87d8935842f9db880ef25
         with:
           path: ${{ env.HARNESS_RETRIEVAL_CACHE }}
           key: harness-retrieval-${{ runner.os }}-${{ env.HARNESS_CLI_VERSION }}

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

@@ -5,7 +5,7 @@
 # `forge` is `github` and its `execution.target` is `github-actions`. Written
 # create-if-absent: from then on it is yours to tune, and a re-run of `init`
 # keeps your copy. `init --upgrade-workflows` does NOT re-render it: it carries
-# no version pin and calls the scripts on the default branch, so it shares
+# no CLI version pin and calls the scripts on the default branch, so it shares
 # their re-run contract — `init --force` replaces it after a `.bak`.
 #
 # WHAT IT DOES. One job runs `remote-run.sh trigger`, which does everything
@@ -38,7 +38,9 @@
 # and the order its refusals are made in. Nothing here pre-filters on it.
 #
 # THE PERMISSIONS, declared because the default token may be read-only
-# (docs/github-integration-research.md, T2):
+# (docs/github-integration-research.md, T2). `permissions: {}` at workflow
+# level grants nothing, and the `trigger` job's own block sets every permission
+# it does not list to `none`, so a job added later inherits nothing:
 #   contents: write   push the new branch carrying the task prompt
 #   actions: write    dispatch harness-run.yml and look up the run it created
 #   issues: write     comment on the issue and remove the trigger label
@@ -49,7 +51,13 @@
 # HARNESS_GIT_TOKEN: a branch pushed with GITHUB_TOKEN starts no workflow
 # (docs/remote-execution.md, `### Verified in Gate 12 round 3`), so the prompt
 # commit does not run your CI. A full fetch, because pushing a new branch from
-# a shallow clone has not been measured anywhere.
+# a shallow clone has not been measured anywhere. The checkout keeps the
+# credential persisted, so zizmor's `artipacked` finding stands on it:
+# `remote-run.sh trigger` runs `start`, whose `hr_push_landed` pushes the new
+# branch through push-branch.sh with that credential. The job uploads no
+# artifact, so nothing carries the checkout's .git/config off the runner; an
+# edit adding an upload never points its `path:` at the workspace root or at
+# `.git/`.
 #
 # NO CONCURRENCY GROUP. A group keeps at most one pending run and cancels an
 # earlier pending one, which would drop a trigger. Two starts that race for one
@@ -75,16 +83,19 @@
 #   cli/src/config/model.ts           DEFAULTS.scriptsDir
 #
 # ACTION PINS.
-#   actions/checkout@v5
-# The lowest major whose own action.yml declares `runs.using: node24`, per a
-# maintainer's lookups of its action.yml and release notes on
-# 2026-09-29T08:21Z (UTC). That major's release notes require 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: it 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 a sha in your copy if you want one.
+#   actions/checkout          v5.1.0
+# The `uses:` names the full commit sha of the release on the comment line
+# above it. The release is in the lowest major whose own action.yml declares
+# `runs.using: node24`, per a maintainer's lookups of its action.yml and release
+# notes on 2026-09-29T08:21Z (UTC). That major's release notes require 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 sha, not
+# a tag: a tag is mutable, and this job holds a write token while it reads
+# untrusted issue text. `init --upgrade-workflows` does not re-render this file
+# (see WHO WRITES IT), so its pin moves only when `init --force` replaces it
+# after a `.bak`, or by a hand bump, which replaces the sha and its comment line
+# together. The version stays on its own line, never trailing the `uses:` value:
+# a value carrying ` #` is never a plain scalar.
 
 name: harness-trigger
 run-name: harness trigger ${{ github.event.issue.number || github.event.action }}
@@ -95,10 +106,7 @@ on:
   repository_dispatch:
     types: [harness-task]
 
-permissions:
-  contents: write
-  actions: write
-  issues: write
+permissions: {}
 
 defaults:
   run:
@@ -108,6 +116,10 @@ jobs:
   trigger:
     if: github.event_name == 'repository_dispatch' || github.event.label.name == (vars.HARNESS_TRIGGER_LABEL || 'sdlc-harness')
     runs-on: ${{ vars.HARNESS_RUNNER || 'ubuntu-latest' }}
+    permissions:
+      contents: write
+      actions: write
+      issues: write
     env:
       GH_TOKEN: ${{ github.token }}
       HARNESS_REMOTE_STOP: ${{ vars.HARNESS_REMOTE_STOP }}
@@ -117,7 +129,8 @@ jobs:
       HARNESS_RUN_ACTORS: ${{ vars.HARNESS_RUN_ACTORS }}
     steps:
       - name: Check out the default branch
-        uses: actions/checkout@v5
+        # actions/checkout v5.1.0
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
         with:
           token: ${{ github.token }}
           fetch-depth: 0

package/templates/scripts/autonomous-watcher.sh

@@ -249,7 +249,7 @@
 # would watch a directory nobody drops files into, log where nobody tails, and
 # honor a kill switch nobody can reach — silently, for as long as it runs. So an
 # unreadable library, a location outside a repository, or a `harness.config.json`
-# that is absent, unparseable, multi-document, missing `defaultBranch` or beyond
+# that is absent, unparsable, multi-document, missing `defaultBranch` or beyond
 # the `jq` floor ends the process with ONE line on stderr and a non-zero status,
 # before anything is created. Those lines go to stderr rather than to the watcher
 # log, because the log's location is exactly what could not be resolved; the
@@ -1574,7 +1574,7 @@ EOF
 
 # The report itself: every registered repository with its state, model, effort,
 # live-run count and per-repository cap, then one summary. Reading fails open in
-# §7's sense — absent, unreadable, unparseable, non-object or unrecognised-schema
+# §7's sense — absent, unreadable, unparsable, non-object or unrecognised-schema
 # reads as "no repositories are registered", and a malformed entry is dropped
 # rather than hiding the rest. Never a shell error, never a non-zero status,
 # never a write.
@@ -2001,7 +2001,7 @@ ${GLOBAL_STOP}. End at 'branch ready for review' — never merge, never push to
   # an --add-dir, because a job session was refused reads under a root the profile
   # file already granted. `init` stays the one producer of the list. File order;
   # an empty entry and one equal to the two directories already passed are
-  # skipped. An absent, unparseable or keyless profile adds nothing and never
+  # skipped. An absent, unparsable or keyless profile adds nothing and never
   # blocks the launch — `doctor --remote-job` refuses an unusable profile earlier.
   local extra_dir_args extra_dirs_logged
   extra_dir_args=()
@@ -3106,7 +3106,7 @@ remote_commit_and_push() {
 #   ^(.+)_docs\.md$              -> docs        engine, a fresh working copy
 #
 # The library owns these patterns and their order: `hr_inbox_route_var` in
-# lib/harness-run-lib.sh, whose comment states why they cannot mis-route.
+# lib/harness-run-lib.sh, whose comment states why they cannot misroute.
 #
 # A filename matching none of the three is logged and ARCHIVED rather than left
 # where it is, so it is not re-logged on every pass for as long as the watcher
@@ -3583,14 +3583,14 @@ usage_read_run() {
   sf="${lp%.log}.stream.jsonl"
   [ -f "$sf" ] || return 0
   tail -n 8000 "$sf" 2>/dev/null | grep '"type":"rate_limit_event"' |
-    jq -rs --argjson thr "$USAGE_SEVEN_DAY_PAUSE_PCT" '
+    jq -rs --argjson threshold "$USAGE_SEVEN_DAY_PAUSE_PCT" '
       [ .[] | select(.rate_limit_info) | .rate_limit_info ] as $ev
       | [ ($ev | map(select(.rateLimitType == "five_hour"))  | last),
           ($ev | map(select(.rateLimitType == "seven_day")) | last),
           ($ev | map(select(.rateLimitType != "five_hour" and .rateLimitType != "seven_day")) | last) ]
       | map(select(. != null))[]
       | (.status // "unknown") as $st0
-      | (if (.rateLimitType == "seven_day") and ($st0 == "allowed_warning") and (((.utilization // 0)) < $thr)
+      | (if (.rateLimitType == "seven_day") and ($st0 == "allowed_warning") and (((.utilization // 0)) < $threshold)
            then "allowed" else $st0 end) as $st
       | "\($st) \(.isUsingOverage // false) \(.resetsAt // 0) \(.overageResetsAt // 0)"' 2>/dev/null
 }

package/templates/scripts/cleanup-merged-worktrees.sh

@@ -325,7 +325,7 @@ run_bounded() {
 # string `0`, and `[ 0 -ge 00 ]` is true on the first iteration, so every sweep
 # kills its own fetch before it starts, blames the network, and never cleans up
 # another branch. Comparing the VALUE closes both: `[ ]` returns non-zero for an
-# unparseable or out-of-range string as readily as for a number that fails the
+# unparsable or out-of-range string as readily as for a number that fails the
 # test, and the default is what survives either way. The upper clamp is what keeps
 # a fat-fingered value from expressing "wait forever" in seconds.
 fetch_timeout="${HARNESS_FETCH_TIMEOUT:-60}"

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

@@ -1100,7 +1100,7 @@ hr_docs_retrieval_backend() {
 # anchored SUFFIX regexes are mutually exclusive by construction: a filename
 # cannot end in more than one of `_task_prompt.md` / `_review[_<n>].md` /
 # `_docs.md`, so a branch whose own name contains `review` or `task_prompt`
-# cannot be mis-routed — `foo_review_task_prompt.md` is the task engine on branch
+# cannot be misrouted — `foo_review_task_prompt.md` is the task engine on branch
 # `foo_review`, and `foo_task_prompt_review.md` is the review engine on branch
 # `foo_task_prompt`. POSIX leftmost-longest matching of the greedy `(.+)` derives
 # the right branch from a round-suffixed name: `foo_review_2.md` -> branch `foo`
@@ -2501,7 +2501,7 @@ EOF
 # reset would pin the file for the life of the machine.
 #
 # FAIL OPEN ON THE STATE, CLOSED ON THE LANE. An absent, unreadable or
-# unparseable `usage-state.json` reads as `unknown 0`, which defers nobody:
+# unparsable `usage-state.json` reads as `unknown 0`, which defers nobody:
 # pausing on an unreadable file would put a machine-level fault in charge of run
 # state, and each repository's own gate is what pauses its runs. A lock directory
 # that cannot be read or created is NOT assumed free: `hr_lane_acquire` returns

package/templates/scripts/remote-run.sh

@@ -38,7 +38,8 @@
 #                 (always 0, 1 only on a usage error: its paragraph)
 #   remote-run.sh collect <branch> [--pr <n>] [--repo <root>]
 #                 (always 0, 1 only on a usage error: its paragraph)
-#   remote-run.sh control [--repo <root>]   (its own exit map: its paragraph)
+#   remote-run.sh control [--needs-agent] [--repo <root>]
+#                 (its own exit map: its paragraph)
 #     0  sent (for stop: the action=stop marker was dispatched, and every
 #        queued, waiting or in-progress `harness run` run of that branch was
 #        asked to cancel, or there was none); for status and fetch: printed
@@ -534,6 +535,18 @@
 #      no such word exists today): the reply lists every command and names
 #      `docs/github-run-control.md`. Skipped for a mention.
 # Then THE BRANCH, and the exact form's arm (`control_run_verb`) or MENTION.
+# `--needs-agent` answers only whether MENTION would start a session: the
+# intake above, then refusals 1 to 3 (`control_gates`, shared with `control`),
+# run alone, posting, dispatching and creating nothing; its one `gh` call is
+# `authorise_actor`'s permission call, and the branch is never resolved. One
+# stdout line each: exit 0 `needs-agent: yes, a mention by @<login> on #<n>`;
+# exit 2 `needs-agent: no, <reason>` for an event other than `issue_comment`,
+# an ignored comment (after its own line), the exact form (before any gate,
+# no `gh` call), or a refusal, whose <reason> is that refusal's reply text;
+# exit 3 `needs-agent: undecided, <AUTH_WHY>` when the permission call failed
+# (`control` still refuses that with exit 2); exit 1 as `control`'s.
+# `WORKFLOW_CONTROL_FILE` runs it before installing the agent; the act step,
+# plain `control`, still re-checks everything.
 # MENTION. `verb_control`'s first statements, for every event, copy `IN_OAUTH`
 # / `IN_API` into the non-exported `MENTION_OAUTH` / `MENTION_API` and unset
 # them, with `CLAUDE_CODE_OAUTH_TOKEN` / `ANTHROPIC_API_KEY`, so no `gh`, `git`
@@ -611,8 +624,8 @@
 # is `branch-resume`'s confirmation. Exits: 0 answered or nothing to do; 2
 # refused; 3 a state read, plugin, binary or agent failure, or a credential
 # value in `text` or `answer`; a carried-out verb, its arm's. The workflow's
-# interface: `IN_OAUTH` / `IN_API` and
-# `HARNESS_MENTION_PLUGIN_DIR`.
+# interface: `IN_OAUTH` / `IN_API`, `HARNESS_MENTION_PLUGIN_DIR`, and
+# `control --needs-agent`'s exit 2, on which it skips installing the agent.
 # THE BRANCH. On a pull request (`.issue.pull_request.url` set), its head, by
 # `pr view`: a fork's pull request is refused, because this event carries the
 # repository's secrets, and nothing from its head is checked out or run; one
@@ -1540,6 +1553,13 @@
 #              harness-run.yml --ref feat_x -f action=pause -f branch=feat_x`,
 #              then one comment on 12 opening `Read from your mention as
 #              `@sdlc-harness pause`.`
+#   needs-agent  the mention's c.json, `control --needs-agent` -> 0, one line
+#              `needs-agent: yes, a mention by @alice on #12`; "$s.log" holds
+#              only the permission call
+#   needs-agent  c.json's body `@sdlc-harness pause` -> 2, one `needs-agent: no`
+#   exact      line naming the exact form; "$s.log" unchanged
+#   needs-agent  the mention with HARNESS_RUN_ACTORS=bob -> 2, one `needs-agent:
+#   unlisted   no` line naming HARNESS_RUN_ACTORS; nothing posted
 
 set -u
 
@@ -1664,7 +1684,7 @@ usage() {
   echo "       remote-run.sh open <branch> [--repo <root>]" >&2
   echo "       remote-run.sh deliver <branch> <bundle_dir> [--repo <root>]" >&2
   echo "       remote-run.sh collect <branch> [--pr <n>] [--repo <root>]" >&2
-  echo "       remote-run.sh control [--repo <root>]" >&2
+  echo "       remote-run.sh control [--needs-agent] [--repo <root>]" >&2
   [ "${verb-}" != save ] || exit "$EXIT_OK"
   exit "$EXIT_USAGE"
 }
@@ -1764,6 +1784,7 @@ reviewers_arg=""
 allow_no_run=0
 pr_arg=""
 branch_gone=0
+needs_agent=0
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
@@ -1824,6 +1845,9 @@ while [ "$#" -gt 0 ]; do
     --branch-gone)
       [ "$verb" = stop ] || usage "$1 is a stop option"
       branch_gone=1; shift ;;
+    --needs-agent)
+      [ "$verb" = control ] || usage "$1 is a control option"
+      needs_agent=1; shift ;;
     -*)
       usage "unknown option '$1'" ;;
     *)
@@ -3541,7 +3565,7 @@ verb_poll() {
 verb_pause_requested() {
   local found
   list_runs
-  # An unparseable createdAt is no match rather than a failed read.
+  # An unparsable createdAt is no match rather than a failed read.
   found=$(printf '%s' "$GH_OUT" | jq -r --arg t "harness pause $branch" --argjson since "$since_arg" '
     [.[] | select(.displayTitle == $t)
       | ((.createdAt // "") | try fromdateiso8601 catch null)
@@ -7423,9 +7447,75 @@ control_mention() {
   exit "$EXIT_GH"
 }
 
+# control_gates — refusals 1 to 3 of `control`, in its order, for both
+# `control` and `--needs-agent`. 0 when all pass; otherwise 1 with CG_EXIT,
+# CG_WHY and CG_WAY set as `control_refuse` takes them, and CG_AUTH the
+# `authorise_actor` status (0 when an earlier gate refused). Posts nothing.
+CG_EXIT=0
+CG_WHY=""
+CG_WAY=""
+CG_AUTH=0
+control_gates() {
+  local forge target
+  CG_EXIT="$EXIT_REFUSED"
+  CG_WHY=""
+  CG_WAY=""
+  CG_AUTH=0
+  if [ -n "${HARNESS_REMOTE_STOP-}" ]; then
+    CG_WHY="the repository variable \`HARNESS_REMOTE_STOP\` is set, which stops every command"
+    CG_WAY="Clear it under **Settings → Secrets and variables → Actions → Variables**, then comment again."
+    return 1
+  fi
+
+  forge=$(hr_forge "$root") || forge=""
+  target=$(hr_execution_target "$root") || target=""
+  if [ "$forge" != github ] || [ "$target" != github-actions ]; then
+    CG_WHY="the default branch's \`harness.config.json\` does not turn run control on: it needs \`forge\` set to \`github\` (it is ${forge:-not set or unreadable}) and \`execution.target\` set to \`github-actions\` (it is ${target:-unreadable})"
+    CG_WAY="Set both keys on the default branch, then comment again."
+    return 1
+  fi
+
+  if ! rerun_actor_listed; then
+    CG_WHY="${RUN_ACTORS_WHY%.}"
+    CG_WAY="Only a person the repository variable \`HARNESS_RUN_ACTORS\` admits may re-run this job; one of them can comment again."
+    return 1
+  fi
+
+  authorise_actor "$CONTROL_ACTOR" "$CONTROL_SENDER_TYPE" || CG_AUTH=$?
+  if [ "$CG_AUTH" -ne 0 ]; then
+    CG_WHY="${AUTH_WHY%.}"
+    CG_WAY="Only a collaborator with write, maintain or admin access whom the repository variable \`HARNESS_RUN_ACTORS\` admits (when unset, the owner alone of a repository a personal account owns, and nobody in an organisation-owned one), or a bot listed in \`HARNESS_TRIGGER_ALLOWED_BOTS\`, commands a run."
+    return 1
+  fi
+  return 0
+}
+
+# control_needs_agent_no <reason> — the `--needs-agent` answer that no session
+# starts: one line, exit 2.
+control_needs_agent_no() {
+  echo "remote-run.sh: control: needs-agent: no, $1"
+  exit "$EXIT_REFUSED"
+}
+
+# control_needs_agent — `--needs-agent` after the comment intake: the exact
+# form, then `control_gates`, answered as one line and an exit. Never returns.
+control_needs_agent() {
+  [ -z "$CONTROL_VERB" ] \
+    || control_needs_agent_no "the comment is the exact form \`$COMMAND_HANDLE $CONTROL_VERB\`"
+  if ! control_gates; then
+    if [ "$CG_AUTH" -eq 4 ]; then
+      echo "remote-run.sh: control: needs-agent: undecided, $AUTH_WHY"
+      exit "$EXIT_GH"
+    fi
+    control_needs_agent_no "$CG_WHY"
+  fi
+  echo "remote-run.sh: control: needs-agent: yes, a mention by @$CONTROL_ACTOR on #$CONTROL_NUMBER"
+  exit "$EXIT_OK"
+}
+
 verb_control() {
   local LC_ALL=C
-  local review=0 close=0 forge="" target="" status
+  local review=0 close=0
   # Unset first so an inherited export of either name cannot keep it exported.
   unset MENTION_OAUTH MENTION_API MENTION_JOB_TOKEN_B64
   MENTION_OAUTH="${IN_OAUTH-}"
@@ -7447,9 +7537,17 @@ verb_control() {
   fi
   hr_have_jq || { echo "remote-run.sh: control needs jq" >&2; exit "$EXIT_USAGE"; }
 
+  if [ "$needs_agent" -eq 1 ] && [ "$GITHUB_EVENT_NAME" != issue_comment ]; then
+    control_needs_agent_no "a \`$GITHUB_EVENT_NAME\` event is not a comment"
+  fi
+
   case "$GITHUB_EVENT_NAME" in
     pull_request_review) control_review_intake || return 0 ;;
-    issue_comment) control_comment_intake || return 0 ;;
+    issue_comment)
+      if ! control_comment_intake; then
+        [ "$needs_agent" -eq 0 ] || control_needs_agent_no "the comment is ignored"
+        return 0
+      fi ;;
     issues) control_issues_intake || return 0 ;;
     pull_request) control_pull_request_intake || return 0 ;;
     delete) control_delete_intake || return 0 ;;
@@ -7463,6 +7561,8 @@ verb_control() {
     esac
   fi
 
+  [ "$needs_agent" -eq 0 ] || control_needs_agent
+
   control_tmp="${RUNNER_TEMP-}"
   if [ -z "$control_tmp" ] || [ ! -d "$control_tmp" ]; then
     control_tmp=$(mktemp -d) || { echo "remote-run.sh: control: mktemp failed" >&2; exit "$EXIT_USAGE"; }
@@ -7473,29 +7573,7 @@ verb_control() {
   # Decided by the event name, never CONTROL_VERB: a comment can name `close`.
   [ "$close" -eq 0 ] || control_close
 
-  if [ -n "${HARNESS_REMOTE_STOP-}" ]; then
-    control_refuse "$EXIT_REFUSED" "the repository variable \`HARNESS_REMOTE_STOP\` is set, which stops every command" \
-      "Clear it under **Settings → Secrets and variables → Actions → Variables**, then comment again."
-  fi
-
-  forge=$(hr_forge "$root") || forge=""
-  target=$(hr_execution_target "$root") || target=""
-  if [ "$forge" != github ] || [ "$target" != github-actions ]; then
-    control_refuse "$EXIT_REFUSED" "the default branch's \`harness.config.json\` does not turn run control on: it needs \`forge\` set to \`github\` (it is ${forge:-not set or unreadable}) and \`execution.target\` set to \`github-actions\` (it is ${target:-unreadable})" \
-      "Set both keys on the default branch, then comment again."
-  fi
-
-  if ! rerun_actor_listed; then
-    control_refuse "$EXIT_REFUSED" "${RUN_ACTORS_WHY%.}" \
-      "Only a person the repository variable \`HARNESS_RUN_ACTORS\` admits may re-run this job; one of them can comment again."
-  fi
-
-  status=0
-  authorise_actor "$CONTROL_ACTOR" "$CONTROL_SENDER_TYPE" || status=$?
-  if [ "$status" -ne 0 ]; then
-    control_refuse "$EXIT_REFUSED" "${AUTH_WHY%.}" \
-      "Only a collaborator with write, maintain or admin access whom the repository variable \`HARNESS_RUN_ACTORS\` admits (when unset, the owner alone of a repository a personal account owns, and nobody in an organisation-owned one), or a bot listed in \`HARNESS_TRIGGER_ALLOWED_BOTS\`, commands a run."
-  fi
+  control_gates || control_refuse "$CG_EXIT" "$CG_WHY" "$CG_WAY"
 
   if [ "$review" -eq 0 ] && [ "$CONTROL_MENTION" != 1 ] \
     && { [ -z "$CONTROL_VERB" ] || ! control_verb_handled "$CONTROL_VERB"; }; then

package/templates/state-dir/autonomous_inbox/README.md

@@ -1,6 +1,6 @@
 # autonomous_inbox/
 
-The unattended run loop's drop point: one file per run request, and its **name** is the whole request — it selects the engine command, the working-copy strategy and where the dropped file lands, all three at once. `<branch>_task_prompt.md` starts a delivery run in a fresh working copy and lands the prompt in `<state_dir>/task_prompts/`; `<branch>_review[_<n>].md` starts a fix round for a hands-on review in that branch's existing working copy and lands the review in `<state_dir>/user_reviews/` with its round suffix intact; `<branch>_docs.md` starts a documentation run and lands the checklist in `<state_dir>/docs_catalog/`. The three patterns are anchored suffixes and mutually exclusive, so a branch whose own name contains `review` or `task_prompt` is not mis-routed, and only the branch is read out of the name — never the round, which the engine resolves inside the working copy.
+The unattended run loop's drop point: one file per run request, and its **name** is the whole request — it selects the engine command, the working-copy strategy and where the dropped file lands, all three at once. `<branch>_task_prompt.md` starts a delivery run in a fresh working copy and lands the prompt in `<state_dir>/task_prompts/`; `<branch>_review[_<n>].md` starts a fix round for a hands-on review in that branch's existing working copy and lands the review in `<state_dir>/user_reviews/` with its round suffix intact; `<branch>_docs.md` starts a documentation run and lands the checklist in `<state_dir>/docs_catalog/`. The three patterns are anchored suffixes and mutually exclusive, so a branch whose own name contains `review` or `task_prompt` is not misrouted, and only the branch is read out of the name — never the round, which the engine resolves inside the working copy.
 
 A drop is written by the harness's prompt command, by its hands-on-review command, or by hand for a documentation checklist, which no shipped command writes. The only reader is the run daemon, on its next poll pass: there is no queue server and no webhook in between. Once it has consumed a file the daemon moves it aside into `.processed/` under a timestamp; a file matching **none** of the three patterns is archived into the same place under a `rejected_` prefix, with one log line and no registry record. A drop the daemon defers instead — the kill switch is up, the run cap is full, the usage hold is on — is left exactly where it is, so a later pass picks it up with nothing to re-drop by hand.