forgedock 1.10.3 → 1.12.0

package/bin/engine.mjs

@@ -29,6 +29,12 @@ export const DEFAULT_LEASE_RENEW_INTERVAL_MS = 240000;
 // need at most one or two pauses in practice.
 export const DEFAULT_MAX_SESSION_LIMIT_PAUSES = 5;
 
+// forge#3511: bounded wait applied ONLY when the runner flagged a confirmed
+// usage-limit failure (`err.usageLimit`) but could not produce a parseable
+// reset epoch. The runner never fabricates a reset time; this default lives in
+// the engine and is still capped by `maxSessionLimitPauses`.
+export const DEFAULT_SESSION_LIMIT_WAIT_MS = 30 * 60 * 1000;
+
 /**
  * Validates the subset of `runIssue()`'s options that must fail fast,
  * synchronously, before any state I/O or timer creation — `backend` and the
@@ -44,7 +50,7 @@ export const DEFAULT_MAX_SESSION_LIMIT_PAUSES = 5;
  * @param {number} params.maxSessionLimitPauses - forge#2524: bound on consecutive session-limit pauses.
  * @throws {Error & {code: "INVALID_BACKEND"|"INVALID_LEASE_CONFIG"|"INVALID_SESSION_LIMIT_CONFIG"}}
  */
