forgedock 1.11.0 → 1.12.1

package/bin/engine/runlog.mjs

@@ -57,7 +57,10 @@ export function deriveState(events) {
   /** @type {import("./phases.mjs").RunState} */
   const s = { v: 0, run: null, issue: null, lane: "staging", committed: [],
               phase: null, branch: null, pr: null, terminal: false,
-              terminalReason: null, lease: null, lastRateLimit: null };
+              terminalReason: null, lease: null, lastRateLimit: null,
+              remediationKind: null };
+  // forge#3528: handoff reason of the LAST PHASE_COMMIT only (replaced, not sticky).
+  let lastCommitReason = null;
   for (const e of events) {
     switch (e.event) {
       case "RUN_START":
@@ -68,10 +71,27 @@ export function deriveState(events) {
         s.v = e.seq;
         if (e.outputs?.branch) s.branch = e.outputs.branch;
         if (e.outputs?.pr != null) s.pr = e.outputs.pr;
+        // forge#3504: a blocked phase persists its reason so a resumed run still routes to
+        // remediate instead of defaulting to a "merged" close.
+        if (e.terminalReason) s.terminalReason = e.terminalReason;
+        lastCommitReason = e.terminalReason ?? null;
+        // forge#3530: the review's remediation kind must survive resume. A later review
+        // commit replaces it; a committed remediate consumes it, so it is never reused.
+        if (e.phase === "review") s.remediationKind = e.outputs?.remediation ?? null;
+        else if (e.phase === "remediate") s.remediationKind = null;
         break;
       case "RUN_TERMINAL":
         s.terminal = true; s.terminalReason = e.reason ?? "done"; s.v = e.seq;
         break;
+      // forge#3511: an explicit `run-issue --retry` reopens an engine-error
+      // terminal. Bumping `v` makes the local state newer than the stale
+      // remote terminal index so reconcile remirrors instead of re-terminating.
+      // forge#3528: RUN_TERMINAL overwrote the persisted handoff reason
+      // (needs-human / decomposed); restore the last commit's reason so the
+      // retry re-enters remediate/decompose instead of close/build.
+      case "RUN_REOPEN":
+        s.terminal = false; s.terminalReason = lastCommitReason; s.v = e.seq;
+        break;
       // forge#2524: a session-limit pause is purely informational — it does
       // NOT touch committed/terminal/terminalReason. The phase that hit the
       // pause is, by construction, not yet committed (the engine is about to

package/bin/engine-cli.mjs

@@ -26,6 +26,7 @@ export const ACTIVE_WORKFLOW_LABELS = [
   "workflow:ready-to-build",
   "workflow:building",
   "workflow:in-review",
+  "workflow:remediating",
 ];
 
 const pexec = promisify(execFile);
@@ -337,16 +338,21 @@ export function lastLocalRun(dir) {
  *                          `runCommand()` call; only applies on the "api" backend.
  *                          Omit to keep runner.mjs's default (`FORGEDOCK_MODEL` env
  *                          or its built-in default).
+ *   --retry                Optional (forge#3511). Reopen a run that ended `engine-error`
+ *                          (e.g. a session-limit hit) and resume from its last committed
+ *                          phase. Other terminal reasons are not reopened.
  */
 export async function runFromCli(argv, deps = {}) {
   const issue = parseInt(argv[0], 10);
-  if (!Number.isInteger(issue)) throw new Error("usage: forgedock run-issue <issue-number> --lane <lane>");
+  if (!Number.isInteger(issue)) throw new Error("usage: forgedock run-issue <issue-number> --lane <lane> [--retry]");
   assertOpenCodeNativeRuntime({ operation: "forgedock run-issue" });
   const lane = flag(argv, "--lane");
   if (!lane) throw new Error("--lane is required: e.g. --lane main or --lane staging. No default to prevent accidental production targeting.");
   const repo = flag(argv, "--repo");
   const backend = flag(argv, "--backend");
   const model = flag(argv, "--model");
+  // Boolean flag: only counts at a flag position, never as another flag's value.
+  const retry = argv.some((a, i) => a === "--retry" && !["--lane", "--repo", "--backend", "--model"].includes(argv[i - 1]));
   const io = deps.io ?? makeIo();
   await assertRepoMatchesCwd(io, repo);
   const runIssueFn = deps.runIssue ?? runIssue;
@@ -375,13 +381,19 @@ export async function runFromCli(argv, deps = {}) {
     else if (e.event === "phase_paused") console.log(`⏸ phase ${e.phase} paused: ${e.detail ?? "session limit"}`);
   };
   const res = await runIssueFn({ issue, dir, agentId, lane, io,
+    ...(repo ? { repo } : {}),
     runner: (await import("./runner.mjs")).runCommand, now: () => Date.now(),
     onProgress,
     // Only forwarded when explicitly provided — omitting them preserves
     // runIssue's/runner.mjs's existing defaults (forge#2028).
     ...(backend ? { backend } : {}),
-    ...(model ? { model } : {}) });
+    ...(model ? { model } : {}),
+    ...(retry ? { retry: true } : {}) });
   console.log(`issue #${issue} → ${res.terminalReason}`);
+  if (res.terminalReason === "not-retryable") {
+    console.log(res.detail ?? "run is not retryable");
+    return res;
+  }
   // forge#2175: a non-success termination previously printed nothing beyond
   // the bare reason above — the actual failing phase/attempt/reason was only
   // recoverable by manually reading ~/.forge/runs/{issue}.jsonl and then the

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,29 @@ 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 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") ||
+         // forge#3512: investigate persists `invalid` on its own commit. Only when investigate is
+         // the LAST committed phase: a later remediate/close commit carrying `invalid` is a handoff.
+         (state.committed[state.committed.length - 1] === "investigate" && state.terminalReason === "invalid")))
+      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 +509,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 +533,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 +608,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 +639,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 } });
 
