forgedock 1.12.0 → 1.13.0

package/bin/runner.mjs

@@ -263,6 +263,83 @@ export function resolveConfiguredCliTimeout(cwd) {
   }
 }
 
+/**
+ * Derive the flat forge.yaml key stem for a runner command name (forge#3589).
+ * `parseForgeYaml` only supports `section:` + one nested `key: scalar` level,
+ * so per-command settings live flat under `engine:` as `<stem>_model` /
+ * `<stem>_max_turns`, where the stem is the command name with every
+ * non-alphanumeric character replaced by `_`
+ * (`review-pr-staging` -> `review_pr_staging`, `work-on/review` -> `work_on_review`).
+ * The single derivation shared by the resolver, docs, and tests.
+ *
+ * @param {string} commandName
+ * @returns {string}
+ */
+export function engineConfigKey(commandName) {
+  return String(commandName ?? "").replace(/[^A-Za-z0-9]/g, "_");
+}
+
+// A model value reaches argv as a discrete element (no shell), but is still
+// restricted to the characters real model ids/aliases use.
+const CLI_MODEL_PATTERN = /^[A-Za-z0-9._:[\]-]+$/;
+
+/**
+ * Validate a model string destined for `--model`. Returns the trimmed value,
+ * or `null` when absent/invalid (never forwarded).
+ *
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+export function sanitizeCliModel(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 && trimmed.length <= 128 && CLI_MODEL_PATTERN.test(trimmed)
+    ? trimmed
+    : null;
+}
+
+/**
+ * Validate a turn bound destined for `--max-turns`: a positive integer (number
+ * or all-digit string), else `null`.
+ *
+ * @param {unknown} value
+ * @returns {number|null}
+ */
+export function sanitizeMaxTurns(value) {
+  if (typeof value === "string" && !/^\d{1,6}$/.test(value.trim())) return null;
+  const n = typeof value === "string" ? Number(value.trim()) : value;
+  return Number.isSafeInteger(n) && n > 0 ? n : null;
+}
+
+/**
+ * Resolve per-command CLI settings from forge.yaml's flat
+ * `engine.<stem>_model` / `engine.<stem>_max_turns` keys (forge#3589), where
+ * `<stem>` comes from `engineConfigKey(commandName)`. Opt-in: with no config
+ * both fields are `null`. Fail-soft on any read/parse error. Invalid values
+ * are dropped (never forwarded to argv).
+ *
+ * @param {string} cwd
+ * @param {string} commandName
+ * @returns {{model: string|null, maxTurns: number|null}}
+ */
+export function resolveCommandEngineSettings(cwd, commandName) {
+  const none = { model: null, maxTurns: null };
+  try {
+    const forgeYamlPath = join(cwd, "forge.yaml");
+    if (!existsSync(forgeYamlPath)) return none;
+    const engine = parseForgeYaml(readFileSync(forgeYamlPath, "utf-8"))?.engine;
+    if (!engine || typeof engine !== "object") return none;
+    const stem = engineConfigKey(commandName);
+    if (!stem) return none;
+    return {
+      model: sanitizeCliModel(resolveModelAlias(engine[`${stem}_model`])),
+      maxTurns: sanitizeMaxTurns(engine[`${stem}_max_turns`]),
+    };
+  } catch {
+    return none;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Backend selection (issue #2003) — CLI vs API execution backend
 // ---------------------------------------------------------------------------
@@ -442,6 +519,7 @@ export function isClaudeCliAvailable(
   const resolveCmd = process.platform === "win32" ? "where claude" : "command -v claude";
   let available;
   let cliPath = null;
+  let version = null;
   try {
     const raw = execImpl(
       `${resolveCmd} && echo ${CLI_PROBE_OUTPUT_SENTINEL} && claude --version`,
@@ -454,6 +532,7 @@ export function isClaudeCliAvailable(
     );
     available = true;
     cliPath = selectResolvedCliPath(parseProbeOutput(raw), { platform, existsImpl });
+    version = parseCliVersion(raw);
   } catch {
     available = false;
   }
@@ -462,7 +541,7 @@ export function isClaudeCliAvailable(
   // entry — whether "oldest" means "never refreshed" or "not refreshed in
   // the longest time."
   cliAvailabilityCache.delete(cwd);
-  cliAvailabilityCache.set(cwd, { available, cliPath, cachedAt: Date.now() });
+  cliAvailabilityCache.set(cwd, { available, cliPath, version, cachedAt: Date.now() });
   if (cliAvailabilityCache.size > CLI_AVAILABILITY_CACHE_MAX_SIZE) {
     const oldestKey = cliAvailabilityCache.keys().next().value;
     cliAvailabilityCache.delete(oldestKey);
@@ -470,6 +549,53 @@ export function isClaudeCliAvailable(
   return available;
 }
 
+// Minimum `claude` CLI versions that accept the print-mode flags (forge#3589).
+// `--max-turns` is intentionally absent from `claude --help`, so support is
+// gated on the cached `claude --version` probe, never on help-text scraping.
+const CLI_MIN_VERSION_MODEL_FLAG = [1, 0, 0];
+const CLI_MIN_VERSION_MAX_TURNS_FLAG = [1, 0, 0];
+
+/**
+ * Extract a `major.minor.patch` version from probe output (the text after the
+ * probe sentinel when present, else the whole string). Bounded, linear regex.
+ *
+ * @param {string} raw
+ * @returns {number[]|null}
+ */
+export function parseCliVersion(raw) {
+  const text = String(raw ?? "");
+  const idx = text.indexOf(CLI_PROBE_OUTPUT_SENTINEL);
+  const tail = idx >= 0 ? text.slice(idx + CLI_PROBE_OUTPUT_SENTINEL.length) : text;
+  const m = /(\d{1,4})\.(\d{1,4})\.(\d{1,4})/.exec(tail.slice(0, 512));
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+function versionAtLeast(version, min) {
+  if (!Array.isArray(version)) return false;
+  for (let i = 0; i < 3; i++) {
+    if (version[i] !== min[i]) return version[i] > min[i];
+  }
+  return true;
+}
+
+/**
+ * Which print-mode flags the installed `claude` CLI supports, derived from the
+ * cached `--version` probe. Unparseable version or unavailable CLI means
+ * unsupported (flags omitted).
+ *
+ * @param {string} [cwd]
+ * @param {object} [opts] - Forwarded to `isClaudeCliAvailable()` (test seams).
+ * @returns {{model: boolean, maxTurns: boolean}}
+ */
+export function getClaudeCliCapabilities(cwd = process.cwd(), opts = {}) {
+  isClaudeCliAvailable(cwd, opts);
+  const version = cliAvailabilityCache.get(cwd)?.version ?? null;
+  return {
+    model: versionAtLeast(version, CLI_MIN_VERSION_MODEL_FLAG),
+    maxTurns: versionAtLeast(version, CLI_MIN_VERSION_MAX_TURNS_FLAG),
+  };
+}
+
 /**
  * Return the exact absolute `claude` executable path that
  * `isClaudeCliAvailable()` validated for `cwd` (issue #2741), ensuring the
@@ -935,13 +1061,40 @@ export function sanitizeOutputExcerptForLog(output) {
 
 // Shared usage-limit phrasing: detection and reset extraction must agree on it.
 const USAGE_LIMIT_PHRASE = "(?:session|weekly|usage) limit";
-const USAGE_LIMIT_RE = new RegExp(USAGE_LIMIT_PHRASE, "i");
 // `... limit · resets 3pm (Asia/Kolkata)` — capture stops at the zone's `)`.
 const USAGE_LIMIT_RESET_PAREN_RE = new RegExp(
   `${USAGE_LIMIT_PHRASE}[^\\n"]*?resets?\\s+([^\\n"]+?\\))`, "i");
 // Zone-less fallback: capture to end of line, but never across a quote.
 const USAGE_LIMIT_RESET_LINE_RE = new RegExp(
   `${USAGE_LIMIT_PHRASE}[^\\n"]*?resets?\\s+([^\\n"]+?)\\s*$`, "im");
+// The two regexes above are polynomial on long no-match lines, so they only
+// ever run on a short window per phrase hit (untrusted input can be tens of MB).
+const USAGE_LIMIT_SCAN_WINDOW_CHARS = 512;
+const USAGE_LIMIT_MAX_PHRASE_HITS = 32;
+
+/** Linear scan for phrase hits; returns at most MAX_PHRASE_HITS newline-cut windows. */
+function collectUsageLimitWindows(source) {
+  const windows = [];
+  const phraseRe = new RegExp(USAGE_LIMIT_PHRASE, "gi");
+  let hit;
+  while (windows.length < USAGE_LIMIT_MAX_PHRASE_HITS && (hit = phraseRe.exec(source)) !== null) {
+    let window = source.slice(hit.index, hit.index + USAGE_LIMIT_SCAN_WINDOW_CHARS);
+    const nl = window.indexOf("\n");
+    if (nl !== -1) window = window.slice(0, nl);
+    windows.push(window);
+  }
+  return windows;
+}
+
+/**
+ * True when `text` holds a `limit ... resets ...` clause (the shape the reset
+ * extractor needs). Only bounded windows reach the polynomial regexes (#3522).
+ */
+function hasUsageLimitResetClause(text) {
+  if (typeof text !== "string") return false;
+  return collectUsageLimitWindows(text).some(
+    (w) => USAGE_LIMIT_RESET_PAREN_RE.test(w) || USAGE_LIMIT_RESET_LINE_RE.test(w));
+}
 
 /**
  * Parses a `claude --output-format json` single-result envelope from `text`.
@@ -962,9 +1115,13 @@ function parseCliEnvelope(text) {
 
 /**
  * Detects whether a failed CLI run was a Claude usage/session/weekly limit.
- * Prefers the envelope's structured fields (`api_error: "usage_limit_reached"`,
- * `api_error_status: 429`), then the envelope's `result` text, then the plain
- * combined output. `stdout` is parsed ALONE (forge#2422 invariant); never throws.
+ * Deliberately narrow (forge#3523): the envelope's `api_error` must be
+ * `"usage_limit_reached"`, or the envelope must be `is_error: true` with a
+ * `result` carrying a full `limit ... resets ...` clause, or (no envelope) the
+ * plain combined output must carry that same clause. A bare HTTP 429 (a
+ * transient rate limit) or a keyword-only mention is NOT a usage limit; a limit
+ * with neither signal is treated as an ordinary failure. `stdout` is parsed
+ * ALONE (forge#2422 invariant); never throws.
  *
  * @param {string} stdout - raw stdout of the CLI run
  * @param {string} [output] - combined stdout+stderr, for the plain-text fallback
@@ -973,11 +1130,10 @@ function parseCliEnvelope(text) {
 export function detectUsageLimit(stdout, output = "") {
   const env = parseCliEnvelope(stdout);
   if (env) {
-    if (env.api_error === "usage_limit_reached" || env.api_error_status === 429) return true;
-    if (typeof env.result === "string" && USAGE_LIMIT_RE.test(env.result)) return true;
-    return false;
+    if (env.api_error === "usage_limit_reached") return true;
+    return env.is_error === true && hasUsageLimitResetClause(env.result);
   }
-  return USAGE_LIMIT_RE.test(output || "") && /resets?\s/i.test(output || "");
+  return hasUsageLimitResetClause(output || "");
 }
 
 /**
@@ -1006,8 +1162,12 @@ export function extractSessionLimitResetTime(output) {
   // JSON-wrapped message cannot swallow the trailing `","type":...` fields.
   const text = parseCliEnvelope(output)?.result ?? output;
   const source = typeof text === "string" ? text : output;
-  const match =
-    USAGE_LIMIT_RESET_PAREN_RE.exec(source) ?? USAGE_LIMIT_RESET_LINE_RE.exec(source);
+  const windows = collectUsageLimitWindows(source);
+  let match = null;
+  for (const w of windows) { if ((match = USAGE_LIMIT_RESET_PAREN_RE.exec(w))) break; }
+  if (!match) {
+    for (const w of windows) { if ((match = USAGE_LIMIT_RESET_LINE_RE.exec(w))) break; }
+  }
   if (!match) return undefined;
   const resetAt = match[1].trim();
   if (resetAt.length === 0) return undefined;
@@ -1163,7 +1323,17 @@ export function runCliBackend({
   logger = console,
   bin = "claude",
   spawnFn = spawnSync,
+  model = null,
+  maxTurns = null,
 }) {
+  // forge#3589: opt-in flags, validated again here as defence in depth. Callers
+  // (runCommand) are responsible for the version gate. Unset -> argv unchanged.
+  const modelFlag = sanitizeCliModel(model);
+  const maxTurnsFlag = sanitizeMaxTurns(maxTurns);
+  const optionalFlags = [
+    ...(modelFlag ? ["--model", modelFlag] : []),
+    ...(maxTurnsFlag ? ["--max-turns", String(maxTurnsFlag)] : []),
+  ];
   const rawTimeout = parseInt(process.env.FORGEDOCK_CLI_TIMEOUT_MS, 10);
   const configuredTimeout = resolveConfiguredCliTimeout(cwd);
   const timeoutMs = Number.isFinite(rawTimeout) && rawTimeout > 0
@@ -1190,6 +1360,7 @@ export function runCliBackend({
     userMessage,
     "--output-format",
     "json",
+    ...optionalFlags,
     "--dangerously-skip-permissions",
   ];
 
@@ -1204,6 +1375,7 @@ export function runCliBackend({
         userMessage,
         "--output-format",
         "json",
+        ...optionalFlags,
         "--append-system-prompt-file",
         systemPromptPath,
         "--dangerously-skip-permissions",
@@ -1275,6 +1447,41 @@ export function runCliBackend({
 
     const output = (stdout + stderr).trim();
 
+    // forge#3589: turn-limit exhaustion arrives as a JSON envelope with
+    // `subtype: "error_max_turns"`, possibly on a non-zero exit. Detect it from
+    // the parsed stdout alone (no regex over output, #3522/#2422) on BOTH exit
+    // paths, before the generic non-zero classification below, so callers can
+    // tell it apart from a crash and resume the same phase.
+    let maxTurnsEnvelope = null;
+    try {
+      const parsedEnvelope = JSON.parse(stdout.trim());
+      if (parsedEnvelope && typeof parsedEnvelope === "object") maxTurnsEnvelope = parsedEnvelope;
+    } catch {
+      // Non-JSON stdout: not a max-turns envelope.
+    }
+    if (maxTurnsEnvelope?.subtype === "error_max_turns") {
+      const numTurns = Number.isFinite(maxTurnsEnvelope.num_turns) ? maxTurnsEnvelope.num_turns : null;
+      const err = new Error(
+        `claude CLI stopped at the --max-turns limit` +
+          (maxTurnsFlag ? ` (${maxTurnsFlag})` : "") +
+          (numTurns !== null ? ` after ${numTurns} turns` : "") +
+          `. Raise the engine max_turns setting and re-run (--retry resumes this phase).`,
+      );
+      err.code = "CLI_MAX_TURNS";
+      err.numTurns = numTurns;
+      const u = maxTurnsEnvelope.usage;
+      err.usage =
+        u && typeof u === "object"
+          ? {
+              input_tokens: toFiniteUsageNumber(u.input_tokens),
+              output_tokens: toFiniteUsageNumber(u.output_tokens),
+              cache_creation_input_tokens: toFiniteUsageNumber(u.cache_creation_input_tokens),
+              cache_read_input_tokens: toFiniteUsageNumber(u.cache_read_input_tokens),
+            }
+          : null;
+      throw err;
+    }
+
     if (result.status !== 0) {
       // Non-zero exit: always emit a self-contained diagnostic, regardless of
       // whether stdout/stderr captured anything. Previously this branch threw
@@ -1324,13 +1531,18 @@ export function runCliBackend({
       // quota-exhaustion failure will clear without reading raw logs. Only
       // ever set when the pattern actually matches — never fabricated.
       // The reset text is read from stdout's parsed envelope first (stdout
-      // ALONE, forge#2422), then from the combined output.
-      const resetAt =
-        extractSessionLimitResetTime(stdout) ?? extractSessionLimitResetTime(output);
+      // ALONE, forge#2422), then from the combined output. Gated on the same
+      // narrowed predicate as `usageLimit` (forge#3523): the engine pauses on
+      // `resetAtEpochMs` alone, so a bare 429 or keyword-only failure whose
+      // output happens to contain a reset clause must not carry one either.
+      const isUsageLimit = detectUsageLimit(stdout, output);
+      const resetAt = isUsageLimit
+        ? extractSessionLimitResetTime(stdout) ?? extractSessionLimitResetTime(output)
+        : undefined;
       // Structured usage-limit flag: lets the engine pause by a bounded
       // default when the reset time itself is missing or unparseable. The
       // engine, not the runner, owns that default — no epoch is fabricated here.
-      if (detectUsageLimit(stdout, output)) err.usageLimit = true;
+      if (isUsageLimit) err.usageLimit = true;
       if (resetAt) {
         err.resetAt = resetAt;
         // forge#2524: also attach a machine-usable epoch-ms timestamp so
@@ -1377,9 +1589,11 @@ export function runCliBackend({
     const stdoutTrimmed = stdout.trim();
     let parsedResult = null;
     let usage = null;
+    let turns = null;
     try {
       const parsed = JSON.parse(stdoutTrimmed);
       if (parsed && typeof parsed === "object") {
+        if (Number.isFinite(parsed.num_turns)) turns = parsed.num_turns;
         parsedResult = typeof parsed.result === "string" ? parsed.result : null;
         if (parsed.usage && typeof parsed.usage === "object") {
           usage = {
@@ -1460,6 +1674,10 @@ export function runCliBackend({
       stopReason: "cli_exit_0",
       usage,
       model: "cli",
+      // forge#3589: additive — the model forced via --model (null = CLI default)
+      // and the envelope's turn count (null when absent), for runlog recording.
+      cliModel: modelFlag,
+      turns,
       backend: "cli",
       // forge#3521: the phase's final reply (the CLI envelope's `.result`), so
       // callers can read its structured `*_RESULT` block. Additive; "" when absent.
@@ -2297,25 +2515,24 @@ export async function runCommand(opts = {}) {
       );
     }
 
-    // model/maxIterations only apply to the api backend — the cli backend
-    // uses whatever model the `claude` CLI itself is configured for, and has
-    // no equivalent iteration-cap concept for a single `claude --print`
-    // invocation. Warn (rather than silently drop) when the caller explicitly
-    // supplied either, so the behavior is discoverable outside of --dry-run.
+    // maxIterations only applies to the api backend — a single `claude --print`
+    // invocation has no iteration-cap concept (it is NOT `--max-turns`; see the
+    // per-command settings below). `model` is forwarded as `--model` (forge#3589).
+    // Warn (rather than silently drop) when the caller explicitly supplied
+    // maxIterations, so the behavior is discoverable outside of --dry-run.
     // hasOwnProperty on the raw opts (not the destructured, default-applied
     // values above) is required here: model/maxIterations always resolve to
     // a computed default, so checking their truthiness would fire this
     // warning on every single cli-backend run.
     const ignoredOptions = [];
-    if (Object.prototype.hasOwnProperty.call(opts, "model")) ignoredOptions.push("model");
     if (Object.prototype.hasOwnProperty.call(opts, "maxIterations"))
       ignoredOptions.push("maxIterations");
     if (ignoredOptions.length > 0) {
       logger.log(
         `Warning: --${ignoredOptions.join(" and --")} ${
           ignoredOptions.length > 1 ? "are" : "is"
-        } ignored on the cli backend (backend: cli uses whatever model the ` +
-          `claude CLI itself is configured for). Use --backend api to honor ${
+        } ignored on the cli backend (a single claude --print has no iteration cap). ` +
+          `Use --backend api to honor ${
             ignoredOptions.length > 1 ? "these options" : "this option"
           }.`,
       );
@@ -2327,6 +2544,22 @@ export async function runCommand(opts = {}) {
     // (e.g. an injected-execImpl test scenario with no path-like output),
     // preserving prior behavior in that edge case.
     const resolvedBin = resolveClaudeCliBinary(cwd);
+    // forge#3589: per-command CLI settings. Precedence: forge.yaml
+    // engine.<stem>_model (most specific), then the run-level model the caller
+    // explicitly supplied (opts.model, e.g. the engine's --model), else omit (the CLI's own default; no behaviour change).
+    // max_turns comes from config only. Flags are forwarded only when the
+    // installed CLI version supports them.
+    const commandSettings = resolveCommandEngineSettings(cwd, commandName);
+    const runLevelModel = Object.prototype.hasOwnProperty.call(opts, "model")
+      ? sanitizeCliModel(resolveModelAlias(opts.model))
+      : null;
+    let cliModel = commandSettings.model ?? runLevelModel;
+    let cliMaxTurns = commandSettings.maxTurns;
+    if (resolvedBin && (cliModel || cliMaxTurns)) {
+      const caps = getClaudeCliCapabilities(cwd);
+      if (cliModel && !caps.model) cliModel = null;
+      if (cliMaxTurns && !caps.maxTurns) cliMaxTurns = null;
+    }
     if (!resolvedBin && backend === "auto") {
       resolvedBackend = "api";
     } else if (!resolvedBin) {
@@ -2345,6 +2578,8 @@ export async function runCommand(opts = {}) {
           args,
           cwd,
           logger,
+          model: cliModel,
+          maxTurns: cliMaxTurns,
         },
       });
     }

package/bin/watch-utils.mjs

@@ -25,6 +25,7 @@ export const FALLBACK_WORKFLOW_LABELS = [
   "workflow:ready-to-build",
   "workflow:building",
   "workflow:in-review",
+  "workflow:remediating",
   "needs-human",
 ];
 

package/commands/autopilot.md

@@ -228,9 +228,9 @@ INFLIGHT_ISSUES=$(gh issue list $GH_FLAG \
   --state open \
   --limit 200 \
   --json number,title,labels \
-  --jq '[.[] | select(.labels | map(.name) | any(. == "workflow:building" or . == "workflow:in-review"))] | length' \
+  --jq '[.[] | select(.labels | map(.name) | any(. == "workflow:building" or . == "workflow:in-review" or . == "workflow:remediating"))] | length' \
   2>/dev/null || echo '0')
-echo "STATE: $INFLIGHT_ISSUES in-flight issue(s) (workflow:building or workflow:in-review)"
+echo "STATE: $INFLIGHT_ISSUES in-flight issue(s) (workflow:building, workflow:in-review, or workflow:remediating)"
 ```
 
 ### 0D: Detect staging vs main delta
@@ -725,7 +725,7 @@ while true; do
         --json number,milestone,labels \
         --jq '[.[] | select(
           .milestone == null and
-          (.labels | map(.name) | any(. == "workflow:merged" or . == "workflow:invalid" or . == "workflow:decomposed" or . == "needs-human") | not)
+          (.labels | map(.name) | any(. == "workflow:merged" or . == "workflow:invalid" or . == "workflow:decomposed" or . == "workflow:remediating" or . == "needs-human") | not)
         )] | .[].number' \
         2>/dev/null || echo '')
 
@@ -855,7 +855,7 @@ To approve: remove \`needs-human\` label from #${ISSUE_NUM} and re-run \`/autopi
         --json number,milestone,labels \
         --jq '[.[] | select(
           .milestone == null and
-          (.labels | map(.name) | any(. == "workflow:merged" or . == "workflow:invalid" or . == "workflow:decomposed" or . == "needs-human") | not)
+          (.labels | map(.name) | any(. == "workflow:merged" or . == "workflow:invalid" or . == "workflow:decomposed" or . == "workflow:remediating" or . == "needs-human") | not)
         )] | .[].number' \
         2>/dev/null || echo '')
       for N in $PRE_DISPATCH_ISSUES; do DISPATCHED_ISSUES+=("$N"); done
@@ -1005,7 +1005,7 @@ while IFS= read -r milestone; do
           '[.[] | select(
             .milestone != null and
             (.milestone.title | ascii_downcase | gsub("[^a-z0-9]+"; "-") | ltrimstr("-") | rtrimstr("-")) == $slug and
-            (.labels | map(.name) | any(. == "workflow:merged" or . == "workflow:invalid" or . == "workflow:decomposed" or . == "needs-human") | not)
+            (.labels | map(.name) | any(. == "workflow:merged" or . == "workflow:invalid" or . == "workflow:decomposed" or . == "workflow:remediating" or . == "needs-human") | not)
           )] | .[].number' \
           2>/dev/null || echo '')
 
@@ -1109,7 +1109,7 @@ To approve: remove \`needs-human\` label from #${ISSUE_NUM} and re-run \`/autopi
           '[.[] | select(
             .milestone != null and
             (.milestone.title | ascii_downcase | gsub("[^a-z0-9]+"; "-") | ltrimstr("-") | rtrimstr("-")) == $slug and
-            (.labels | map(.name) | any(. == "workflow:merged" or . == "workflow:invalid" or . == "workflow:decomposed" or . == "needs-human") | not)
+            (.labels | map(.name) | any(. == "workflow:merged" or . == "workflow:invalid" or . == "workflow:decomposed" or . == "workflow:remediating" or . == "needs-human") | not)
           )] | .[].number' \
           2>/dev/null || echo '')
         for N in $MS_PRE_DISPATCH; do DISPATCHED_ISSUES+=("$N"); done

package/commands/cleanup.md

@@ -71,6 +71,9 @@ gh issue list {GH_FLAG} --state closed --label "workflow:building" --limit 100 -
 echo "=== Stale workflow:awaiting-merge ==="
 gh issue list {GH_FLAG} --state closed --label "workflow:awaiting-merge" --limit 100 --json number,title --jq '.[] | "#\(.number) — \(.title)"'
 
+echo "=== Stale workflow:remediating ==="
+gh issue list {GH_FLAG} --state closed --label "workflow:remediating" --limit 100 --json number,title --jq '.[] | "#\(.number) — \(.title)"'
+
 echo "=== Stale workflow:investigating ==="
 gh issue list {GH_FLAG} --state closed --label "workflow:investigating" --limit 100 --json number,title --jq '.[] | "#\(.number) — \(.title)"'
 
@@ -82,11 +85,11 @@ gh issue list {GH_FLAG} --state closed --label "needs-validation" --limit 100 --
 
 For each closed issue with a stale intermediate label:
 
-**Stale `workflow:in-review`, `workflow:building`, `workflow:awaiting-merge`** — these were merged but label wasn't updated:
+**Stale `workflow:in-review`, `workflow:building`, `workflow:awaiting-merge`, `workflow:remediating`** — these were merged but label wasn't updated:
 ```bash
 for NUM in {stale_issue_numbers}; do
   gh issue edit $NUM {GH_FLAG} --add-label "workflow:merged"
-  gh issue edit $NUM {GH_FLAG} --remove-label "workflow:in-review,workflow:building,workflow:awaiting-merge,needs-validation" 2>/dev/null || true
+  gh issue edit $NUM {GH_FLAG} --remove-label "workflow:in-review,workflow:building,workflow:awaiting-merge,workflow:remediating,needs-validation" 2>/dev/null || true # allowlist:check-command-side-effects
 done
 ```
 
@@ -159,7 +162,7 @@ These were closed outside the pipeline. Report count but don't fix (not necessar
 
 ### 1D: Detect stale OPEN issues in intermediate workflow states
 
-Open issues stuck in `workflow:building`, `workflow:in-review`, or `workflow:investigating` beyond a configurable threshold indicate a stalled agent. These are invisible to Phase 1A–1C (which only query closed issues).
+Open issues stuck in `workflow:building`, `workflow:in-review`, `workflow:remediating`, or `workflow:investigating` beyond a configurable threshold indicate a stalled agent. These are invisible to Phase 1A–1C (which only query closed issues).
 
 ```bash
 # Configurable threshold — override by setting STALE_THRESHOLD_HOURS before invoking /cleanup
@@ -174,7 +177,7 @@ echo "=== Stale-Open Intermediate Issues (threshold: ${STALE_THRESHOLD_HOURS}h)
 
 STALE_OPEN_COUNT=0
 
-for LABEL in "workflow:building" "workflow:in-review" "workflow:investigating"; do
+for LABEL in "workflow:building" "workflow:in-review" "workflow:remediating" "workflow:investigating"; do
   ISSUES=$(gh issue list {GH_FLAG} \
     --state open \
     --label "$LABEL" \
@@ -226,7 +229,7 @@ For each orphaned issue found:
 ```bash
 gh issue close $NUM {GH_FLAG} --comment "Closed by cleanup — PR #$MERGED_PR was already merged."
 gh issue edit $NUM {GH_FLAG} --add-label "workflow:merged"
-gh issue edit $NUM {GH_FLAG} --remove-label "workflow:in-review,workflow:awaiting-merge" 2>/dev/null || true
+gh issue edit $NUM {GH_FLAG} --remove-label "workflow:in-review,workflow:remediating,workflow:awaiting-merge" 2>/dev/null || true # allowlist:check-command-side-effects
 ```
 
 Also check open issues with `workflow:building` — same pattern (search for merged PRs referencing them).

package/commands/orchestrate/phase-1-resolve.md

@@ -281,7 +281,7 @@ Remove issues that should NOT be worked on:
 - Has `workflow:invalid` label
 - Has `needs-human` label (requires manual action)
 - Has `workflow:decomposed` label (parent tracker — its sub-issues should be picked up instead)
-- Has `workflow:building` or `workflow:in-review` label (already in progress)
+- Has `workflow:building`, `workflow:in-review`, or `workflow:remediating` label (already in progress; `workflow:remediating` is a review-handoff state awaiting a remediation worker)
 - Is an epic (`epic` label) — these are planning containers, not buildable
 
 If a `workflow:decomposed` issue is found, automatically expand it to its open sub-issues instead.

package/commands/orchestrate/phase-3-dependency.md

@@ -83,27 +83,22 @@ declare -A EDGE_FILES   # "{PRED}:{SUCCESSOR}" → the specific file(s) that tri
 declare -A FILE_SOURCE  # {NUM} → contract-deliverables | affected-files-section | body-fallback | none (forge#2436, forge#2848)
 declare -A ISSUE_FILES  # {NUM} → newline-separated declared file set (forge#2844)
 
-# Resolve ForgeDock's helper from the runtime installation before falling back to
-# the target repository. The orchestrator runs inside the project being worked on,
-# so a bare `scripts/extract-affected-files.sh` silently fails when that project
-# has not copied ForgeDock's helper scripts into its own repository (observed in
-# OpenCode runs against installed ForgeDock). Keep the precedence aligned with
-# phase-4-execution.md's classify-lane resolver.
+# Resolve ForgeDock's helper from a trusted ForgeDock install only (same tiers as the
+# TRUSTED_SCRIPT resolver). The orchestrator runs inside the project being worked on, so
+# neither the working directory nor the target repo may supply the script (#3400/#3483),
+# and a bare `scripts/extract-affected-files.sh` would silently fail on consumer repos.
 resolve_extract_affected_files() {
-  local candidates=()
-  case '${CLAUDE_PLUGIN_ROOT}' in /*) candidates+=('${CLAUDE_PLUGIN_ROOT}/scripts/extract-affected-files.sh') ;; esac  # running plugin first
-  [ -n "${FORGE_HOME:-}" ] && candidates+=("$FORGE_HOME/scripts/extract-affected-files.sh")
-  [ -n "${REPO_PATH:-}" ] && candidates+=("$REPO_PATH/scripts/extract-affected-files.sh")
-  candidates+=("$PWD/scripts/extract-affected-files.sh")
-
-  local candidate
-  for candidate in "${candidates[@]}"; do
-    if [ -f "$candidate" ]; then
-      printf '%s\n' "$candidate"
-      return 0
-    fi
+  # HELPER_SCRIPT resolver (EXTRACT_SCRIPT; trusted-install tiers only, never the working directory or the target repo, #3400/#3483): plugin root, FORGE_ROOT, FORGEDOCK_HOME, FORGE_HOME, install symlink, marketplaces, newest pinned plugin cache under CLAUDE_CONFIG_DIR then ~/.claude.
+  local _l _tc _cfg _c
+  _l="$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null || true)"; _l="${_l%/commands/work-on.md}"
+  _tc="$(printf '%s\n' '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGEDOCK_HOME:-}" "${FORGE_HOME:-}" "$_l" "$HOME/.claude/plugins/marketplaces/forgedock")"
+  for _cfg in "${CLAUDE_CONFIG_DIR:-}" "$HOME/.claude"; do
+    [ -n "$_cfg" ] && _tc="$_tc"$'\n'"$(find -L "$_cfg/plugins/cache/forgedock/forgedock" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | awk -F/ '$NF ~ /^[0-9]+\.[0-9]+\.[0-9]+$/{split($NF,a,".");printf "%d %d %d %s\n",a[1],a[2],a[3],$(0)}' | sort -k1,1nr -k2,2nr -k3,3nr | cut -d' ' -f4- || true)"
   done
-  echo "ERROR: extract-affected-files.sh is not installed in any configured runtime path." >&2
+  while IFS= read -r _c; do
+    case "$_c" in /*) if [ -f "$_c/scripts/extract-affected-files.sh" ]; then printf '%s\n' "$_c/scripts/extract-affected-files.sh"; return 0; fi ;; esac
+  done <<< "$_tc"
+  echo "ERROR: extract-affected-files.sh is not installed in any trusted ForgeDock install path." >&2
   return 1
 }