-function validateRunIssueOptions({ backend, leaseTtlMs, leaseRenewIntervalMs, maxSessionLimitPauses }) {
+function validateRunIssueOptions({ backend, leaseTtlMs, leaseRenewIntervalMs, maxSessionLimitPauses, sessionLimitDefaultWaitMs = DEFAULT_SESSION_LIMIT_WAIT_MS }) {
   // forge#2054: validate `backend` before anything else — before state is
   // read/written and before the phase/retry loop begins below. An invalid
   // value must fail fast and non-retryably. Without this check, an invalid
@@ -128,6 +134,15 @@ function validateRunIssueOptions({ backend, leaseTtlMs, leaseRenewIntervalMs, ma
       { code: "INVALID_SESSION_LIMIT_CONFIG" },
     );
   }
+  // forge#3511: same guard for the unknown-reset default wait.
+  if (typeof sessionLimitDefaultWaitMs !== "number" || !Number.isFinite(sessionLimitDefaultWaitMs) || sessionLimitDefaultWaitMs < 0) {
+    throw Object.assign(
+      new Error(
+        `Invalid session-limit config: sessionLimitDefaultWaitMs must be a finite number >= 0, got ${typeof sessionLimitDefaultWaitMs === "number" ? sessionLimitDefaultWaitMs : `${typeof sessionLimitDefaultWaitMs} (${JSON.stringify(sessionLimitDefaultWaitMs)})`}.`,
+      ),
+      { code: "INVALID_SESSION_LIMIT_CONFIG" },
+    );
+  }
 }
 
 /**
@@ -204,6 +219,14 @@ function makeProgressEmitter(onProgress) {
  *   Defaults to DEFAULT_MAX_SESSION_LIMIT_PAUSES. Purely a defensive backstop
  *   against a persistently-misreported reset time; a genuine reset is
  *   expected to need at most one or two pauses in practice.
+ * @param {number} [opts.sessionLimitDefaultWaitMs] - forge#3511: how long to
+ *   pause when the failure is a confirmed usage limit but no reset time could
+ *   be parsed. Defaults to DEFAULT_SESSION_LIMIT_WAIT_MS; counts against
+ *   `maxSessionLimitPauses`.
+ * @param {boolean} [opts.retry] - forge#3511: explicit opt-in. When the run's
+ *   terminal reason is `engine-error`, reopen it (RUN_REOPEN) and resume from
+ *   the last committed phase. Any other terminal reason is left untouched and
+ *   returns `not-retryable`.
  */
 export async function runIssue(opts) {
   const { issue, dir, agentId, lane = "staging", io, runner,
@@ -214,12 +237,19 @@ export async function runIssue(opts) {
           // callers keep runner.mjs's own "auto" ladder default unchanged —
           // this is purely additive pass-through, not a new default.
           backend, model,
+          // forge#3499: "owner/repo" the phase sub-skills must target
+          // (`--repo` / `--gh-flag`). Optional override; otherwise resolved
+          // lazily — once, only if a phase's runner is actually invoked —
+          // from the cwd-resolved repo (`gh repo view`).
+          repo,
           leaseTtlMs = DEFAULT_LEASE_TTL_MS,
           leaseRenewIntervalMs = DEFAULT_LEASE_RENEW_INTERVAL_MS,
           // forge#2524: real default is a genuine setTimeout-based wait —
           // tests inject a fast/no-op replacement (see opts.sleep doc above).
           sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
           maxSessionLimitPauses = DEFAULT_MAX_SESSION_LIMIT_PAUSES,
+          sessionLimitDefaultWaitMs = DEFAULT_SESSION_LIMIT_WAIT_MS,
+          retry = false,
           onProgress = () => {} } = opts;
 
   // forge#2452: extracted into makeProgressEmitter() — see its docstring for
@@ -230,7 +260,7 @@ export async function runIssue(opts) {
   // for the forge#2054/#2313/#2329 rationale and required call-order (before
   // any state I/O or timer creation, unchanged from the inline block this
   // replaces).
-  validateRunIssueOptions({ backend, leaseTtlMs, leaseRenewIntervalMs, maxSessionLimitPauses });
+  validateRunIssueOptions({ backend, leaseTtlMs, leaseRenewIntervalMs, maxSessionLimitPauses, sessionLimitDefaultWaitMs });
 
   const projector = makeProjector(io);
 
@@ -260,6 +290,25 @@ export async function runIssue(opts) {
     rewriteLog(dir, issue, eventsFromIndex(state));
     state = deriveState(readLog(dir, issue));
   }
+
+  // forge#3511: explicit `--retry` reopens a transient `engine-error` terminal
+  // so the run resumes from its last committed phase. Placed AFTER the I3
+  // lease guard (never weaken that ordering) and BEFORE the unconditional
+  // lease write below, which then publishes `terminal:false` at the reopen's
+  // higher `v`. Only `engine-error` is ever reopened; needs-human / merged /
+  // decomposed / etc. terminals are left untouched.
+  let reopened = false;
+  if (retry && state?.terminal) {
+    if (state.terminalReason !== "engine-error") {
+      return {
+        terminalReason: "not-retryable",
+        detail: `issue ${issue} ended ${state.terminalReason}; --retry only reopens an engine-error run`,
+      };
+    }
+    appendEvent(dir, issue, { event: "RUN_REOPEN", issue });
+    state = deriveState(readLog(dir, issue));
+    reopened = true;
+  }
   // forge#2239: claim the lease unconditionally here — before the phase loop
   // starts, for EVERY reconcile action ("fresh", "remirror", "hydrate", and
   // "local"). Previously only "fresh"/"remirror"/"hydrate" wrote any state at
@@ -273,6 +322,17 @@ export async function runIssue(opts) {
   // check above (commit 541a3e5 fixed the reverse ordering as a real bug —
   // do not reintroduce it).
   await projector.writeState(issue, { ...state, lease: { by: agentId, until: now() + leaseTtlMs } });
+  // forge#3511: clear the stale label only after the reopened state is
+  // published, so a crash in between leaves the run still marked engine-error.
+  // On `--retry` this runs whether or not THIS invocation did the reopen: a prior
+  // retry may have published the reopen and died before removing the label, so the
+  // next one sees a non-terminal state (reopened=false) with the label still set.
+  // Best-effort — a transient `gh` error must not abort a reopen already published.
+  // Removing an absent label is a harmless no-op.
+  if (retry) {
+    try { await projector.removeLabel(issue, "workflow:engine-error"); }
+    catch (err) { console.warn(`forge#3511: could not clear workflow:engine-error on #${issue}: ${err?.message || err}`); }
+  }
 
   // 2. Drive phases until terminal.
   //
@@ -284,8 +344,26 @@ export async function runIssue(opts) {
   // against a nonexistent ref and silently evaluated to 0 (forge#2174). The
   // build phase's `reconcile`/`detectOutcome` (bin/engine/phases.mjs) resolve
   // the real branch from the `FORGE:BUILDER` comment instead.
+  let repoPromise = null;
+  const resolveRepo = () => (repoPromise ??= (async () => {
+    if (repo) return String(repo).trim();
+    try {
+      const out = await io.gh(["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"]);
+      return String(out || "").trim() || null;
+    } catch { return null; }
+  })());
+
   let phase;
   while ((phase = pickPhase(state))) {
+    // forge#3506 (SPEC-1/SPEC-2): a crash after a terminal-after phase committed (remediate or
+    // decompose) and before RUN_TERMINAL leaves its persisted reason on the commit event. Resume
+    // must honour that reason instead of picking the next phase (close would throw in buildArgs
+    // and end as engine-error; build would run on a decomposed parent). Review's `needs-human`
+    // is a handoff to remediate, so only these two committed phases trigger the guard.
+    if (state.terminalReason && TERMINAL_REASONS.includes(state.terminalReason) &&
+        ((state.committed.includes("remediate") && !["merged", "decomposed", "invalid"].includes(state.terminalReason)) ||
+         (state.committed.includes("decompose") && state.terminalReason === "decomposed")))
+      return await terminate(state, state.terminalReason);
     // forge#2352: state-vs-GitHub divergence guard. Every phase's own
     // `entryCondition` only ever checked `state.committed` (local run-log
     // progress) — never the issue's live GitHub state/labels — so a phase
@@ -428,18 +506,21 @@ export async function runIssue(opts) {
         let pauseCount = 0;
         for (;;) {
           try {
-            outcome = await runPhaseWithRetry(phase, state, { io, runner, dir, issue, commandsDir, maxAttempts, backend, model });
+            outcome = await runPhaseWithRetry(phase, state, { io, runner, dir, issue, commandsDir, maxAttempts, backend, model, resolveRepo });
             break;
           } catch (e) {
             const resetAtMs = e.resetAtEpochMs;
+            const hasResetEpoch =
+              typeof resetAtMs === "number" && Number.isFinite(resetAtMs) && resetAtMs > now();
+            // forge#3511: a confirmed usage limit whose reset time is
+            // missing/unparseable/already past still pauses, by a bounded default.
             const canPause =
               e.code === "CLI_BACKEND_FAILED" &&
-              typeof resetAtMs === "number" && Number.isFinite(resetAtMs) &&
-              resetAtMs > now() &&
+              (hasResetEpoch || e.usageLimit === true) &&
               pauseCount < maxSessionLimitPauses;
             if (!canPause) throw e; // falls through to the unchanged outer catch below
             pauseCount += 1;
-            const waitMs = Math.max(0, resetAtMs - now());
+            const waitMs = hasResetEpoch ? Math.max(0, resetAtMs - now()) : sessionLimitDefaultWaitMs;
             // forge#2524 AC4: append a run-log event so a crash mid-wait
             // leaves a durable record of the pause (deriveState() folds this
             // into RunState.lastRateLimit — see bin/engine/runlog.mjs). This
@@ -449,15 +530,17 @@ export async function runIssue(opts) {
             // was ever written.
             appendEvent(dir, issue, {
               event: "PHASE_RATE_LIMITED", phase: phase.id,
-              resetAt: resetAtMs, resetAtDisplay: e.resetAt || null, waitMs,
+              resetAt: hasResetEpoch ? resetAtMs : null, resetAtDisplay: e.resetAt || null, waitMs,
             });
             // forge#2524 AC6: progress observer sees the pause so a caller
             // (bin/engine-cli.mjs) can render the wait state instead of the
             // process going silent for the duration.
             emitProgress({
               event: "phase_paused", phase: phase.id, reason: "session-limit",
-              resetAt: resetAtMs,
-              detail: `session limit hit — pausing until ${e.resetAt || new Date(resetAtMs).toISOString()}`,
+              resetAt: hasResetEpoch ? resetAtMs : null,
+              detail: hasResetEpoch
+                ? `session limit hit — pausing until ${e.resetAt || new Date(resetAtMs).toISOString()}`
+                : `session limit hit — reset time unknown, waiting default ${Math.round(waitMs / 60000)} min`,
             });
             await sleep(waitMs);
             // Loop back and retry the same phase with a fresh attempt budget
@@ -522,8 +605,14 @@ export async function runIssue(opts) {
       }
     }
 
+    // forge#3499: remediate takes the PR number as its positional argument, so
+    // the handoff only applies when review resolved one. A review that blocked
+    // without ever resolving a PR (e.g. retries exhausted before one existed)
+    // has nothing to remediate and stays a plain needs-human stop — it must not
+    // fall through to `close`, which would otherwise be the next eligible phase.
     const isRemediationHandoff = outcome.status === "blocked" &&
-      phase.id === "review" && (outcome.reason || "needs-human") === "needs-human";
+      phase.id === "review" && (outcome.reason || "needs-human") === "needs-human" && outcome.handoff !== false &&
+      (outcome.outputs?.pr ?? state.pr) != null;
     if (outcome.status === "blocked") {
       emitProgress({ event: "phase_exit", phase: phase.id, status: "blocked", detail: outcome.detail });
       if (!isRemediationHandoff)
@@ -547,11 +636,24 @@ export async function runIssue(opts) {
     // the "committed" path, so that case doesn't apply here). Kept as a
     // sibling of `outputs` rather than nested inside it, since `outputs` is
     // owned by phase.detectOutcome() (bin/engine/phases.mjs).
-    appendEvent(dir, issue, { event: "PHASE_COMMIT", phase: phase.id, outputs: outcome.outputs || {}, usage: outcome.usage ?? null });
+    // forge#3503/#3504: a blocked review hands off to remediate, which reads the PR
+    // number and the needs-human reason from state re-derived from the run log. Persist
+    // both in the PHASE_COMMIT event itself so a rebuild (the next line, or a resume)
+    // sees them; in-memory-only values are discarded by deriveState.
+    const commitOutputs = { ...(outcome.outputs || {}) };
+    if (outcome.status === "blocked" && commitOutputs.pr == null && state.pr != null)
+      commitOutputs.pr = state.pr;
+    const blockedReason = outcome.status === "blocked" ? (outcome.reason || "needs-human") : null;
+    // forge#3506: committed outcomes also carry handoff/terminal reasons (investigate
+    // `decomposed`, remediate `merged`/`awaiting-merge`/`needs-human`). Persist them on the
+    // commit event too, so a crash before RUN_TERMINAL or a rebuild cannot drop them.
+    const commitReason = blockedReason ?? outcome.terminalReason ?? null;
+    appendEvent(dir, issue, {
+      event: "PHASE_COMMIT", phase: phase.id, outputs: commitOutputs, usage: outcome.usage ?? null,
+      ...(commitReason ? { terminalReason: commitReason } : {}),
+    });
     state = deriveState(readLog(dir, issue));
-    const terminalReason = outcome.status === "blocked"
-      ? (outcome.reason || "needs-human")
-      : outcome.terminalReason;
+    const terminalReason = blockedReason ?? outcome.terminalReason;
     if (terminalReason) state.terminalReason = terminalReason;
     await projector.writeState(issue, { ...state, lease: { by: agentId, until: now() + leaseTtlMs } });
 
@@ -597,7 +699,21 @@ export async function runIssue(opts) {
 }
 
 async function runPhaseWithRetry(phase, state, ctx) {
-  const { io, runner, dir, issue, commandsDir, maxAttempts, backend, model } = ctx;
+  const { io, runner, dir, issue, commandsDir, maxAttempts, backend, model, resolveRepo } = ctx;
+  // forge#3499: build the phase's full argument set ONCE, up front. Every
+  // work-on phase sub-skill stops with BLOCKED when a required flag is absent,
+  // so an incomplete/invalid set is a deterministic engine failure — fail
+  // closed here (no runner call, no retries) instead of sending a partial
+  // `[issue]`-only invocation that burns the attempt budget.
+  let phaseArgs;
+  try {
+    phaseArgs = await phase.buildArgs(state, { repo: await resolveRepo() }, io);
+  } catch (e) {
+    if (e?.code !== "PHASE_ARGS_INVALID") throw e;
+    const detail = `phase ${phase.id} args unresolved: ${e.message}`;
+    appendEvent(dir, issue, { event: "PHASE_FAILED", phase: phase.id, attempt: 0, reason: detail, maxAttempts });
+    return { status: "blocked", detail, reason: "engine-error", usage: null };
+  }
   // forge#2261: true only if EVERY attempt failed by the runner itself
   // throwing (never once reached phase.detectOutcome()). This is the signal
   // that distinguishes an engine/tool crash (the tool never even produced a
@@ -621,7 +737,7 @@ async function runPhaseWithRetry(phase, state, ctx) {
     let result;
     try {
       result = await runner({
-        commandsDir, commandName: phase.command, args: [String(issue)],
+        commandsDir, commandName: phase.command, args: phaseArgs,
         // Only forwarded when explicitly provided — omitting them preserves
         // runner.mjs's existing default ("auto" backend / DEFAULT_MODEL).
         ...(backend ? { backend } : {}),
@@ -656,7 +772,7 @@ async function runPhaseWithRetry(phase, state, ctx) {
     }
     allAttemptsThrew = false;
     lastUsage = result?.usage ?? null;
-    const outcome = await phase.detectOutcome(state, io);
+    const outcome = await phase.detectOutcome(state, io, result);
     if (outcome.status === "committed" || outcome.status === "blocked") return { ...outcome, usage: lastUsage };
     appendEvent(dir, issue, { event: "PHASE_FAILED", phase: phase.id, attempt, reason: outcome.detail, maxAttempts, usage: lastUsage });
     // forge#2176: a phase's detectOutcome can mark a failure as a known,
@@ -670,7 +786,9 @@ async function runPhaseWithRetry(phase, state, ctx) {
     // for every phase that doesn't opt in — investigate/context/architect/
     // review/close — is unchanged, preserving transient-failure retries).
     if (outcome.retryable === false) {
-      return { status: "blocked", detail: outcome.detail, usage: lastUsage };
+      // forge#3521: keep outcome.outputs (e.g. the PR number) so the blocked
+      // commit persists it and isRemediationHandoff can see it.
+      return { status: "blocked", detail: outcome.detail, outputs: outcome.outputs, handoff: outcome.handoff, usage: lastUsage };
     }
   }
   // Exhausted transient retries → escalate (spec §7).
@@ -706,6 +824,14 @@ function eventsFromIndex(idx) {
     if (phase === "review" && idx.pr != null) outputs.pr = idx.pr;
     events.push({ event: "PHASE_COMMIT", phase, outputs });
   }
+  // forge#3506: a non-terminal reason is a handoff (e.g. review -> remediate). Replay it on
+  // the last committed PHASE_COMMIT (deriveState is last-wins), never as RUN_TERMINAL, which
+  // would terminate the run. Nothing to attach it to when no phase is committed.
+  if (!idx.terminal && idx.terminalReason && idx.committed.length > 0) {
+    for (let i = events.length - 1; i >= 0; i--) {
+      if (events[i].event === "PHASE_COMMIT") { events[i].terminalReason = idx.terminalReason; break; }
+    }
+  }
   if (idx.terminal) events.push({ event: "RUN_TERMINAL", reason: idx.terminalReason });
   return events;
 }

package/bin/forgedock.mjs

@@ -3207,7 +3207,7 @@ function help() {
     ["npx forgedock disable [dir]", "Opt a directory out of ForgeDock"],
     ["npx forgedock status [dir]", "Show ForgeDock state for a directory"],
     ["npx forgedock run <cmd> [args]", "Run a command headlessly (local claude CLI or Anthropic API)"],
-    ["npx forgedock run-issue <issue>", "Drive one issue through the durable engine"],
+    ["npx forgedock run-issue <issue> --lane <lane> [--retry]", "Drive one issue through the durable engine (--retry reopens an engine-error run)"],
     ["npx forgedock resume-stalled [--dry-run]", "Fleet stall recovery — re-dispatch expired-lease issues"],
     ["npx forgedock demo", "Set up a risk-free demo repo and print next steps"],
     ["npx forgedock labels [setup] [--repo owner/repo]", "Bootstrap ForgeDock-managed labels on a GitHub repo (idempotent)"],
@@ -3971,7 +3971,7 @@ switch (command) {
       // an uncaught throw, which already set exitCode = 1 below. Now that
       // runIssue() resolves cleanly with a terminalReason instead of throwing,
       // preserve that same non-zero exit code for this reason too.
-      if (result && (result.terminalReason === "needs-human" || result.terminalReason === "engine-error")) exitCode = 1;
+      if (result && (result.terminalReason === "needs-human" || result.terminalReason === "engine-error" || result.terminalReason === "not-retryable")) exitCode = 1;
     } catch (err) {
       process.stderr.write(`${RED}${err.message}${RESET}\n`);
       exitCode = 1;

package/bin/runner.mjs

@@ -933,6 +933,53 @@ export function sanitizeOutputExcerptForLog(output) {
   return sanitizeAndCap(String(output), MAX_LOGGED_OUTPUT_EXCERPT_LEN);
 }
 
+// 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");
+
+/**
+ * Parses a `claude --output-format json` single-result envelope from `text`.
+ * Returns the parsed object, or `undefined` when `text` is not exactly one
+ * JSON object. Never throws.
+ */
+function parseCliEnvelope(text) {
+  if (typeof text !== "string") return undefined;
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("{")) return undefined;
+  try {
+    const parsed = JSON.parse(trimmed);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 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.
+ *
+ * @param {string} stdout - raw stdout of the CLI run
+ * @param {string} [output] - combined stdout+stderr, for the plain-text fallback
+ * @returns {boolean}
+ */
+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;
+  }
+  return USAGE_LIMIT_RE.test(output || "") && /resets?\s/i.test(output || "");
+}
+
 /**
  * Best-effort extraction of a Claude CLI session-limit reset time from
  * captured stdout/stderr (forge#2241). The CLI's own session-limit message
@@ -952,7 +999,15 @@ export function sanitizeOutputExcerptForLog(output) {
  */
 export function extractSessionLimitResetTime(output) {
   if (!output) return undefined;
-  const match = /session limit[^\n]*?resets?\s+([^\n]+?)\s*$/im.exec(output);
+  // The engine runs phases with `--output-format json`, so the limit message
+  // usually arrives inside a one-line JSON envelope. Read the structured
+  // `result` text when the whole input parses; otherwise fall back to the raw
+  // text. The plain-text captures below never cross a quote or newline, so a
+  // 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);
   if (!match) return undefined;
   const resetAt = match[1].trim();
   if (resetAt.length === 0) return undefined;
@@ -1036,19 +1091,26 @@ function wallTimeInZoneToEpochMs(y, mo, d, h, mi, s, timeZone) {
  */
 export function parseSessionLimitResetEpochMs(resetAtText, nowMs = Date.now()) {
   if (!resetAtText) return undefined;
-  const match = /^(\d{1,2}):(\d{2})\s*([ap]m)\s*\(([^)]+)\)\s*$/i.exec(resetAtText.trim());
+  const match = /^(\d{1,2})(?::(\d{2}))?\s*([ap]m)?\s*\(([^)]+)\)\s*$/i.exec(resetAtText.trim());
   if (!match) return undefined;
   const [, hourStr, minuteStr, ampm, timeZone] = match;
   const rawHour = parseInt(hourStr, 10);
-  // Reject out-of-range hours BEFORE the `% 12` conversion below — otherwise
-  // malformed input like "13:30pm" or "99:30pm" silently aliases to a
-  // plausible-but-wrong hour (13 % 12 = 1, 99 % 12 = 3) instead of being
-  // rejected, violating this function's own "never fabricate a value"
-  // contract. Mirrors the `minute > 59` guard further down.
-  if (rawHour < 1 || rawHour > 12) return undefined;
-  let hour = rawHour % 12;
-  if (/pm/i.test(ampm)) hour += 12;
-  const minute = parseInt(minuteStr, 10);
+  let hour;
+  if (ampm) {
+    // Reject out-of-range hours BEFORE the `% 12` conversion below — otherwise
+    // malformed input like "13:30pm" or "99:30pm" silently aliases to a
+    // plausible-but-wrong hour (13 % 12 = 1, 99 % 12 = 3) instead of being
+    // rejected, violating this function's own "never fabricate a value"
+    // contract. Mirrors the `minute > 59` guard further down.
+    if (rawHour < 1 || rawHour > 12) return undefined;
+    hour = rawHour % 12;
+    if (/pm/i.test(ampm)) hour += 12;
+  } else {
+    // 24-hour form: minutes are required (a bare "15" is too ambiguous).
+    if (minuteStr === undefined || rawHour > 23) return undefined;
+    hour = rawHour;
+  }
+  const minute = minuteStr === undefined ? 0 : parseInt(minuteStr, 10);
   if (!Number.isFinite(hour) || !Number.isFinite(minute) || minute > 59) return undefined;
 
   let todayParts;
@@ -1261,7 +1323,14 @@ export function runCliBackend({
       // present) so callers (bin/engine.mjs) can surface *when* a
       // quota-exhaustion failure will clear without reading raw logs. Only
       // ever set when the pattern actually matches — never fabricated.
-      const resetAt = extractSessionLimitResetTime(output);
+      // 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);
+      // 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 (resetAt) {
         err.resetAt = resetAt;
         // forge#2524: also attach a machine-usable epoch-ms timestamp so
@@ -1392,6 +1461,9 @@ export function runCliBackend({
       usage,
       model: "cli",
       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.
+      text: parsedResult ?? "",
     };
   } finally {
     if (tmpDir) {
@@ -2377,6 +2449,11 @@ export async function runCommand(opts = {}) {
         usage,
         model,
         backend: "api",
+        // forge#3521: final assistant text (see the CLI backend's `text`).
+        text: (response.content || [])
+          .filter((blk) => blk.type === "text" && typeof blk.text === "string")
+          .map((blk) => blk.text)
+          .join("\n"),
       };
     }
 

package/commands/ci-audit.md

@@ -253,7 +253,7 @@ For each gap detected (tool present in repo but no CI validation step found), fi
 **Skip issue creation if `--dry-run` flag is passed** (or `forge.yaml → ci_audit.dry_run: true`):
 ```bash
 DRY_RUN=$(yq '.ci_audit.dry_run // "false"' forge.yaml 2>/dev/null || echo "false")
-[ "$1" = "--dry-run" ] || [ "$2" = "--dry-run" ] && DRY_RUN="true"
+[ "${1}" = "--dry-run" ] || [ "${2}" = "--dry-run" ] && DRY_RUN="true"
 ```
 
 ### 3A: Determine validator recommendation
@@ -262,8 +262,8 @@ For each gap, compose a concrete, version-aware recommendation:
 
 ```bash
 get_validator_recommendation() {
-    local tool="$1"
-    local version="$2"  # may be empty if unknown
+    local tool="${1}"
+    local version="${2}"  # may be empty if unknown
 
     case "$tool" in
         traefik)

package/commands/compat-audit.md

@@ -28,7 +28,7 @@ fi
 # Fallback: resolve from this command file's own location if yq is unavailable
 # or forge.yaml is absent. The commands/ directory is always inside FORGE_HOME.
 if [ -z "$FORGE_HOME_PATH" ] || [ ! -d "$FORGE_HOME_PATH" ]; then
-  FORGE_HOME_PATH="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/.." 2>/dev/null && pwd)"
+  FORGE_HOME_PATH="$(cd "$(dirname "${BASH_SOURCE[0]:-${0}}")/.." 2>/dev/null && pwd)"
 fi
 export FORGE_HOME_PATH
 ```

package/commands/deploy-pr.md

@@ -93,12 +93,12 @@ DRY_RUN=false
 # Parse optional flags
 shift 2>/dev/null || true
 while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --target)      TARGET="$2";           shift 2 ;;
-    --issue)       ISSUE_NUMBER="$2";     shift 2 ;;
-    --repo)        GH_REPO="$2"; GH_FLAG="-R $GH_REPO"; shift 2 ;;
-    --max-ci-iterations)     MAX_CI_ITER="$2";     shift 2 ;;
-    --max-review-iterations) MAX_REVIEW_ITER="$2"; shift 2 ;;
+  case "${1}" in
+    --target)      TARGET="${2}";           shift 2 ;;
+    --issue)       ISSUE_NUMBER="${2}";     shift 2 ;;
+    --repo)        GH_REPO="${2}"; GH_FLAG="-R $GH_REPO"; shift 2 ;;
+    --max-ci-iterations)     MAX_CI_ITER="${2}";     shift 2 ;;
+    --max-review-iterations) MAX_REVIEW_ITER="${2}"; shift 2 ;;
     --dry-run)     DRY_RUN=true;          shift ;;
     *) shift ;;
   esac

package/commands/explain.md

@@ -140,10 +140,10 @@ Extract each annotation block from the comments. Each `<!-- FORGE:TYPE -->` bloc
 ```bash
 # Helper: extract comment body containing a FORGE marker
 extract_forge() {
-  local marker="$1"
+  local marker="${1}"
   echo "$ALL_COMMENTS" | awk "
     /<!-- ${marker}(:[A-Z]*)? -->/{found=1; buffer=\"\"}
-    found {buffer = buffer \$0 ORS}
+    found {buffer = buffer \$(0) ORS}
     /<!-- ${marker}[^>]*:COMPLETE -->/{if(found){print buffer; found=0; buffer=\"\"}}
     END {if(found && length(buffer)>0) print buffer}
   "

package/commands/fix-ci.md

@@ -49,7 +49,7 @@ Parse `$ARGUMENTS`:
 
 ```bash
 # Extract PR number (accept raw number or full GitHub URL)
-PR_INPUT=$(echo "$ARGUMENTS" | awk '{print $1}')
+PR_INPUT=$(echo "$ARGUMENTS" | awk '{print $(1)}')
 if echo "$PR_INPUT" | grep -qE '^https?://'; then
   PR_NUMBER=$(echo "$PR_INPUT" | grep -oE '[0-9]+$')
 else
@@ -58,7 +58,7 @@ fi
 
 MAX_ATTEMPTS=5
 if echo "$ARGUMENTS" | grep -q -- "--max-attempts"; then
-  MAX_ATTEMPTS=$(echo "$ARGUMENTS" | grep -oE -- '--max-attempts [0-9]+' | awk '{print $2}')
+  MAX_ATTEMPTS=$(echo "$ARGUMENTS" | grep -oE -- '--max-attempts [0-9]+' | awk '{print $(2)}')
 fi
 
 if [ -z "$PR_NUMBER" ]; then

package/commands/forge-stats.md

@@ -104,7 +104,7 @@ for cmd in commands/*.md; do
 done
 
 echo ""
-echo "Total: $(wc -l commands/*.md | tail -1 | awk '{print $1}') lines across $(ls commands/*.md | wc -l) commands"
+echo "Total: $(wc -l commands/*.md | tail -1 | awk '{print $(1)}') lines across $(ls commands/*.md | wc -l) commands"
 ```
 
 **After running, flag any command where:**

package/commands/forgedock-init.md

@@ -576,7 +576,7 @@ gh repo view "${OWNER}/${REPO}" --json name,url 2>/dev/null \
 ### 6B: Path existence
 
 ```bash
-[ -d "$(grep 'root:' "$FORGE_YAML" | head -1 | awk '{print $2}' | tr -d '"')" ] \
+[ -d "$(grep 'root:' "$FORGE_YAML" | head -1 | awk '{print $(2)}' | tr -d '"')" ] \
   && echo "✓ paths.root exists" \
   || echo "WARNING: paths.root does not exist on this machine"
 ```
@@ -588,7 +588,7 @@ gh repo view "${OWNER}/${REPO}" --json name,url 2>/dev/null \
 ```bash
 # Only run if project_board section was written
 if grep -q "^project_board:" "$FORGE_YAML"; then
-  PROJECT_ID=$(grep "project_id:" "$FORGE_YAML" | head -1 | awk '{print $2}' | tr -d '"')
+  PROJECT_ID=$(grep "project_id:" "$FORGE_YAML" | head -1 | awk '{print $(2)}' | tr -d '"')
   # Validate PVT_ prefix before GraphQL call — any other format will produce a confusing API error
   if [[ "$PROJECT_ID" != PVT_* ]]; then
     echo "ERROR: project_board.project_id must start with 'PVT_' (got: '$PROJECT_ID')"
@@ -610,7 +610,7 @@ fi
 if grep -q "^repos:" "$FORGE_YAML"; then
   # Extract satellite repo names and verify each is accessible
   grep -A 20 "^repos:" "$FORGE_YAML" | grep "repo:" | tail -n +2 | while read -r line; do
-    SAT_REPO=$(echo "$line" | awk '{print $2}' | tr -d '"')
+    SAT_REPO=$(echo "$line" | awk '{print $(2)}' | tr -d '"')
     gh repo view "$SAT_REPO" --json name 2>/dev/null \
       && echo "✓ satellite repo ${SAT_REPO} accessible" \
       || echo "WARNING: satellite repo ${SAT_REPO} not accessible — check prefix and repo name"

package/commands/optimize.md

@@ -250,7 +250,7 @@ declare -A LABEL_MAP=(
 )
 
 map_label() {
-  local canonical="$1"
+  local canonical="${1}"
   echo "${LABEL_MAP[$canonical]:-$canonical}"
 }
 SCRIPT_EOF
@@ -514,8 +514,8 @@ for candidate in "${TIER_A_PROMOTIONS[@]}"; do
 # Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)
 #
 # CONTRACT:
-#   \$1 = absolute path to unified diff (git diff HEAD)
-#   \$2 = absolute path to worktree root
+#   \${1} = absolute path to unified diff (git diff HEAD)
+#   \${2} = absolute path to worktree root
 #   stdout = findings lines: SLUG | SEVERITY | FILE | MESSAGE
 #   exit 0 = pass, exit 1 = findings, exit 2 = inapplicable
 #   30s timeout enforced by quality-gate (fail-closed)
@@ -612,8 +612,8 @@ ${CITATIONS_BODY}
 ## gate.d contract
 
 Each script receives:
-- \$1 = path to unified diff
-- \$2 = path to worktree root
+- \${1} = path to unified diff
+- \${2} = path to worktree root
 - exits 0 (pass), 1 (findings on stdout), or 2 (inapplicable)
 - 30-second timeout enforced by quality-gate (fail-closed on timeout)