@@ -572,7 +677,8 @@ export async function runIssue(opts) {
     // is seen), phase.id is "decompose" — not "investigate" — so this
     // exemption does not apply and the normal terminate() path below fires,
     // ending the run for real.
-    const isDecomposeHandoff = phase.id === "investigate" && terminalReason === "decomposed";
+    // build also hands off: the B5.5 size gate (NEEDS_DECOMPOSE) reports "decomposed".
+    const isDecomposeHandoff = (phase.id === "investigate" || phase.id === "build") && terminalReason === "decomposed";
     if (terminalReason && TERMINAL_REASONS.includes(terminalReason) &&
         !isDecomposeHandoff && !isRemediationHandoff)
       return await terminate(state, terminalReason, outcome.detail);
@@ -597,7 +703,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 +741,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 +776,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 +790,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).
@@ -704,8 +826,17 @@ function eventsFromIndex(idx) {
     const outputs = {};
     if (phase === "build" && idx.branch) outputs.branch = idx.branch;
     if (phase === "review" && idx.pr != null) outputs.pr = idx.pr;
+    if (phase === "review" && idx.remediationKind) outputs.remediation = idx.remediationKind;
     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/hooks/interactive-engine.mjs

@@ -116,6 +116,9 @@ const PHASE_MARKERS = [
  * @param {string} text
  * @returns {{ phaseId: string|null, terminalReason: string|null }}
  */
+// forge#3542: this scans a session TRANSCRIPT (tool results / assistant text), which carries no
+// comment authorship, so it is outside the headless engine's trusted + anchored marker model
+// (bin/engine/phases.mjs). Advisory phase detection only.
 export function detectPhaseFromText(text) {
   const str = typeof text === "string" ? text : "";
   let phaseId = null;

package/bin/labels.json

@@ -39,6 +39,11 @@
     "color": "5319E7",
     "description": "Pipeline: PR created, under review. Managed by ForgeDock."
   },
+  {
+    "name": "workflow:remediating",
+    "color": "C5DEF5",
+    "description": "Pipeline: autonomous remediation pending (no human action needed). Managed by ForgeDock."
+  },
   {
     "name": "workflow:awaiting-merge",
     "color": "FF8C00",

package/bin/orchestrate-preflight.mjs

@@ -16,7 +16,7 @@ import { fileURLToPath } from "node:url";
 import { classifyInputPattern } from "./engine/resolve.mjs";
 
 const VERSION = "opencode-preflight-v1";
-const IN_FLIGHT_LABELS = new Set(["workflow:building", "workflow:in-review"]);
+const IN_FLIGHT_LABELS = new Set(["workflow:building", "workflow:in-review", "workflow:remediating"]);
 const EXCLUDED_LABELS = new Set([
   "needs-human",
   "workflow:decomposed",

package/bin/runner.mjs

@@ -933,6 +933,71 @@ 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");
+// 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;
+}
+
+/**
+ * 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 +1017,19 @@ 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 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;
@@ -1036,19 +1113,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 +1345,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 +1483,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 +2471,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/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",
 ];