forgedock 1.0.22 → 1.1.1

package/bin/runner.mjs

@@ -338,6 +338,31 @@ function resolveConfinedPath(cwd, p) {
     );
   }
 
+  // Residual TOCTOU assumption: we return the lexical `resolved` path rather
+  // than `realResolved` so that callers (readFileSync / writeFileSync) work
+  // correctly with not-yet-existing paths (where realResolved === resolved
+  // anyway, since there is nothing to dereference).  The check above verified
+  // confinement on the realpath of the nearest *existing* ancestor, but a
+  // concurrent actor that mutates the filesystem between this check and the
+  // caller's open() call could in theory introduce a symlink that evades the
+  // guard — a classic time-of-check / time-of-use (TOCTOU) window.
+  //
+  // This is acceptable under the current threat model because:
+  //   1. Tool calls are executed in a strictly sequential, synchronous
+  //      `for...of` loop (see the runLive tool-use loop).  There is no async
+  //      gap and no concurrent tool execution within the runner itself.
+  //   2. A prompt-injected model therefore cannot create this race — it would
+  //      need to schedule two tool calls simultaneously, which the loop
+  //      prevents.
+  //   3. Only an independent, external OS process running concurrently could
+  //      exploit the window, which is outside the stated single-shot
+  //      prompt-injection threat model.
+  //
+  // If the runner is ever refactored to execute tool calls concurrently or
+  // asynchronously, this assumption MUST be revisited.  Mitigations to
+  // consider at that point include: operating on `realResolved` directly
+  // (eliminating the lexical/realpath split), or opening the file with an
+  // O_NOFOLLOW-equivalent flag so the kernel rejects a symlink at open time.
   return resolved;
 }
 
