session-orchestrator 3.21.0 → 3.23.0

package/scripts/lib/ci-status-banner.mjs

@@ -18,6 +18,7 @@ import { promisify } from 'node:util';
 import {
   resolveRepoSpec,
   resolveRepoHost,
+  resolveGitlabProjectTarget,
   redactUrlCredentials,
   detectVcsFamily,
   isQueryFailure,
@@ -46,6 +47,128 @@ async function execWithTimeout(cmd, args, opts = {}) {
   ]);
 }
 
+/** C0 controls plus DEL — matching them is the POINT, hence the disable. */
+// eslint-disable-next-line no-control-regex
+const CONTROL_BYTE_RE = /[\u0000-\u001f\u007f]/g;
+
+/**
+ * Replace every C0/DEL control byte with its printable `\uXXXX` escape.
+ *
+ * `JSON.stringify` covers the payload preview, but NOT `SyntaxError.message` —
+ * V8 quotes the offending input INTO that message verbatim, so an ANSI/CR
+ * payload reached the operator's terminal through the error text even after
+ * the preview was escaped. Both halves go through here.
+ *
+ * @param {unknown} text
+ * @returns {string}
+ */
+function escapeControlBytes(text) {
+  return String(text).replace(
+    CONTROL_BYTE_RE,
+    (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`,
+  );
+}
+
+/**
+ * Name a parsed JSON value's type WITHOUT quoting any of its content.
+ *
+ * @param {unknown} value
+ * @returns {'null'|'array'|'object'|'string'|'number'|'boolean'|'undefined'}
+ */
+function jsonTypeOf(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return /** @type {any} */ (typeof value);
+}
+
+/**
+ * Parse CLI stdout as JSON, degrading an unparseable payload onto this module's
+ * documented failure channel instead of a bare `SyntaxError` (CWE-502).
+ *
+ * The throw IS that channel, not an escape from it: every call site runs under
+ * `checkCiStatus`'s outer catch, whose comment already names "unparseable
+ * output" as a case it converts to `console.warn` + `null`. Measured
+ * 2026-08-28 at 30940cb, BEFORE this helper existed: an HTML login page from
+ * `gh repo view`, a literal `null`, and an empty `glab` stdout ALL already
+ * returned `null` with a warn — nothing crashed, and
+ * `tests/lib/ci-status-banner.test.mjs` § "error containment" pinned it. So
+ * this does not fix a crash — the outer catch already turned non-JSON output
+ * into a warn + `null`. The rule this helper closes is lexical
+ * (`json-parse-untrusted-input`, see below), not a crash it prevents.
+ *
+ * What it does fix is the message. The raw parse error (`Unexpected token
+ * '<'`) named neither the CLI nor the request, and this banner spawns four
+ * different subprocesses — an operator reading that line at session-start
+ * could not tell which one returned garbage, which is the same
+ * "could not read looks like nothing to report" class #1022/#1039 attacked.
+ * Guarding at the parse also satisfies the `json-parse-untrusted-input` rule,
+ * which keys on a LEXICALLY enclosing try/catch and cannot see the outer one.
+ *
+ * Ceiling (BV-004): the payload preview is clamped to 120 characters. An
+ * unbounded one would bury the session-start banner it is printed beside — a
+ * paginated HTML error page is the realistic worst case. Revisit if a CLI
+ * starts emitting a diagnostic that needs more than one line to identify.
+ *
+ * The preview is emitted through `JSON.stringify`, not raw. It comes from a
+ * subprocess whose stdout this module does not control and lands in a
+ * `console.warn` beside the session-start banner: a payload carrying ANSI
+ * escapes, a `\r`, or a bare newline could otherwise repaint or overwrite the
+ * lines around it. `JSON.stringify` escapes every control byte and quotes the
+ * result, so the preview stays exactly one line of printable text.
+ *
+ * `expect` closes the second half of the same gap: valid JSON of the WRONG
+ * SHAPE parsed fine and escaped this named channel entirely. Measured
+ * 2026-08-28 at 7daa3d2 — a `gh repo view` that printed `null` reached
+ * `const { nameWithOwner } = …` and threw a bare
+ * `TypeError: Cannot destructure property 'nameWithOwner' of 'null'`, which
+ * names neither the CLI nor the request; a `glab api …/pipelines` that printed
+ * `null` was swallowed by `!Array.isArray(pipelines) → return null`, silent.
+ * Both now fail as the SAME named error the parse failure produces.
+ *
+ * @param {string} stdout  Raw child-process stdout (untrusted)
+ * @param {string} label   The command that produced it, for the failure message
+ * @param {'object'|'array'} [expect]  Required shape; omit to accept any JSON
+ * @returns {unknown} The parsed value
+ * @throws {Error} Named parse/shape failure carrying a bounded payload preview
+ */
+function parseCliJson(stdout, label, expect) {
+  const raw = String(stdout ?? '');
+  // Bounded (BV-004: 120 chars — a paginated HTML error page is the realistic
+  // worst case) AND escaped, so it can never break the line it is printed on.
+  const preview = raw.trim().slice(0, 120);
+  const shown = preview
+    ? `got: ${escapeControlBytes(JSON.stringify(preview))}`
+    : 'got: (empty stdout)';
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const reason = escapeControlBytes(err instanceof Error ? err.message : String(err));
+    // `cause` preserves the original for a debugger; the reason is ALSO
+    // inlined into the message because the outer catch reads `err.message`
+    // only — a cause-only wrapper would lose it on the operator-facing line.
+    throw new Error(
+      `${label} returned unparseable JSON (${reason}) — ${shown}`,
+      { cause: err },
+    );
+  }
+
+  // A shape mismatch reports the JSON TYPE, never the payload. The parse
+  // succeeded, so the bytes add nothing an operator can act on — and
+  // `tests/lib/ci-status-banner.test.mjs` § "unexpected benign pipeline
+  // metadata" pins that a well-formed-but-wrong-shaped API body must not have
+  // its contents echoed anywhere. A type name carries no body content.
+  const actual = jsonTypeOf(parsed);
+  if (expect === 'array' && actual !== 'array') {
+    throw new Error(`${label} returned JSON of an unexpected shape — expected an array, got ${actual}`);
+  }
+  if (expect === 'object' && actual !== 'object') {
+    throw new Error(`${label} returned JSON of an unexpected shape — expected an object, got ${actual}`);
+  }
+  return parsed;
+}
+
 /**
  * The one failure this probe can produce that the frozen
  * `REMOTE_RESOLUTION_REASONS` set has no member for: the async timeout race
@@ -191,48 +314,26 @@ async function getHeadSha(repoRoot, deps = {}) {
 }
 
 /**
- * Get GitLab project ID via glab.
+ * Run a host-pinned `glab api <path>` request and return parsed JSON.
  *
- * #872: pins to `deps.repoSpec` via `-R` when resolved (host-pinning —
- * `glab repo view` otherwise falls back to the ambient `GITLAB_HOST`).
- *
- * @param {string} repoRoot
- * @param {{ execFile?: Function, timeoutMs?: number, repoSpec?: string }} deps
- * @returns {Promise<number>}
- */
-async function getGlabProjectId(repoRoot, deps = {}) {
-  const args = ['repo', 'view', '--output', 'json'];
-  if (deps.repoSpec) args.push('-R', deps.repoSpec);
-  const result = await execWithTimeout(
-    'glab',
-    args,
-    { cwd: repoRoot, timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS, execFile: deps.execFile },
-  );
-  const parsed = JSON.parse(result.stdout);
-  return parsed.id;
-}
-
-/**
- * Run `glab api <path>` and return parsed JSON.
- *
- * #872: `glab api` has no repo/`-R` concept — it accepts only `--hostname`
- * to pin which GitLab instance the request targets. Pinned via
- * `deps.repoHost` when resolved.
+ * GitLab's API accepts neither a remote URL nor `-R`; callers provide the host
+ * proven by `resolveGitlabProjectTarget` so this helper cannot fall back to
+ * ambient `GITLAB_HOST` configuration.
  *
  * @param {string} apiPath
  * @param {string} repoRoot
- * @param {{ execFile?: Function, timeoutMs?: number, repoHost?: string }} deps
+ * @param {{ execFile?: Function, timeoutMs?: number, repoHost: string }} deps
+ * @param {'object'|'array'} [expect]  Required payload shape (see `parseCliJson`)
  * @returns {Promise<unknown>}
  */
-async function glabApi(apiPath, repoRoot, deps = {}) {
-  const args = ['api', apiPath];
-  if (deps.repoHost) args.push('--hostname', deps.repoHost);
+async function glabApi(apiPath, repoRoot, deps = {}, expect = undefined) {
+  const args = ['api', apiPath, '--hostname', deps.repoHost];
   const result = await execWithTimeout(
     'glab',
     args,
     { cwd: repoRoot, timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS, execFile: deps.execFile },
   );
-  return JSON.parse(result.stdout);
+  return parseCliJson(result.stdout, `glab api ${apiPath}`, expect);
 }
 
 /**
@@ -244,9 +345,10 @@ async function glabApi(apiPath, repoRoot, deps = {}) {
  * @param {string} apiPath
  * @param {string} repoRoot
  * @param {{ execFile?: Function, timeoutMs?: number, repoHost?: string }} deps
+ * @param {'object'|'array'} [expect]  Required payload shape (see `parseCliJson`)
  * @returns {Promise<unknown>}
  */
-async function ghApi(apiPath, repoRoot, deps = {}) {
+async function ghApi(apiPath, repoRoot, deps = {}, expect = undefined) {
   const args = ['api', apiPath];
   if (deps.repoHost) args.push('--hostname', deps.repoHost);
   const result = await execWithTimeout(
@@ -254,7 +356,7 @@ async function ghApi(apiPath, repoRoot, deps = {}) {
     args,
     { cwd: repoRoot, timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS, execFile: deps.execFile },
   );
-  return JSON.parse(result.stdout);
+  return parseCliJson(result.stdout, `gh api ${apiPath}`, expect);
 }
 
 /**
@@ -276,21 +378,40 @@ function ageDaysFrom(isoDate, now) {
  *
  * @param {string} repoRoot
  * @param {number} now
- * @param {{ execFile?: Function, timeoutMs?: number, repoSpec?: string, repoHost?: string }} deps
+ * @param {{
+ *   execFile?: Function,
+ *   timeoutMs?: number,
+ *   gitlabProject?: { host: string, encodedProjectPath: string },
+ * }} deps
  * @returns {Promise<object|null>}
  */
 async function checkGitlab(repoRoot, now, deps = {}) {
-  const projectId = await getGlabProjectId(repoRoot, deps);
-  const currentSha = await getHeadSha(repoRoot, deps);
+  const project = deps.gitlabProject;
+  if (
+    !project ||
+    typeof project.host !== 'string' ||
+    typeof project.encodedProjectPath !== 'string' ||
+    project.host === '' ||
+    project.encodedProjectPath === ''
+  ) {
+    return null;
+  }
 
+  const currentSha = await getHeadSha(repoRoot, deps);
+  const apiDeps = { ...deps, repoHost: project.host };
+  const projectPath = `projects/${project.encodedProjectPath}`;
+  // `'array'` is load-bearing, not decoration: before it, a `glab api` that
+  // returned valid JSON of the wrong shape (`null`, `"ok"`, an object) fell
+  // into `!Array.isArray(pipelines) → return null` — a SILENT no-op an operator
+  // reads as "nothing to report". It now raises the same named error an
+  // unparseable payload does, so the outer catch warns.
   const pipelines = await glabApi(
-    `projects/${projectId}/pipelines?order_by=updated_at&sort=desc&per_page=15`,
+    `${projectPath}/pipelines?order_by=updated_at&sort=desc&per_page=15`,
     repoRoot,
-    deps,
+    apiDeps,
+    'array',
   );
 
-  if (!Array.isArray(pipelines)) return null;
-
   const currentPipeline = pipelines.find((p) => p.sha === currentSha);
 
   if (!currentPipeline) {
@@ -316,9 +437,10 @@ async function checkGitlab(repoRoot, now, deps = {}) {
     let allowFailureJobs;
     try {
       const jobs = await glabApi(
-        `projects/${projectId}/pipelines/${currentPipeline.id}/jobs`,
+        `${projectPath}/pipelines/${currentPipeline.id}/jobs`,
         repoRoot,
-        deps,
+        apiDeps,
+        'array',
       );
       if (Array.isArray(jobs)) {
         const softFailed = jobs
@@ -383,9 +505,10 @@ async function checkGitlab(repoRoot, now, deps = {}) {
     let failingJobName;
     try {
       const jobs = await glabApi(
-        `projects/${projectId}/pipelines/${currentPipeline.id}/jobs`,
+        `${projectPath}/pipelines/${currentPipeline.id}/jobs`,
         repoRoot,
-        deps,
+        apiDeps,
+        'array',
       );
       if (Array.isArray(jobs)) {
         const failedJob = jobs.find((j) => j.status === 'failed');
@@ -433,9 +556,9 @@ async function checkGitlab(repoRoot, now, deps = {}) {
  * `[HOST/]OWNER/REPO` shape `resolveRepoSpec({ vcs: 'github' })` returns is
  * exactly the positional's documented input format.
  *
- * The asymmetry with `getGlabProjectId` is real and deliberate: `glab repo
- * view` DOES accept `-R`, and `gh api`/`glab api` accept neither `-R` nor a
- * positional — only `--hostname`. Do not unify these three call sites.
+ * GitLab CI differs deliberately: it derives a host-pinned API target from
+ * the selected remote, while GitHub still needs this lookup because its API
+ * path requires `nameWithOwner`. Do not unify these call sites.
  *
  * `nameWithOwner` is NOT derivable from `deps.repoSpec`, so this lookup
  * cannot be dropped: the spec carries a HOST prefix the `repos/<owner>/<repo>`
@@ -457,12 +580,22 @@ async function checkGithub(repoRoot, deps = {}) {
     repoViewArgs,
     { cwd: repoRoot, timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS, execFile: deps.execFile },
   );
-  const { nameWithOwner } = JSON.parse(repoViewResult.stdout);
+  // `'object'` before the destructuring: a `gh repo view` that printed `null`
+  // (or a bare string, or an array) used to throw a bare
+  // `TypeError: Cannot destructure property 'nameWithOwner' of 'null'`, whose
+  // message names neither the CLI nor the request — the exact identification
+  // failure this helper exists to fix.
+  const { nameWithOwner } = parseCliJson(
+    repoViewResult.stdout,
+    `gh ${repoViewArgs.join(' ')}`,
+    'object',
+  );
 
   const data = await ghApi(
     `repos/${nameWithOwner}/commits/HEAD/check-runs`,
     repoRoot,
     deps,
+    'object',
   );
 
   const checkRuns = data.check_runs;
@@ -523,12 +656,19 @@ async function checkGithub(repoRoot, deps = {}) {
  *     or >= 2 remotes with no preference match) — a benign, measured absence
  *   - Required CLI (glab / gh) not in PATH
  *   - Any CLI invocation times out
- *   - JSON parse failure on CLI output
  *
  * Also returns `null`, but with a `console.warn` trace, when the VCS-detection
- * QUERY ITSELF failed (`git` not on PATH, `git remote -v` erroring) or when a
- * present CLI rejected its invocation. `null` alone cannot express "could not
- * read" — see the outer catch and Step 1 for why the warn channel carries it.
+ * QUERY ITSELF failed (`git` not on PATH, `git remote -v` erroring), when a
+ * present CLI rejected its invocation, or when a CLI returned output this
+ * module could not parse (see {@link parseCliJson}). `null` alone cannot
+ * express "could not read" — see the outer catch and Step 1 for why the warn
+ * channel carries it.
+ *
+ * The unparseable-output case was listed above as SILENT until 2026-08-28.
+ * That was never the behaviour — it has always fallen through to the outer
+ * catch's warn branch (measured at 30940cb). The drift survived because the
+ * one test covering it asserted only the `null` and let the file-wide
+ * `console.warn` spy swallow the rest.
  *
  * @param {{
  *   repoRoot?: string,
@@ -540,10 +680,11 @@ async function checkGithub(repoRoot, deps = {}) {
  *   execFile?: Function,
  *   resolveRepoSpec?: (opts: { repoRoot: string, vcs: 'gitlab'|'github' }) => string|undefined,
  *   resolveRepoHost?: (opts: { repoRoot: string, vcs: 'gitlab'|'github' }) => string|undefined,
- * }} deps  Dependency-injection seam for testing. `resolveRepoSpec`/
- *   `resolveRepoHost` default to the real `vcs-repo-spec.mjs` exports
- *   (#872 host-pinning — see that module for the `-R` vs `--hostname`
- *   contract).
+ *   resolveGitlabProjectTarget?: (opts: { repoRoot: string }) =>
+ *     { host: string, encodedProjectPath: string }|undefined,
+ * }} deps  Dependency-injection seam for testing. GitLab defaults to
+ *   `resolveGitlabProjectTarget`, which proves host and project path from one
+ *   sanitized remote; GitHub retains the #872 spec/host resolvers.
  * @returns {Promise<null | {
  *   status: 'green'|'red'|'unknown',
  *   ok: boolean,
@@ -572,6 +713,7 @@ export async function checkCiStatus(opts = {}, deps = {}) {
 
   const resolveRepoSpecDep = deps.resolveRepoSpec ?? resolveRepoSpec;
   const resolveRepoHostDep = deps.resolveRepoHost ?? resolveRepoHost;
+  const resolveGitlabProjectTargetDep = deps.resolveGitlabProjectTarget ?? resolveGitlabProjectTarget;
 
   const depsWithExec = { execFile: execFileDep, timeoutMs };
 
@@ -605,22 +747,33 @@ export async function checkCiStatus(opts = {}, deps = {}) {
       vcs = detected.vcs;
     }
 
-    // Step 1b (#872): resolve the -R/--hostname host-pinning spec ONCE per
-    // checkCiStatus call — a bare glab/gh spawn falls back to the ambient
-    // GITLAB_HOST/GH_HOST env var, which can silently target the wrong
-    // instance on a multi-instance host. `cwd: repoRoot` alone does not fix
-    // this (ambient env still wins over cwd).
-    const repoSpec = resolveRepoSpecDep({ repoRoot, vcs });
-    const repoHost = resolveRepoHostDep({ repoRoot, vcs });
-    const depsWithPinning = { ...depsWithExec, repoSpec, repoHost };
-
-    // Step 2: dispatch to VCS-specific implementation.
+    // Step 1b: GitLab's API target must be proven before its first glab spawn.
+    // A missing target is never permission to fall back to ambient
+    // GITLAB_HOST/repository configuration. GitHub retains its distinct
+    // repository lookup because its API path requires `nameWithOwner`.
+    //
+    // It is also not an ABSENCE: detectVcs just proved a GitLab remote exists,
+    // so `!gitlabProject` means "remote present, its form was rejected" — a
+    // QUERY FAILURE by the same rule the block above states. Returning null
+    // silently put this repo back in the pre-#1039 state where "CI green" and
+    // "could not ask" look identical. Reachable inputs measured 2026-08-21:
+    // `git://` scheme, a doubled slash in the path, a query string.
     if (vcs === 'gitlab') {
-      return await checkGitlab(repoRoot, now, depsWithPinning);
+      const gitlabProject = resolveGitlabProjectTargetDep({ repoRoot });
+      if (!gitlabProject) {
+        console.warn(
+          'WARN ci-status-banner: a GitLab remote was detected but its host/project path ' +
+            'could not be derived, banner suppressed — CI state is UNKNOWN, not "green".',
+        );
+        return null;
+      }
+      return await checkGitlab(repoRoot, now, { ...depsWithExec, gitlabProject });
     }
 
     if (vcs === 'github') {
-      return await checkGithub(repoRoot, depsWithPinning);
+      const repoSpec = resolveRepoSpecDep({ repoRoot, vcs });
+      const repoHost = resolveRepoHostDep({ repoRoot, vcs });
+      return await checkGithub(repoRoot, { ...depsWithExec, repoSpec, repoHost });
     }
 
     // Unknown VCS value — silent no-op.

package/scripts/lib/command-blocker.mjs

@@ -648,12 +648,57 @@ export function tokenizeCommand(command) {
   return tokens;
 }
 
+/**
+ * Shell RESERVED WORDS and grouping tokens that bash recognises ONLY in COMMAND
+ * POSITION — the first word of a statement (#1145). Everywhere else they are
+ * ordinary arguments (`echo do`, `git commit -m then`), which is exactly why the
+ * drop below is position-gated rather than a blanket text filter.
+ *
+ * Two classes, both dropped, for the same reason:
+ *   - OPENERS (`{`, `(`, `!`, `if`, `elif`, `then`, `else`, `while`, `until`,
+ *     `do`) are followed by a COMMAND. Dropping one moves verb resolution
+ *     towards the real command — the identical safety argument WRAPPER_UNWRAP
+ *     makes for a transparent wrapper: a dropped token is a reserved word, never
+ *     an interpreter, so this cannot turn a match into a miss.
+ *   - CLOSERS (`}`, `)`, `fi`, `done`, `esac`) end one. In command position they
+ *     are the whole segment, which then filters out as empty.
+ *
+ * Deliberately NOT listed:
+ *   - `for` / `select` / `case` / `in` / `function` — followed by a NAME or WORD,
+ *     never a command. Dropping them would invent a verb (`for t in a` → `t`)
+ *     where the truthful answer is "this segment has no command".
+ *   - `time` — a reserved word AND an external binary, already classified as a
+ *     transparent wrapper in WRAPPER_UNWRAP. One classification per token, in
+ *     one table: a second entry here would fork the wrapper-vs-keyword decision
+ *     the way `VERB_PREFIXES` once forked WRAPPER_UNWRAP (#991).
+ *
+ * NAMED CEILING (BV-004): only a STANDALONE token is dropped. bash requires
+ * whitespace around `{` / `}`, so brace groups are always covered; a subshell
+ * written WITHOUT the space (`(rm -rf /)`) lexes as the glued word `(rm` and is
+ * not reached — the pre-#1145 behaviour, unchanged. Peeling the paren off the
+ * token TEXT would mutate a token five consumers read positionally, which is a
+ * larger contract change than this defect justifies. Revisit if a glued-paren
+ * form shows up in a real overflow triage or guard-bypass measurement.
+ */
+const COMMAND_POSITION_KEYWORDS = new Set([
+  '{', '(', '!', 'if', 'elif', 'then', 'else', 'while', 'until', 'do',
+  '}', ')', 'fi', 'done', 'esac',
+]);
+
 /**
  * Split a tokenized command into chained segments on shell control operators
  * (`;`, `&&`, `||`, `|`, `&`) and on newline separators (#981). Only UNQUOTED
  * single-token operators split; an operator that arrived inside quotes stays
  * part of its segment.
  *
+ * A segment additionally has its COMMAND-POSITION reserved words stripped
+ * (#1145) — see {@link COMMAND_POSITION_KEYWORDS}. Without this the first token
+ * of a compound statement is `do` / `then` / `{` / `(` and NEVER the command,
+ * so every consumer that reads a segment head saw a keyword: measured against
+ * the live issue-budget guard with `max-per-session: 1, mode: strict`,
+ * `for t in a b c; do glab issue create …; done` and `{ glab issue create …; }`
+ * were allowed with NO accounting at all, while the plain form denied at 1/1.
+ *
  * The newline separator is checked by its `operator` field as well as its text,
  * so the split survives a future change to that token's spelling. Because a
  * separator token is CONSUMED here, it can never reach a per-segment operand
@@ -678,6 +723,13 @@ function splitSegments(tokens) {
       current = [];
       continue;
     }
+    // Reserved word in COMMAND POSITION (`current` still empty) → drop it, so
+    // the NEXT token becomes the segment head and is itself judged in command
+    // position (`do { rm …` peels both). A keyword anywhere else is an ordinary
+    // argument and is kept verbatim (#1145).
+    if (current.length === 0 && !tok.quoted && COMMAND_POSITION_KEYWORDS.has(tok.text)) {
+      continue;
+    }
     current.push(tok);
   }
   segments.push(current);
@@ -763,6 +815,24 @@ export const WRAPPER_UNWRAP = new Map([
   }],
   ['command', {}],
   ['nohup', {}],
+  // `exec cmd args` REPLACES the shell with `cmd` — it delegates to a real verb
+  // and never executes a command STRING, so by the #982 classification it is a
+  // TRANSPARENT wrapper, not an interpreter (contrast `su -c`, which is in
+  // SHELL_EXEC_INTERPRETERS for exactly the opposite reason). `-a NAME` is the
+  // one value-taking flag; `-c` (clear environment) and `-l` are BOOLEANS here
+  // — despite the spelling, `exec -c` carries no payload, so it must NOT reach
+  // DASH_C_SHELLS, and it does not: that set is keyed on the RESOLVED verb.
+  // Redirect-only `exec > file` keeps working. Measured both namespaces: on the
+  // RAW segment the wrapper consumes `exec` and the redirect operator resolves
+  // as the verb (`>`, previously `exec`); on scope-gate's paren-peeled,
+  // redirect-stripped projection the segment exhausts in wrappers and yields
+  // `verb: null, index: -1` — the shape a bare `sudo` already produced. Neither
+  // is `rm`/`tee`/`sed`/`dd`, and a redirect target is read from the redirect
+  // token stream rather than from the verb, so detection is unaffected:
+  // measured `extractBashWriteTargets('exec > src/out.ts')` → `['src/out.ts']`.
+  ['exec', {
+    argFlags: new Set(['-a']),
+  }],
   // `-o FILE` is the BSD/GNU `time` report destination and it TRUNCATES without
   // `-a` (BSD time(1): "If file exists and the -a flag is not specified, the
   // file will be overwritten"). With an empty spec the operand was read as the

package/scripts/lib/config/dispatcher-autonomy-capture.mjs

@@ -43,13 +43,36 @@ import { hasBlockHeader } from './block-header.mjs';
 const ALLOWED_AUTONOMY = ['off', 'advisory', 'autonomous-gated'];
 const DEFAULT_CONFIDENCE_FLOOR = 0.5;
 
+/**
+ * The display-only tail of an option LABEL, stripped before the enum match.
+ *
+ * The label and the stored value were the SAME string, which made the label
+ * unchangeable: both consumers (`skills/session-start/SKILL.md` Phase 1.1 and
+ * `skills/bootstrap/SKILL.md` Phase 3.5.1) hand the SELECTED LABEL straight to
+ * writeDispatcherAutonomyBlock(), and coerceAutonomy() falls back to 'off' on
+ * any value outside the enum. Putting AUQ-003's `(Recommended)` marker into the
+ * label would therefore have written `autonomy: off` for an operator who picked
+ * `advisory` — a silent downgrade, fail-closed and therefore invisible.
+ *
+ * Measured before this split (renderDispatcherAutonomyBlock, 2026-08-22):
+ *   'advisory'                => autonomy: advisory
+ *   'Advisory (surface only)' => autonomy: off      ← the downgrade
+ *
+ * Anchored at the end, so it can only ever strip a suffix. The enum values
+ * themselves are untouched and stay greppable.
+ */
+const RECOMMENDED_SUFFIX = /\s*\((?:Recommended|Empfohlen|Default)\)\s*$/u;
+
 /**
  * Coordinator-facing AUQ question definition for the one-time capture.
  * Mirrors the shape of `getInterviewQuestions()` entries in owner-interview.mjs:
  *   { question, header, options: [{ label, description }], multiSelect }
  *
- * Option labels match the ALLOWED_AUTONOMY enum so the selected label maps
- * directly to the `autonomy` value passed to writeDispatcherAutonomyBlock().
+ * Each label BEGINS with its ALLOWED_AUTONOMY value; option 1 additionally
+ * carries the `(Recommended)` marker AUQ-003 puts in the label. `coerceAutonomy()`
+ * strips that marker, so the selected label still maps to the enum value written
+ * by writeDispatcherAutonomyBlock() — see the comment on RECOMMENDED_SUFFIX for
+ * why the two halves must not be the same string.
  * Option 1 (`off`) is the recommended, fail-closed default.
  *
  * @returns {{ question: string, header: string, options: Array<{ label: string, description: string }>, multiSelect: boolean }}
@@ -57,23 +80,23 @@ const DEFAULT_CONFIDENCE_FLOOR = 0.5;
 export function getDispatcherAutonomyQuestion() {
   return {
     question:
-      'Cross-repo dispatcher autonomy: how should this repo participate when the free-repo dispatcher routes work to it?',
-    header: 'Dispatcher Autonomy (one-time)',
+      'When /dispatcher looks across your repos for the next one to work on, how may it treat this repo?',
+    header: 'Dispatcher',
     options: [
       {
-        label: 'off',
+        label: 'off (Recommended)',
         description:
-          '(Recommended) Fail-closed. The dispatcher never routes work to this repo automatically. No behaviour change.',
+          'Nothing changes: this repo is never offered and never started for you. Safe default — you keep picking the work.',
       },
       {
         label: 'advisory',
         description:
-          'The dispatcher surfaces ranked free-repo candidates for operator review — no automated dispatch.',
+          'This repo may appear in the ranked suggestions, so you can compare it against the others. You still start each session.',
       },
       {
         label: 'autonomous-gated',
         description:
-          'A deterministic confidence gate is checked first; only dispatches that clear the confidence-floor route automatically.',
+          'Work may start here without asking, but only when the ranking beats the confidence floor written next to this setting.',
       },
     ],
     multiSelect: false,
@@ -128,7 +151,7 @@ export function isDispatcherAutonomyBlockPresent(claudeMdContent) {
  */
 function coerceAutonomy(value) {
   if (value === null || value === undefined) return 'off';
-  const normalized = String(value).toLowerCase().trim();
+  const normalized = String(value).toLowerCase().replace(RECOMMENDED_SUFFIX, '').trim();
   return ALLOWED_AUTONOMY.includes(normalized) ? normalized : 'off';
 }