forgedock 1.26.0 → 1.28.0

package/bin/engine.mjs

@@ -13,6 +13,7 @@ import { pickPhase, TERMINAL_REASONS, issueSnapshot, hasInvestigationExit, postC
 import { reconcileState } from "./engine/reconcile.mjs";
 import { makeProjector } from "./engine/projector.mjs";
 import { VALID_BACKENDS, resolveRunTmpRoot, runTmpDir } from "./runner.mjs";
+import { resolveClaudeConfigDir } from "./journey.mjs";
 import { OUTCOME_CODES, UNCLASSIFIED, normalizeCode, codeForRunnerError, codeForTerminalReason, isDiskQuotaError, isDiskQuotaText, isTransientSpawnError } from "./engine/outcome-codes.mjs";
 
 // Exported (forge#2175) so bin/engine-cli.mjs can render "failed N/M attempts"
@@ -82,7 +83,10 @@ export function ciRateLimitSleepMs(rl, nowMs, rand = Math.random) {
  */
 export function backendIdentity({ backend, env = process.env } = {}) {
   const sha = (s) => createHash("sha256").update(String(s)).digest("hex");
-  const cfg = env.CLAUDE_CONFIG_DIR || `${homedir()}/.claude`;
+  // Shared resolver (forge#4173). The fallback keeps its legacy
+  // `${homedir()}/.claude` spelling so identities recorded before the shared
+  // resolver existed still match on Windows (path.join would use "\\").
+  const cfg = env.CLAUDE_CONFIG_DIR ? resolveClaudeConfigDir(env) : `${homedir()}/.claude`;
   const key = env.ANTHROPIC_API_KEY
     ? scryptSync(String(env.ANTHROPIC_API_KEY), "forgedock-backend-identity", 16).toString("hex") : "";
   return sha(JSON.stringify([backend ?? "auto", cfg, key])).slice(0, 16);
@@ -941,7 +945,7 @@ export async function runIssue(opts) {
         // "needs-human" — this is the engine/tool breaking, not a genuine
         // human-judgment block (see #2244/#2261). Any other thrown error is
         // a true unexpected crash and keeps propagating unchanged.
-        if (e.code === "NO_API_KEY" || e.code === "NO_SDK" || e.code === "CLI_BACKEND_FAILED" || e.code === "CLI_MAX_TURNS" || isDiskQuotaError(e)) {
+        if (e.code === "NO_API_KEY" || e.code === "NO_SDK" || e.code === "CLI_BACKEND_FAILED" || e.code === "CLI_BACKEND_UNAVAILABLE" || e.code === "CLI_MAX_TURNS" || isDiskQuotaError(e)) {
           // forge#2241: when the runner attached a session-limit reset time
           // (bin/runner.mjs's extractSessionLimitResetTime(), only ever set
           // for a genuine session-limit CLI_BACKEND_FAILED — never
@@ -1051,6 +1055,8 @@ export async function runIssue(opts) {
       usage: outcome.usage ?? null, last_attempt_usage: outcome.last_attempt_usage ?? null,
       // forge#3589: model + turn count per phase (null when the backend does not report them).
       model: outcome.model ?? null, turns: outcome.turns ?? null,
+      // forge#4257: the execution backend that ran the phase (null when unreported).
+      backend: outcome.backend ?? null,
       ...(commitReason ? { terminalReason: commitReason, code: commitCode } : {}),
     });
     state = deriveState(readLog(dir, issue));
@@ -1278,6 +1284,7 @@ async function runPhaseWithRetry(phase, state, ctx) {
       event: "PHASE_ATTEMPT_USAGE", phase: phase.id, attempt,
       usage: usage ?? null, duration_ms: Math.round(performance.now() - t0),
       cost_usd: extra?.cost_usd ?? null, model: extra?.model ?? null, turns: extra?.turns ?? null,
+      backend: extra?.backend ?? null,
     };
     appendEvent(dir, issue, rec);
     try { await emitTelemetry?.({ ...rec, issue }); } catch { /* telemetry never fails a phase */ }
@@ -1344,7 +1351,7 @@ async function runPhaseWithRetry(phase, state, ctx) {
         attempt--;
         continue;
       }
-      if (e.code === "NO_API_KEY" || e.code === "NO_SDK" || e.code === "CLI_BACKEND_FAILED") throw e;
+      if (e.code === "NO_API_KEY" || e.code === "NO_SDK" || e.code === "CLI_BACKEND_FAILED" || e.code === "CLI_BACKEND_UNAVAILABLE") throw e;
       // forge#2377: no `usage` field here — the runner threw, so no result
       // (and therefore no usage data) was ever produced for this attempt.
       // Do not fabricate a value; omitting the field (rather than a stale
@@ -1363,10 +1370,11 @@ async function runPhaseWithRetry(phase, state, ctx) {
     // forge#3589: model/turns recorded alongside usage (additive; null when absent).
     const lastModel = result?.cliModel ?? result?.model ?? null;
     const lastTurns = result?.turns ?? null;
+    const lastBackend = typeof result?.backend === "string" ? result.backend : null; // forge#4257
     addUsage(lastUsage);
-    await recordAttempt(attempt, lastUsage, t0, { cost_usd: result?.costUsd ?? null, model: lastModel, turns: lastTurns });
+    await recordAttempt(attempt, lastUsage, t0, { cost_usd: result?.costUsd ?? null, model: lastModel, turns: lastTurns, backend: lastBackend });
     const outcome = await phase.detectOutcome(state, io, result);
-    if (outcome.status === "committed" || outcome.status === "blocked") return { ...outcome, usage: cumulativeUsage, last_attempt_usage: lastUsage, model: lastModel, turns: lastTurns };
+    if (outcome.status === "committed" || outcome.status === "blocked") return { ...outcome, usage: cumulativeUsage, last_attempt_usage: lastUsage, model: lastModel, turns: lastTurns, backend: lastBackend };
     appendEvent(dir, issue, { event: "PHASE_FAILED", phase: phase.id, attempt, reason: outcome.detail, code: normalizeCode(outcome.code), maxAttempts, usage: lastUsage, model: lastModel, turns: lastTurns });
     // forge#2176: a phase's detectOutcome can mark a failure as a known,
     // state-derived fixed point — re-running the phase's runner is

package/bin/forgedock.mjs

@@ -34,6 +34,8 @@ import {
   writeInstallReceipt,
   persistHome,
   PIPELINE_SCRIPTS,
+  resolveClaudeConfigDir,
+  setupAfterRead,
 } from "./journey.mjs";
 import {
   deriveWorkflowLabels,
@@ -176,7 +178,14 @@ const HOME = process.env.HOME || process.env.USERPROFILE || homedir();
 // existing invocations, but it is now a no-op — global is the only supported
 // install location.
 
-const GLOBAL_CLAUDE_DIR = join(HOME, ".claude");
+//
+// The directory itself honours CLAUDE_CONFIG_DIR (forge#4173): Claude Code
+// reads commands/settings from there when it is set, so install, doctor,
+// status and uninstall all resolve it through the one shared helper the
+// journey installer uses — never a hard-coded ~/.claude.
+const GLOBAL_CLAUDE_DIR = resolveClaudeConfigDir(process.env, HOME);
+/** Display form of GLOBAL_CLAUDE_DIR for user-facing messages. */
+const CLAUDE_DIR_LABEL = GLOBAL_CLAUDE_DIR === join(HOME, ".claude") ? "~/.claude" : GLOBAL_CLAUDE_DIR;
 
 /**
  * Resolve the install target directories for the current invocation.
@@ -242,7 +251,7 @@ const restArgs = cmdIdx === -1 ? [] : rawArgs.slice(cmdIdx + 1).filter((a) => a
  * Path to the user-level Claude Code settings file.
  * This is where the SessionStart hook entry is written/removed.
  */
-const CLAUDE_SETTINGS_PATH = join(HOME, ".claude", "settings.json");
+const CLAUDE_SETTINGS_PATH = join(GLOBAL_CLAUDE_DIR, "settings.json");
 
 /**
  * Check whether a hook command string refers to the ForgeDock SessionStart hook.
@@ -1004,6 +1013,11 @@ async function statusScreen(c) {
  * otherwise falls back to the Anthropic API when ANTHROPIC_API_KEY is set,
  * otherwise skips enrichment.
  *
+ * Repository setup (forge#4173): after detection, interactive runs with no
+ * GitHub remote, no commits, or no `staging` branch are offered repo
+ * creation, an initial push of `main`, and `staging` creation — see
+ * journey.mjs setupRepo(). Non-TTY runs are unchanged.
+ *
  * Env:
  *   FORGEDOCK_INIT_BACKEND   Override ("cli"|"api"|"none"|"auto"; default
  *                            "auto") — pins the enrichment backend instead of
@@ -1042,7 +1056,7 @@ async function initFlow(c) {
     // Staging semantics preserved (#1148): detection → minimal template with
     // only the three required sections. No review screen — this is the
     // power-user escape hatch for a ~20-line forge.yaml.
-    const { draft, description } = await read(c);
+    const { draft, description } = await setupAfterRead(c, await read(c));
     // Hard-fail on unresolved identity placeholders when overwriting an
     // existing config (forge#1850 spec item 4) — never destroy a working
     // forge.yaml in favor of one that can't address a repo.
@@ -1071,7 +1085,7 @@ async function initFlow(c) {
 
   if (flags.includes("--manual")) {
     // Manual escape hatch: plain prompts, detection values as defaults.
-    const { draft, description } = await read(c);
+    const { draft, description } = await setupAfterRead(c, await read(c));
     const v = {
       owner: await input("GitHub owner", draft.project.owner.value),
       repo: await input("Repository", draft.project.repo.value),
@@ -1097,7 +1111,7 @@ async function initFlow(c) {
     await maybeOfferDemo(c);
     return 0;
   }
-  const { draft, description } = await read(c);
+  const { draft, description } = await setupAfterRead(c, await read(c));
   const reviewed = await review(c, draft, description);
   celebrate(c, reviewed);
   if (!reviewed.aborted) await maybeOfferDemo(c);
@@ -1110,7 +1124,7 @@ async function uninstall() {
   console.log("");
 
   const { targetDir, scriptsTargetDir, manifestPath } = detectInstallPaths();
-  console.log(`  Mode: global (~/.claude)`);
+  console.log(`  Mode: global (${CLAUDE_DIR_LABEL})`);
   console.log(`  ${dim(getLogoTagline("uninstall"))}`);
   console.log("");
 
@@ -1244,19 +1258,19 @@ async function uninstall() {
 
   // Remove the SessionStart hook from ~/.claude/settings.json via the
   // hardened settings-hook module (never writes through malformed JSON).
-  const settingsJsonPath = join(HOME, ".claude", "settings.json");
+  const settingsJsonPath = CLAUDE_SETTINGS_PATH;
   const { status: hookRemoveResult } = removeSessionStartHook(settingsJsonPath);
   if (hookRemoveResult === "removed") {
     console.log(
-      `  ${GREEN}✔${RESET}  Removed SessionStart hook from ${CYAN}~/.claude/settings.json${RESET}`,
+      `  ${GREEN}✔${RESET}  Removed SessionStart hook from ${CYAN}${CLAUDE_DIR_LABEL}/settings.json${RESET}`,
     );
   } else if (hookRemoveResult === "absent") {
     console.log(
-      `  ✔  SessionStart hook already absent from ~/.claude/settings.json`,
+      `  ✔  SessionStart hook already absent from ${CLAUDE_DIR_LABEL}/settings.json`,
     );
   } else {
     console.log(
-      `  ${YELLOW}⚠${RESET}  Could not update ~/.claude/settings.json — remove the hook manually.`,
+      `  ${YELLOW}⚠${RESET}  Could not update ${CLAUDE_DIR_LABEL}/settings.json — remove the hook manually.`,
     );
   }
 
@@ -1264,19 +1278,19 @@ async function uninstall() {
   // engine adapter, and SubagentStop annotation verifier.
   const { status: preToolUseRemoveResult } = removePreToolUseHook(settingsJsonPath);
   if (preToolUseRemoveResult === "removed") {
-    console.log(`  ${GREEN}✔${RESET}  Removed PreToolUse enforcement hook from ${CYAN}~/.claude/settings.json${RESET}`);
+    console.log(`  ${GREEN}✔${RESET}  Removed PreToolUse enforcement hook from ${CYAN}${CLAUDE_DIR_LABEL}/settings.json${RESET}`);
   } else if (preToolUseRemoveResult !== "absent") {
-    console.log(`  ${YELLOW}⚠${RESET}  Could not remove PreToolUse hook — check ${CYAN}~/.claude/settings.json${RESET} manually.`);
+    console.log(`  ${YELLOW}⚠${RESET}  Could not remove PreToolUse hook — check ${CYAN}${CLAUDE_DIR_LABEL}/settings.json${RESET} manually.`);
   }
   const { status: subagentStopRemoveResult } = removeSubagentStopHook(settingsJsonPath);
   if (subagentStopRemoveResult === "removed") {
-    console.log(`  ${GREEN}✔${RESET}  Removed SubagentStop hook from ${CYAN}~/.claude/settings.json${RESET}`);
+    console.log(`  ${GREEN}✔${RESET}  Removed SubagentStop hook from ${CYAN}${CLAUDE_DIR_LABEL}/settings.json${RESET}`);
   }
   const { status: subagentStopEnforceRemoveResult } = removeSubagentStopEnforceHook(settingsJsonPath);
   if (subagentStopEnforceRemoveResult === "removed") {
-    console.log(`  ${GREEN}✔${RESET}  Removed SubagentStop enforcement hook from ${CYAN}~/.claude/settings.json${RESET}`);
+    console.log(`  ${GREEN}✔${RESET}  Removed SubagentStop enforcement hook from ${CYAN}${CLAUDE_DIR_LABEL}/settings.json${RESET}`);
   } else if (subagentStopEnforceRemoveResult !== "absent") {
-    console.log(`  ${YELLOW}⚠${RESET}  Could not remove SubagentStop enforcement hook — check ${CYAN}~/.claude/settings.json${RESET} manually.`);
+    console.log(`  ${YELLOW}⚠${RESET}  Could not remove SubagentStop enforcement hook — check ${CYAN}${CLAUDE_DIR_LABEL}/settings.json${RESET} manually.`);
   }
   console.log("");
 
@@ -2111,6 +2125,44 @@ function resolveLabelsRepo(subArgs) {
   return null;
 }
 
+/** Fixed colors for well-known domain labels (forge#4174); anything else gets DOMAIN_LABEL_DEFAULT_COLOR. */
+const DOMAIN_LABEL_COLORS = {
+  frontend: "1D76DB",
+  backend: "0E8A16",
+  infra: "5319E7",
+  design: "D4C5F9",
+  "legal-gated": "B60205",
+};
+const DOMAIN_LABEL_DEFAULT_COLOR = "EDEDED";
+
+/**
+ * Parse a `--domain a,b,c` value into domain-label entries (forge#4174).
+ * Names are trimmed and deduped (first occurrence wins). An empty name, a name
+ * over 50 characters (GitHub's label-name limit), or a missing value is an
+ * error — the caller exits before any gh call.
+ *
+ * @param {string|undefined} raw - the value after --domain
+ * @returns {{ labels?: Array<{name: string, color: string, description: string}>, error?: string }}
+ */
+function buildDomainLabels(raw) {
+  if (raw === undefined || raw.startsWith("--")) return { error: "--domain needs a comma-separated list, e.g. --domain frontend,backend" };
+  const seen = new Set();
+  const labels = [];
+  for (const part of raw.split(",")) {
+    const name = part.trim();
+    if (!name) return { error: `--domain contains an empty label name: "${raw}"` };
+    if (name.length > 50) return { error: `--domain label name exceeds 50 characters: "${name}"` };
+    if (seen.has(name)) continue;
+    seen.add(name);
+    labels.push({
+      name,
+      color: DOMAIN_LABEL_COLORS[name] ?? DOMAIN_LABEL_DEFAULT_COLOR,
+      description: `Domain: ${name}. Managed by ForgeDock.`,
+    });
+  }
+  return { labels };
+}
+
 /**
  * Idempotently create or update all ForgeDock-managed labels on a GitHub repo.
  *
@@ -2122,10 +2174,15 @@ function resolveLabelsRepo(subArgs) {
  * --force makes the call idempotent: it creates the label if absent, or updates
  * its color and description if it already exists. Safe to re-run at any time.
  *
+ * Optional per-repo domain labels (forge#4174) are appended after the
+ * manifest — see buildDomainLabels(). They are never part of bin/labels.json,
+ * so doctor's required-label check ignores them.
+ *
  * @param {string} repo - "owner/repo" string
+ * @param {Array<{name: string, color: string, description: string}>} [domainLabels]
  * @returns {{ created: number, failed: string[] }}
  */
-async function labelsSetup(repo) {
+async function labelsSetup(repo, domainLabels = []) {
   const manifestPath = join(__dirname, "labels.json");
 
   if (!existsSync(manifestPath)) {
@@ -2141,6 +2198,8 @@ async function labelsSetup(repo) {
     console.log(`${RED}Failed to parse labels.json: ${err.message}${RESET}`);
     process.exit(1);
   }
+  const manifestNames = new Set(labels.map((l) => l.name));
+  labels = labels.concat(domainLabels.filter((l) => !manifestNames.has(l.name)));
 
   console.log("");
   console.log(`${BOLD}ForgeDock Label Bootstrap${RESET}`);
@@ -2210,7 +2269,7 @@ async function labelsSetup(repo) {
  *   2.  gh CLI installed and authenticated
  *   3.  git configured (user.name + user.email)
  *   4.  forge.yaml exists and has required keys
- *   5.  SessionStart hook registered in ~/.claude/settings.json
+ *   5.  SessionStart hook registered in ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR)
  *   6.  CLAUDE.md legacy managed block (cwd) — informational only; the
  *       journey install never injects one, session context comes from the
  *       SessionStart hook
@@ -2247,7 +2306,7 @@ async function doctor(fix = false) {
   console.log(
     isGitCloneInstall
       ? `  Mode: git clone at ${CYAN}${FORGE_HOME}${RESET}`
-      : `  Mode: global (~/.claude)`,
+      : `  Mode: global (${CLAUDE_DIR_LABEL})`,
   );
   console.log(`  Source: ${formatSourceIdentity(sourceBranch)}`);
   console.log("");
@@ -2301,7 +2360,7 @@ async function doctor(fix = false) {
     console.log(`  ${CYAN}↻${RESET}  ${BOLD}${label}${RESET}${suffix}`);
   }
 
-  const settingsPath = join(HOME, ".claude", "settings.json");
+  const settingsPath = CLAUDE_SETTINGS_PATH;
 
   /**
    * Detect whether the registered SessionStart hook entry (if any) points at
@@ -2671,17 +2730,17 @@ async function doctor(fix = false) {
     }
 
     if (hookReg.error) {
-      fail("SessionStart hook", `Cannot read ~/.claude/settings.json: ${hookReg.error}. Run: npx forgedock install`);
+      fail("SessionStart hook", `Cannot read ${CLAUDE_DIR_LABEL}/settings.json: ${hookReg.error}. Run: npx forgedock install`);
     } else if (hookReg.ok) {
       if (fix && hookRegWasBroken) {
-        fixed("SessionStart hook", "registered in ~/.claude/settings.json (repaired)");
+        fixed("SessionStart hook", `registered in ${CLAUDE_DIR_LABEL}/settings.json (repaired)`);
       } else {
-        pass("SessionStart hook", "registered in ~/.claude/settings.json");
+        pass("SessionStart hook", `registered in ${CLAUDE_DIR_LABEL}/settings.json`);
       }
     } else {
       fail(
         "SessionStart hook",
-        "Run: npx forgedock doctor --fix  (or: npx forgedock install)  (writes hook entry to ~/.claude/settings.json)",
+        `Run: npx forgedock doctor --fix  (or: npx forgedock install)  (writes hook entry to ${CLAUDE_DIR_LABEL}/settings.json)`,
       );
     }
   }
@@ -3007,7 +3066,7 @@ async function doctor(fix = false) {
   // server presence is orthogonal to the core ForgeDock install — but missing
   // it causes /qa-sweep to silently fail mid-sweep.
   {
-    const mcpServersPath = join(HOME, ".claude", "mcp_servers.json");
+    const mcpServersPath = join(GLOBAL_CLAUDE_DIR, "mcp_servers.json");
     let playwrightFound = false;
     let fileReadable = false;
     let hasMcpServers = false;
@@ -3040,12 +3099,12 @@ async function doctor(fix = false) {
     if (!fileReadable) {
       warn(
         "Playwright MCP",
-        "No MCP servers file found (~/.claude/mcp_servers.json). Register Playwright MCP to enable /qa-sweep: claude mcp add playwright npx @playwright/mcp@latest",
+        `No MCP servers file found (${CLAUDE_DIR_LABEL}/mcp_servers.json). Register Playwright MCP to enable /qa-sweep: claude mcp add playwright npx @playwright/mcp@latest`,
       );
     } else if (!hasMcpServers) {
       warn(
         "Playwright MCP",
-        "MCP servers file found (~/.claude/mcp_servers.json) but it has no 'mcpServers' key. Register Playwright MCP to enable /qa-sweep: claude mcp add playwright npx @playwright/mcp@latest",
+        `MCP servers file found (${CLAUDE_DIR_LABEL}/mcp_servers.json) but it has no 'mcpServers' key. Register Playwright MCP to enable /qa-sweep: claude mcp add playwright npx @playwright/mcp@latest`,
       );
     } else if (playwrightFound) {
       pass("Playwright MCP", "registered in Claude Code MCP servers");
@@ -3172,6 +3231,26 @@ async function doctor(fix = false) {
     );
   }
 
+  // ── Check 13: Resource hygiene (#4183) ──────────────────────────────────────
+  // Owned leftovers (stale lane ledgers, forgedock-labelled docker, lean-*/agent-* worktrees, lane branches,
+  // ~/.forge/tmp scratch) with counts and sizes; unowned stale ones are only reported. --fix runs the reaper with the
+  // forge.yaml hygiene TTLs. Never a failure: a leftover slows the host, it does not break the install.
+  {
+    try {
+      const gc = await import("./gc.mjs");
+      const probes = gc.makeGcProbes({ cwd: process.cwd() });
+      const h = gc.readHygiene(process.cwd());
+      const plan = await gc.planGc({ probes, ttlMs: gc.hygieneTtls(h), deleteMergedBranches: h.delete_merged_branches });
+      const applied = fix ? await gc.applyGc(plan, probes) : null;
+      if (applied && applied.reclaimed.length > 0) fixesApplied++;
+      const r = gc.hygieneCheck(plan, { applied });
+      if (r.status === "pass") pass("Resource hygiene", r.detail);
+      else warn("Resource hygiene", r.detail);
+    } catch (e) {
+      warn("Resource hygiene", `could not inspect ForgeDock leftovers: ${String(e?.message ?? e).slice(0, 200)}`);
+    }
+  }
+
   // ── Summary ────────────────────────────────────────────────────────────────
   console.log("");
   if (fix && fixesApplied > 0) {
@@ -3207,20 +3286,24 @@ 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 bootstrap <idea|docs> [--dry-run] [--spike <path>] | --plan <plan.json> [--dry-run]", "Headless /bootstrap: idea to orchestrate-ready backlog (--dry-run previews milestones, titles, DAG and estimated agent cost without GitHub writes); --plan validates and creates (or previews) a plan, and re-running resumes from GitHub"],
     ["npx forgedock run-issue <issue> [--lane <lane>] [--lane-override] [--path core|full] [--retry] [--wait-lease]", "Run the lean core work-on on one issue (default; --path full = legacy multi-phase pipeline; the lane comes from the issue: milestone → milestone/<slug>, else staging; --lane is an assertion, never the default branch) (--retry reopens an engine-error run, or a needs-human run once the label is cleared; --wait-lease waits for a held lease; exit 75 = deferred, lease held)"],
     ["npx forgedock orchestrate <issue...> [--parallel K] [--lane L]", "Run core work-on on several issues with bounded concurrency and Depends-on ordering; each issue on its own lane, cross-lane dependencies reported"],
-    ["npx forgedock orchestrate --resume <id> | --set-parallel <id> K", "Continue a batch after the dispatcher died (live lanes re-adopted), or change its concurrency live"],
+    ["npx forgedock orchestrate --resume <id> | --set-parallel <id> K", "Reattach to a batch hosted by the schedd daemon (a finished one replays its report, an orphaned one is resumed with live lanes re-adopted), or change its concurrency live"],
     ["npx forgedock triage <issue...> [--lane L] [--dry-run]", "Already-fixed pre-filter: close issues a merged PR or green CI already resolved; print the rest"],
-    ["npx forgedock gc", "Prune stale per-run scratch dirs under ~/.forge/tmp/runs (older than 6h, owner dead)"],
+    ["npx forgedock limits show | clear <id>|--all", "Show or clear per-account usage-limit holds shared by orchestrate batches"],
+    ["npx forgedock sched show | cap <N>|--clear | weight <owner/repo> <N>|--clear", "Show the host lane registry, set the host-wide lane cap shared by orchestrate batches, or set a repo's share of slots within a priority (default equal)"],
+    ["npx forgedock schedd [status]", "Host scheduler daemon hosting every orchestrate batch (auto-spawned by orchestrate; run in the foreground for a systemd-user unit); status shows its pid and batches"],
+    ["npx forgedock gc [--apply] [--older-than 6h] [--docker] [--worktrees] [--branches] [--tmp] [--processes] [--sandboxes]", "Report (dry-run default) and reclaim ForgeDock-owned leftovers: stale lane ledgers, forgedock-labelled containers/volumes, lean-*/agent-* worktrees, abandoned lane branches, ~/.forge/tmp scratch, orphaned lane processes, orphaned lane sandboxes; unowned resources and unpushed work are only reported"],
     ["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)"],
+    ["npx forgedock labels [setup] [--repo owner/repo] [--domain a,b,c]", "Bootstrap ForgeDock-managed labels on a GitHub repo, plus optional per-repo domain labels (idempotent)"],
     ["npx forgedock config migrate [dir]", "Backfill missing optional sections into an existing forge.yaml (idempotent)"],
     ["npx forgedock watch [--repo owner/repo]", "Live per-agent orchestration view (Ctrl+C to exit)"],
     ["npx forgedock report [--days 30] [--md] [--json]", "30-day pipeline impact receipts for your repo"],
     ["npx forgedock stats [--since <ver|date>] [--repo owner/repo] [--json] [--refresh]", "Version-over-version cost/time/flow/review/gate report from GitHub telemetry (no model)"],
     ["npx forgedock doctor", "Check installation health"],
-    ["npx forgedock doctor --fix", "Auto-fix deterministic issues (symlinks, hook, labels, legacy block)"],
+    ["npx forgedock doctor --fix", "Auto-fix deterministic issues (symlinks, hook, labels, legacy block) and reclaim ForgeDock-owned leftovers (forge.yaml hygiene TTLs)"],
     ["npx forgedock update", "Pull latest & reinstall"],
     ["npx forgedock uninstall", "Remove commands"],
     ["npx forgedock opencode install", "Install token-efficient native OpenCode commands"],
@@ -3785,10 +3868,10 @@ async function watch() {
 // The journey-routed commands render their own branded marks (hero/compact);
 // splash() would double-brand them. Engine-surface commands, help, and
 // unknown-command output keep the logo.
-const SPLASH_COMMANDS = new Set(["run", "run-issue", "orchestrate", "triage", "gc", "resume-stalled", "demo", "doctor", "watch", "help", "--help", "-h"]);
+const SPLASH_COMMANDS = new Set(["run", "bootstrap", "run-issue", "orchestrate", "triage", "gc", "resume-stalled", "demo", "doctor", "watch", "help", "--help", "-h"]);
 const KNOWN_COMMANDS = new Set([
   "install", "init", "enable", "disable", "status", "uninstall", "update",
-  "run", "backend-check", "run-issue", "orchestrate", "triage", "gc", "resume-stalled", "demo", "doctor", "watch", "labels", "config", "stats", "help", "--help", "-h",
+  "run", "bootstrap", "backend-check", "run-issue", "orchestrate", "triage", "gc", "resume-stalled", "demo", "doctor", "watch", "labels", "config", "stats", "limits", "sched", "schedd", "help", "--help", "-h",
   "version", "--version", "-v",
 ]);
 if (SPLASH_COMMANDS.has(command) || !KNOWN_COMMANDS.has(command)) splash(command);
@@ -3945,6 +4028,18 @@ switch (command) {
   case "run":
     await run();
     break;
+  case "bootstrap": {
+    // #4177: headless /bootstrap; --plan runs scripts/bootstrap-create.mjs directly (no LLM), a re-run resumes.
+    const { runBootstrap } = await import("./bootstrap.mjs");
+    try {
+      const { runCommand } = await import("./runner.mjs");
+      exitCode = await runBootstrap(restArgs, { runCommand, commandsDir: COMMANDS_DIR });
+    } catch (err) {
+      process.stderr.write(`${RED}${err.message}${RESET}\n`);
+      exitCode = 1;
+    }
+    break;
+  }
   case "backend-check": {
     // Exit codes: 0 = ready, 1 = no usable backend, 2 = bad usage (unknown option).
     // Only --quiet is accepted; anything else is a usage error so callers can tell a
@@ -3987,10 +4082,9 @@ switch (command) {
     break;
   }
   case "gc": {
-    // Best-effort prune of core-run scratch dirs (older than 6h, owner pid dead). Never touches dirs we did not create.
-    const { makeRunTmp } = await import("./lean/effects.mjs");
-    const removed = await makeRunTmp().prune();
-    process.stdout.write(`gc: removed ${removed.length} stale run tmp dir(s)\n`);
+    // Reaper (#4180): dry-run report by default; --apply reclaims only ForgeDock-owned resources (ledger, label, lane naming, own tmp).
+    const { runGc } = await import("./gc.mjs");
+    exitCode = await runGc(restArgs);
     break;
   }
   case "orchestrate": {
@@ -4004,6 +4098,37 @@ switch (command) {
     }
     break;
   }
+  case "limits": {
+    const { limitsFromCli } = await import("./engine-cli.mjs");
+    try {
+      await limitsFromCli(restArgs);
+    } catch (err) {
+      process.stderr.write(`${RED}${err.message}${RESET}\n`);
+      exitCode = 1;
+    }
+    break;
+  }
+  case "schedd": {
+    // #4192: the host scheduler daemon; runs until idle or SIGTERM. Lanes are detached and survive it.
+    const { scheddFromCli } = await import("./engine-cli.mjs");
+    try {
+      await scheddFromCli(restArgs);
+    } catch (err) {
+      process.stderr.write(`${RED}${err.message}${RESET}\n`);
+      exitCode = 1;
+    }
+    break;
+  }
+  case "sched": {
+    const { schedFromCli } = await import("./engine-cli.mjs");
+    try {
+      await schedFromCli(restArgs);
+    } catch (err) {
+      process.stderr.write(`${RED}${err.message}${RESET}\n`);
+      exitCode = 1;
+    }
+    break;
+  }
   case "triage": {
     const { triageFromCli } = await import("./engine-cli.mjs");
     try {
@@ -4048,19 +4173,24 @@ switch (command) {
     const subcommand = positional[1];
     if (!subcommand || subcommand === "setup" || subcommand.startsWith("--")) {
       const repo = resolveLabelsRepo(restArgs);
-      if (!repo) {
+      const domainIdx = restArgs.indexOf("--domain");
+      const domain = domainIdx === -1 ? { labels: [] } : buildDomainLabels(restArgs[domainIdx + 1]);
+      if (domain.error) {
+        console.log(`${RED}${domain.error}${RESET}`);
+        exitCode = 1;
+      } else if (!repo) {
         console.log(
           `${RED}No repository specified.${RESET}\n` +
             `  Pass ${cyan("--repo owner/repo")} or run from a directory with ${cyan("forge.yaml")}.`,
         );
         exitCode = 1;
       } else {
-        await labelsSetup(repo);
+        await labelsSetup(repo, domain.labels);
       }
     } else {
       console.log(`${RED}Unknown labels subcommand: ${subcommand}${RESET}`);
       console.log(
-        `Usage: ${CYAN}npx forgedock labels [setup] [--repo owner/repo]${RESET}`,
+        `Usage: ${CYAN}npx forgedock labels [setup] [--repo owner/repo] [--domain a,b,c]${RESET}`,
       );
       exitCode = 1;
     }