@@ -539,31 +564,48 @@ export function getToolHandlers(cwd) {
       // available. `shell: shell || true` preserves execSync's implicit
       // "always run via a shell" behavior for compound commands (&&, pipes,
       // heredocs) when resolveBashShell() returns undefined.
+      // maxBuffer defaults to 50 MB. FORGEDOCK_MAX_BUFFER_BYTES overrides it so
+      // tests can trigger ENOBUFS with a small value without generating 50 MB of
+      // output.  Non-positive or non-finite values fall back to the default.
+      const rawMaxBuffer = parseInt(process.env.FORGEDOCK_MAX_BUFFER_BYTES, 10);
+      const maxBuffer =
+        Number.isFinite(rawMaxBuffer) && rawMaxBuffer > 0
+          ? rawMaxBuffer
+          : 50 * 1024 * 1024;
       const result = spawnSync(command, {
         cwd,
         encoding: "utf-8",
-        maxBuffer: 50 * 1024 * 1024,
+        maxBuffer,
         timeout: timeoutMs,
         env: childEnv,
         shell: shell || true,
       });
       const stdout = result.stdout ? String(result.stdout) : "";
       const stderr = result.stderr ? String(result.stderr) : "";
-      // Detect timeout: result.error.code === "ETIMEDOUT" and/or
-      // result.signal === "SIGTERM" are the primary indicators (set by
-      // Node.js when the timeout fires and the process is killed), but on
-      // Windows signal reporting may not be reliable. Fall back to elapsed
-      // wall time — if we spent at least as long as the timeout, the timer
-      // must have fired, since a voluntarily-exiting process would have
-      // returned before then. Gate all of this on `result.status === null`
-      // so a legitimately-completed process near the timeout boundary is
-      // never misreported as timed out.
+      // Detect timeout. Two reliable indicators:
+      //   1. result.error.code === "ETIMEDOUT" — Node sets this on the error
+      //      object specifically when spawnSync's own `timeout` option fires
+      //      and it kills the child. This is the authoritative Node-initiated
+      //      kill signal.
+      //   2. elapsedMs >= timeoutMs — elapsed-wall-time fallback for platforms
+      //      (primarily Windows) where the ETIMEDOUT error code is unreliable.
+      //      If we spent at least as long as the timeout, the timer must have
+      //      fired, since a voluntarily-exiting process would have returned
+      //      before then.
+      //
+      // NOTE: `result.signal === "SIGTERM"` is intentionally NOT included.
+      // spawnSync sets result.signal for ANY signal that terminated the child —
+      // including SIGTERM from external sources (supervisors, orchestrators,
+      // `timeout(1)` wrappers, or the child self-signaling) that are entirely
+      // unrelated to this runner's timeout. Including it caused any externally-
+      // sent SIGTERM to be misreported as a ForgeDock timeout (issue #1240).
+      //
+      // Gate all of this on `result.status === null` so a legitimately-
+      // completed process near the timeout boundary is never misreported.
       const elapsedMs = Date.now() - startMs;
       const timedOut =
         result.status === null &&
-        (result.error?.code === "ETIMEDOUT" ||
-          result.signal === "SIGTERM" ||
-          elapsedMs >= timeoutMs);
+        (result.error?.code === "ETIMEDOUT" || elapsedMs >= timeoutMs);
       if (timedOut) {
         const timeoutSecs = Math.round(timeoutMs / 1000);
         const partial = (stdout + stderr).trim();
@@ -573,6 +615,18 @@ export function getToolHandlers(cwd) {
             (partial ? `\nPartial output:\n${partial}` : ""),
         );
       }
+      if (result.error?.code === "ENOBUFS") {
+        // The process ran but produced more output than maxBuffer allows.
+        // spawnSync populates result.stdout/stderr up to the limit before
+        // setting result.error — surface what was captured so the agent has
+        // actionable context rather than a misleading "failed to start" error.
+        const partial = (stdout + stderr).trim();
+        const bufMB = Math.round(maxBuffer / (1024 * 1024));
+        throw new Error(
+          `Command output exceeded ${bufMB}MB buffer limit (output truncated).` +
+            (partial ? `\nPartial output:\n${partial}` : ""),
+        );
+      }
       if (result.error) {
         // spawnSync-level failure to even launch the process (e.g. ENOENT
         // for a missing shell binary) — distinct from a nonzero exit status
@@ -701,6 +755,19 @@ export async function runCommand(opts = {}) {
   }
 
   const client = new Anthropic({ apiKey });
+  // NOTE on /proc/$PPID/environ (Linux): deleting from process.env calls
+  // unsetenv() at the C level, which does NOT update the kernel's
+  // /proc/<pid>/environ snapshot (that is fixed at execve() time). A
+  // run_bash payload can still read /proc/$PPID/environ and recover the
+  // key if it was set in the shell environment before the node process
+  // started. The only effective JavaScript-layer mitigation is the
+  // child-env scrub in run_bash: `childEnv = {...process.env}; delete
+  // childEnv.ANTHROPIC_API_KEY` — this prevents the child from inheriting
+  // the key in its own process.env, which is sufficient for
+  // `process.env.ANTHROPIC_API_KEY` access. The /proc/$PPID/environ vector
+  // is a known Linux limitation at the OS level; closing it would require
+  // a native module (e.g. prctl PR_SET_DUMPABLE) or process isolation.
+  // See: issue #1370 for tracking this known limitation.
   const handlers = getToolHandlers(cwd);
   const messages = [{ role: "user", content: userMessage }];
 

package/bin/settings-hook.mjs

@@ -0,0 +1,112 @@
+/**
+ * bin/settings-hook.mjs — Idempotent SessionStart hook registration in
+ * ~/.claude/settings.json.
+ *
+ * Contract (spec: "Hook wiring"):
+ *   - Read-modify-write; unrelated keys and hooks preserved verbatim
+ *   - Our entry identified by HOOK_MARKER in its command string
+ *   - Malformed JSON → skip and report, NEVER overwrite the file
+ *   - Absolute hook script path baked in at install time
+ */
+
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "fs";
+import { dirname } from "path";
+
+/** Substring identifying ForgeDock's own hook entry. */
+export const HOOK_MARKER = "session-start.mjs";
+
+function isOurs(entry) {
+  return JSON.stringify(entry).includes(HOOK_MARKER);
+}
+
+function readSettings(settingsPath) {
+  if (!existsSync(settingsPath)) return { settings: {}, fresh: true };
+  try {
+    const parsed = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    return { settings: parsed, fresh: false };
+  } catch {
+    return null; // malformed — caller must not write
+  }
+}
+
+function writeSettings(settingsPath, settings) {
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  const tmp = settingsPath + ".tmp";
+  writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+  renameSync(tmp, settingsPath);
+}
+
+/**
+ * Merge ForgeDock's SessionStart hook into settings.json.
+ * @param {string} settingsPath - Absolute path to ~/.claude/settings.json
+ * @param {string} hookScriptPath - Absolute path to bin/hooks/session-start.mjs
+ * @returns {{ status: 'installed'|'already'|'skipped-malformed' }}
+ */
+export function installSessionStartHook(settingsPath, hookScriptPath) {
+  const read = readSettings(settingsPath);
+  if (read === null) return { status: "skipped-malformed" };
+  const { settings } = read;
+
+  // Validate hooks shape: must be a plain object (not array, string, etc.)
+  if (settings.hooks !== undefined && settings.hooks !== null) {
+    if (Array.isArray(settings.hooks) || typeof settings.hooks !== "object") {
+      return { status: "skipped-malformed" };
+    }
+    // Validate SessionStart if present: must be an array
+    if (settings.hooks.SessionStart !== undefined && !Array.isArray(settings.hooks.SessionStart)) {
+      return { status: "skipped-malformed" };
+    }
+  } else {
+    // hooks missing or null → initialize to fresh object
+    settings.hooks = {};
+  }
+
+  const list = Array.isArray(settings.hooks.SessionStart) ? settings.hooks.SessionStart : [];
+  if (list.some(isOurs)) return { status: "already" };
+
+  list.push({
+    hooks: [
+      {
+        type: "command",
+        command: `node "${hookScriptPath}"`,
+      },
+    ],
+  });
+  settings.hooks.SessionStart = list;
+  writeSettings(settingsPath, settings);
+  return { status: "installed" };
+}
+
+/**
+ * Remove ForgeDock's SessionStart hook entry; leaves everything else alone.
+ * @returns {{ status: 'removed'|'absent'|'skipped-malformed' }}
+ */
+export function removeSessionStartHook(settingsPath) {
+  const read = readSettings(settingsPath);
+  if (read === null) return { status: "skipped-malformed" };
+  const { settings, fresh } = read;
+  if (fresh) return { status: "absent" };
+
+  // Validate hooks shape: must be a plain object (not array, string, etc.)
+  if (settings.hooks !== undefined && settings.hooks !== null) {
+    if (Array.isArray(settings.hooks) || typeof settings.hooks !== "object") {
+      return { status: "skipped-malformed" };
+    }
+  }
+
+  // Validate SessionStart shape if present: must be an array
+  if (settings.hooks && settings.hooks.SessionStart !== undefined && !Array.isArray(settings.hooks.SessionStart)) {
+    return { status: "skipped-malformed" };
+  }
+
+  const list = settings.hooks && Array.isArray(settings.hooks.SessionStart)
+    ? settings.hooks.SessionStart
+    : [];
+  const kept = list.filter((e) => !isOurs(e));
+  if (kept.length === list.length) return { status: "absent" };
+
+  settings.hooks.SessionStart = kept;
+  writeSettings(settingsPath, settings);
+  return { status: "removed" };
+}

package/bin/tui.mjs

@@ -837,7 +837,7 @@ const REVIEW_FIELDS = [
  */
 export async function annotatedReviewScreen(
   draft,
-  { hasExistingConfig = false, existingContent = "", showSources = false } = {},
+  { hasExistingConfig = false, existingContent = "", showSources = false, extraFields = {} } = {},
 ) {
   // Helper — pull a field from the draft by path, or return a low-confidence placeholder.
   function getField(draftPath) {
@@ -862,7 +862,10 @@ export async function annotatedReviewScreen(
   const whys = {};
 
   for (const fd of REVIEW_FIELDS) {
-    const field = getField(fd.draftPath);
+    const field =
+      fd.draftPath === null && extraFields[fd.key]
+        ? extraFields[fd.key]
+        : getField(fd.draftPath);
     values[fd.key] = field.value;
     confidences[fd.key] = field.confidence;
     sources[fd.key] = field.source;
@@ -987,7 +990,7 @@ export async function annotatedReviewScreen(
     }
 
     process.stdout.write(
-      `  ${dim("Press")} ${bold("Enter")} ${dim("to accept all values, or enter a field number to edit it.")}\n\n`,
+      `  ${dim("Press")} ${bold("Enter")} ${dim("to forge, or a number to edit a field")}\n\n`,
     );
   }
 

package/commands/autopilot.md

@@ -10,7 +10,7 @@ argument-hint: [--fix | --recon-only | --fix --limit 5 | --dry-run]
 **Config variables used by this command** (set in `forge.yaml`):
 - `{CREDENTIALS_FILE}` ← `paths.credentials.file` (optional) — path to credentials YAML for analytics APIs
 - `{SERVER_SSH}` ← `services.server_ssh` (optional) — SSH target for production server health checks (e.g., `ubuntu@1.2.3.4`)
-- `{EMEMO_PATH}` ← `services.ememo_path` (optional) — path on production server to open eMemo files
+- `{OPS_INBOX_PATH}` ← `services.ops_inbox_path` (optional) — path on production server to a directory of open work-item files (e.g. `/srv/ops/inbox`)
 - `{BILLING_ENABLED}` ← `billing.enabled` (optional, default `false`) — set to `true` to enable Stripe data collection in the Analytics Snapshot agent
 
 Resolve `{BILLING_ENABLED}` from `forge.yaml` before executing any phase:
@@ -112,7 +112,7 @@ Spawn these as **background agents** (all `run_in_background=true`, all `model="
 **Agent: Production Health**
 ```
 Check production system health:
-1. SSH to check for open eMemos: if {SERVER_SSH} is configured, run: ssh {SERVER_SSH} "ls {EMEMO_PATH}/*-open-* 2>/dev/null" — skip this step if SERVER_SSH or EMEMO_PATH is not set in forge.yaml
+1. SSH to check for open ops-inbox items: if {SERVER_SSH} is configured, run: ssh {SERVER_SSH} "ls {OPS_INBOX_PATH}/*-open-* 2>/dev/null" — skip this step if SERVER_SSH or OPS_INBOX_PATH is not set in forge.yaml
 2. If any exist, cat each one and summarize
 3. Check container health via MCP: get_production_status, run_production_health_check
 4. Check recent error logs: get_production_logs for api and worker (last 100 lines), grep for ERROR/CRITICAL
@@ -197,7 +197,7 @@ For each finding from RECON_DATA, assign:
 
 | Signal | Priority | Type |
 |--------|----------|------|
-| Production eMemo (open) | P1 | bug |
+| Open ops-inbox item | P1 | bug |
 | Container unhealthy | P0 | bug |
 | Error spike (>5x normal) | P1 | bug |
 | Tier degradation (>20% drop) | P2 | bug |
@@ -286,7 +286,7 @@ Print a structured report:
 
 ### Production Health
 - Containers: {all healthy / N unhealthy}
-- Open eMemos: {count}
+- Open ops-inbox items: {count}
 - Error patterns: {summary or "none"}
 
 ### Scraping Performance

package/commands/deploy-info.md

@@ -156,7 +156,7 @@ done
 # Full file diff summary
 git diff --stat origin/$TARGET..origin/$SOURCE
 
-# Read layout paths from forge.yaml, fall back to AlterLab defaults
+# Read layout paths from forge.yaml, fall back to forge.yaml defaults
 LAYOUT_API=$(yq '.review.layout.api // "services/api"' forge.yaml 2>/dev/null || echo "services/api")
 LAYOUT_WORKER=$(yq '.review.layout.worker // "services/worker"' forge.yaml 2>/dev/null || echo "services/worker")
 LAYOUT_PAGES=$(yq '.review.layout.pages // "web/src/app"' forge.yaml 2>/dev/null || echo "web/src/app")
@@ -231,8 +231,10 @@ if [ -n "$NEW_ENV" ]; then
   # If your project uses a different backend, skip this block and verify manually.
   if [ "{DEPLOY_SECRETS_BACKEND}" = "sops" ]; then
     for var in $(echo "$NEW_ENV" | grep -oE '^\+[A-Z_]+' | sed 's/^\+//'); do
-      if ! grep -q "$var" scripts/decrypt-secrets.sh 2>/dev/null; then
-        echo "  ❌ $var NOT in decrypt-secrets.sh ENV_MAPPING"
+      if [ -f "{REPO_PATH}/scripts/decrypt-secrets.sh" ]; then
+        grep -q "$var" "{REPO_PATH}/scripts/decrypt-secrets.sh" 2>/dev/null || echo "  ❌ $var NOT in decrypt-secrets.sh ENV_MAPPING"
+      else
+        echo "  ℹ️  scripts/decrypt-secrets.sh not found — skipping ENV_MAPPING cross-check for $var. Verify manually in your SOPS chain."
       fi
     done
   else

package/commands/design-bench.md

@@ -1,6 +1,7 @@
 ---
 description: Run the ABC benchmark — reference URL → design-blind brief → render arms A/B/C → blind judge → scorecard with win-rates over n runs
 argument-hint: [<brief-name>|all] [--n <runs>] [--corpus-version <ver>]
+install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

package/commands/design-render-critique-loop.md

@@ -1,6 +1,7 @@
 ---
 description: Render a design from its FORGE:DESIGN_SPEC, critique the rendered pixels against the perceptual negatives, and iterate until it passes or the budget is spent — the missing reward signal.
 argument-hint: [<issue-number>|<spec-path>] [--max-iters <n>] [--viewports desktop,mobile]
+install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

package/commands/design.md

@@ -1,6 +1,7 @@
 ---
 description: Route a design GitHub issue through the UI Taste Harness — investigate → architect → implement → critique loop → user-feedback loop → close — accumulating FORGE:DESIGN_* annotations and driving the design:* label state machine to design:shipped.
 argument-hint: <issue-number> | <brief-name>
+install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

package/commands/forge-stats.md

@@ -1,6 +1,7 @@
 ---
 description: Track command sizes, detect bloat, compare against baselines and thresholds
 argument-hint: [diff | baseline | full]
+install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

package/commands/issue.md

@@ -495,7 +495,7 @@ Create all {N} issues? (yes / adjust #N / cancel)
 
 | Bad Issue | Why It Fails | Good Version |
 |-----------|-------------|-------------|
-| "Fix docker mount" | Which compose file? Which mount? | "fix: `.gemini` volume mount in docker-compose.prod.yml missing rw flag" |
+| "Fix docker mount" | Which compose file? Which mount? | "fix: `logs` volume in docker-compose.yml missing `rw` flag — container writes fail at runtime" |
 | "Update billing" | What about billing? What's broken? | "fix: payment_processor.charge() raises ZeroDivisionError when amount == 0" |
 | "Investigate performance" | Investigate what? Where? | "investigate: API p95 latency doubled since last deploy — trace hot paths in job processing routers" |
 | No affected files listed | Investigator guesses wrong files | List every file with what needs to change |

package/commands/orchestrate.md

@@ -519,9 +519,11 @@ When two issues modify different files that **import from the same utility/init
 | Pattern | Inference | Action |
 |---------|-----------|--------|
 | Issue A modifies `routers/billing.py`, Issue B modifies `routers/auth.py` | Both likely import from `routers/__init__.py` or `dependencies.py` | Flag as possible conflict if same service |
-| Issue A modifies `models/user.py`, Issue B modifies `models/subscription.py` | Both likely modify `models/__init__.py` (SQLAlchemy model registry) | Flag as probable conflict → serialize |
+| Issue A modifies `models/user.py`, Issue B modifies `models/subscription.py` *(Python/SQLAlchemy example)* | Both likely modify `models/__init__.py` (model registry) | Flag as probable conflict → serialize |
+| Issue A modifies `routes/users.js`, Issue B modifies `routes/billing.js` *(Node.js example)* | Both likely import from `routes/index.js` barrel | Flag as possible conflict if same service |
+| Issue A modifies `internal/user/handler.go`, Issue B modifies `internal/billing/handler.go` *(Go example)* | Both likely register in `internal/router/router.go` | Flag as possible conflict if same service |
 | Issue A modifies `web/src/components/X.tsx`, Issue B modifies `web/src/components/Y.tsx` | May share `index.ts` barrel export | Flag only if same parent directory |
-| Issue A modifies `services/api/app/main.py` | `main.py` is a high-fan-in file (router registration, middleware) | Serialize with ANY other API issue |
+| Issue A modifies the app entrypoint (e.g. `main.py`, `main.go`, `server.js`, `app.ts`) | Entrypoint is a high-fan-in file (router registration, middleware) — set the path via `forge.yaml → review.layout.api_main` | Serialize with ANY other same-service issue |
 | Issue A modifies `docker-compose.yml` or `docker-compose.prod.yml` | Global config — any concurrent modification conflicts | Serialize with ALL other issues that touch infra |
 
 **Apply inferences:**
@@ -529,14 +531,14 @@ When two issues modify different files that **import from the same utility/init
 # High-fan-in files — if ANY issue touches these, serialize it with all same-service issues.
 # Read layout paths from forge.yaml review.layout; fall back to sensible generic defaults.
 # Example (pseudo-code — adapt to your forge.yaml parsing method):
-#   API_MAIN    = forge_yaml.review.layout.api_main    ?? "services/api/app/main.py"
-#   WORKER_MAIN = forge_yaml.review.layout.worker_main ?? "services/worker/worker/main.py"
-#   PAGES_ROOT  = forge_yaml.review.layout.pages       ?? "web/src/app"
+#   API_MAIN    = forge_yaml.review.layout.api_main    ?? "src/main.py"   # set in forge.yaml; no stack-specific default
+#   WORKER_MAIN = forge_yaml.review.layout.worker_main ?? "src/worker.py" # set in forge.yaml; no stack-specific default
+#   PAGES_ROOT  = forge_yaml.review.layout.pages       ?? "web/src/app"   # Next.js default; override in forge.yaml for other frameworks
 
 HIGH_FAN_IN = [
-  API_MAIN,                          # e.g. "services/api/app/main.py" — router/middleware registration
-  WORKER_MAIN,                       # e.g. "services/worker/worker/main.py" — worker entrypoint (set forge.yaml review.layout.worker_main)
-  PAGES_ROOT + "/layout.tsx",        # e.g. "web/src/app/layout.tsx" — root layout for all pages
+  API_MAIN,                          # app entrypoint — router/middleware registration (set forge.yaml review.layout.api_main)
+  WORKER_MAIN,                       # worker entrypoint (set forge.yaml review.layout.worker_main)
+  PAGES_ROOT + "/layout.tsx",        # root layout for all pages (Next.js; adapt for your framework)
   "docker-compose.yml",
   "docker-compose.prod.yml",
   ".env.example"
@@ -570,13 +572,17 @@ Layers 1-4 infer conflict risk from structure — path overlap, directory nestin
 # argument below — a plain string here would be word-split and glob-expanded
 # by the shell when handed to `git log --`, silently mangling or dropping any
 # path containing a space or glob metacharacter.
-mapfile -t ALL_AFFECTED_FILES < <(printf '%s\n' "${LAYER1_FILES[@]}" | sort -u)
+mapfile -t ALL_AFFECTED_FILES < <(printf '%s\n' "${LAYER1_FILES[@]}" | sort -u | grep -v '^$')
 
 # Guard: an empty array expands to nothing after `--`, which git interprets as
 # "no pathspec restriction" (i.e. the whole repo) rather than "match nothing".
 # Skip the query entirely in that case instead of letting it silently widen to
 # a full-repo scan — this can happen when upstream file-extraction (Layer 1)
 # yields zero paths for every issue in the batch.
+# NOTE: `grep -v '^$'` above is required — without it, `printf '%s\n'` on an
+# empty array emits one blank line (printf runs its format string once even
+# with zero variadic args), which `mapfile` captures as a 1-element array of
+# [""], making this guard evaluate to false and causing `git log -- ""` to run.
 if [ "${#ALL_AFFECTED_FILES[@]}" -eq 0 ]; then
   echo "Layer 5: no affected files extracted by Layer 1 for this batch — skipping co-change query, falling back to Layers 1-4."
 else
@@ -834,6 +840,18 @@ Proceed? (yes / adjust / pick specific issues)
 
 ---
 
+## Engine mode (headless)
+
+When running headless/CI, dispatch each issue via the durable execution engine instead of spawning prose agents:
+
+```bash
+forgedock run-issue <issue> --lane <staging|milestone/slug>
+```
+
+The engine drives every phase transition deterministically, mirrors state to the `FORGE:STATE` block on the issue, and holds a lease. To recover stalls, scan in-flight issues' `FORGE:STATE`; any issue with an expired lease and a non-terminal state is re-dispatched with the same `forgedock run-issue <issue>` command — it resumes from the last committed phase (idempotent). This replaces the label-heuristic "already in progress" check and the resume-with-nagging loop.
+
+---
+
 ## Phase 4: Streaming DAG Execution
 
 ### Step 4A-pre: Staging baseline tracking (MANDATORY — continuous)