@aion0/forge 0.8.8 → 0.9.0

package/cli/mw.ts

@@ -1,4 +1,3 @@
-#!/usr/bin/env -S npx tsx
 /**
  * forge — Forge CLI
  *

package/components/SettingsModal.tsx

@@ -203,6 +203,7 @@ interface Settings {
   telegramModel: string;
   skipPermissions: boolean;
   notificationRetentionDays: number;
+  maxConcurrentPipelines: number;
   _secretStatus?: Record<string, boolean>;
 }
 
@@ -230,6 +231,7 @@ export default function SettingsModal({ onClose }: { onClose: () => void }) {
     telegramModel: 'sonnet',
     skipPermissions: false,
     notificationRetentionDays: 30,
+    maxConcurrentPipelines: 5,
   });
   const [secretStatus, setSecretStatus] = useState<Record<string, boolean>>({});
   const [newRoot, setNewRoot] = useState('');
@@ -520,6 +522,30 @@ export default function SettingsModal({ onClose }: { onClose: () => void }) {
           </div>
         </div>
 
+        {/* Pipeline concurrency cap */}
+        <div className="space-y-2">
+          <label className="text-xs text-[var(--text-secondary)] font-semibold uppercase">
+            Pipeline concurrency
+          </label>
+          <div className="flex items-center gap-2">
+            <span className="text-[10px] text-[var(--text-secondary)]">Max concurrent pipelines</span>
+            <select
+              value={settings.maxConcurrentPipelines || 5}
+              onChange={e => setSettings({ ...settings, maxConcurrentPipelines: Number(e.target.value) })}
+              className="text-xs bg-[var(--bg-tertiary)] border border-[var(--border)] rounded px-2 py-1 text-[var(--text-primary)]"
+            >
+              {[1, 2, 3, 5, 8, 10, 15, 20].map(n => (
+                <option key={n} value={n}>{n}</option>
+              ))}
+            </select>
+          </div>
+          <p className="text-[10px] text-[var(--text-secondary)] leading-snug">
+            Global cap on running + pending pipelines (cancels new Job dispatches when reached;
+            the items roll over to the next tick). Per-Job <code>max_per_tick</code> (default 5, capped 10)
+            stacks on top.
+          </p>
+        </div>
+
         {/* Remote Access (Cloudflare Tunnel) */}
         <div className="space-y-2">
           <label className="text-xs text-[var(--text-secondary)] font-semibold uppercase">

package/lib/help-docs/19-jobs.md

@@ -13,6 +13,11 @@ Job is a separate primitive from Task and Pipeline. The CLI keeps
 `forge task` (single agent invocation) and `forge pipeline` (DAG of tasks)
 unchanged. `forge jobs` is new.
 
+> **Tip**: for common watchers (GitLab MR comments, Mantis bugs) prefer
+> **From recipe…** in the Jobs form — it pre-fills source connector,
+> dedup field, and pipeline wiring so you only fill 3-4 high-level
+> params. See `22-recipes.md` for the catalog.
+
 ## Anatomy
 
 | Field | Purpose |

package/lib/help-docs/22-recipes.md

@@ -0,0 +1,124 @@
+# Recipes & GitLab MR auto-fix
+
+A **Recipe** is a parameterized template for a Job + its dispatched pipeline. Instead of hand-filling 12 fields in the Jobs form, you pick a recipe, fill 3-4 high-level params, and Forge instantiates the rest.
+
+Recipes live under `~/.forge/data/recipes/*.yaml`. The canonical catalog is `aiwatching/forge-workflow` on GitHub; Marketplace ↓ Sync pulls the latest registry.
+
+## Built-in recipes
+
+| Name | What it does | Source tool |
+|---|---|---|
+| `gitlab-mr-watch` | Watch ONE specific MR for new review comments → run `mr-review-fix` | `gitlab.get_mr` |
+| `gitlab-my-mrs-watch` | Watch all MRs assigned to you → run `mr-review-fix` per MR | `gitlab.list_my_mrs` |
+| `mantis-bug-fix` | Manual fire — fix a single Mantis bug → run `mantis-bug-fix-and-mr` | `mantis.get_bug` |
+| `mantis-bug-watch` | Periodic — fix bugs matching a filter | `mantis.search_bugs` |
+
+## Creating a Job from a recipe
+
+Extension → Jobs tab → **+ From recipe…** → pick one → fill the form → Create.
+
+For `gitlab-mr-watch` you fill:
+- **Local project name** (picks a directory under `projectRoots`)
+- **MR URL** — paste the full URL like `https://gitlab.example.com/namespace/repo/-/merge_requests/123`. Forge auto-extracts namespace/repo + iid.
+- **Poll interval** (minutes, default 5)
+- **Triage policy** (free-form, optional — ships with a sensible default)
+
+## Special param types
+
+- `project_picker` — dropdown of dirs under your configured `projectRoots`
+- `gitlab_mr_url` — single MR URL; Forge parses out `<name>__path` (`namespace/repo`) + `<name>__iid` (numeric iid) at instantiation time. Reference them in templates via `{{params.mr_url__path}}` / `{{params.mr_url__iid}}`.
+- `number` — coerces string → number
+- `boolean` — coerces truthy strings
+
+## The `mr-review-fix` pipeline — 5 nodes
+
+1. **ingest** (shell, no worktree) — `glab api` pulls MR meta + ALL notes + diff into `/tmp/mr-<iid>-*.{json,txt}`. Emits `SOURCE_BRANCH`, `MR_TITLE`, `MR_AUTHOR`, `LATEST_COMMENTER`, file paths.
+2. **triage** (AI, no worktree, no shell) — reads all notes holistically, decides action.
+3. **fix** (AI, branch `mr-<iid>` worktree) — runs the git work only on ACT path.
+4. **reply** (shell) — posts a comment on the MR describing the outcome; adds a label; closes the MR if needed.
+5. **cleanup** (shell) — Teams notify + worktree removal + tmp file cleanup.
+
+### Four triage actions
+
+| ACTION | Meaning | Reply posted? | Label | MR state |
+|---|---|---|---|---|
+| `act`   | Comments name a concrete fix → apply it | yes (with diff summary) | `forge:fix-applied` | push fixup to source_branch |
+| `skip`  | Substantive but no change needed (lgtm, nits, questions) | yes (explanation) | `forge:no-fix-needed` | unchanged |
+| `close` | MR itself shouldn't merge (duplicate, wrong direction, already-fixed-elsewhere) | yes (rationale) | `forge:no-merge` | **closed** via `glab api PUT state_event=close` |
+| `noop`  | Latest non-system comment is Forge's own or this Job's user → nothing changed since last run | **no** (silent) | none | unchanged |
+
+The `noop` case is the loop-breaker. Without it, Forge's auto-reply bumps `user_notes_count`, the next tick sees a new state, fires again, posts another reply — endless self-conversation.
+
+### Required GitLab labels (one-time)
+
+Create these in **GitLab → Project → Labels → New label** (any colors):
+
+```
+forge:fix-applied      (suggest green)
+forge:no-fix-needed    (suggest blue)
+forge:no-merge         (suggest red)
+```
+
+If a label is missing, the label-add step logs a failure but the rest of the pipeline still runs.
+
+### Triage prompt — when to customize
+
+The recipe ships with a default `triage_instructions` covering common cases. Overwrite when you need project-specific rules. Examples:
+
+```
+Only act if the reviewer is from team @backend. Skip everything else.
+```
+
+```
+Act ONLY on Code Review Bot 'error' findings; skip all human comments.
+```
+
+```
+Treat any comment containing "MUST" as actionable; everything else SKIP.
+```
+
+Keep the noop clause at the bottom of any custom policy:
+
+```
+NOOP when the latest non-system comment is authored by @<your-username>
+or starts with '🤖 Forge:'.
+```
+
+## Per-MR vs per-comment dispatch
+
+Older recipe versions used `gitlab.list_mr_notes` and fired ONE pipeline per new comment — 50 historical comments on first Fire meant 50 pipelines. Current recipes use `gitlab.get_mr` + dedup on `user_notes_count`:
+
+- Fetches the MR object once; scheduler wraps as 1-item list
+- `user_notes_count` only changes when comments are added/removed → label flips, status changes, assignee changes don't false-trigger
+- First Fire registers the current count as "seen" via `__mark_existing_as_seen: true` — no backfill stampede
+
+## Marketplace ↔ local copy split
+
+- **Marketplace** (Settings → Marketplace → Templates → Recipes / Pipelines) lists ONLY items from the registry (`forge-workflow` repo). Editing-by-hand or "Import as new copy" workflows don't appear here.
+- **Pipelines tab** lists ALL local workflow yamls — registry-sourced installs, your custom edits, anything in `~/.forge/data/flows/`.
+- **Reinstall** button overwrites a local copy with the current registry version (use after a version bump).
+- Local copies are **independent** of marketplace — Forge will never silently overwrite a local file you've edited.
+
+## Cleanup recipes
+
+```bash
+# Delete a Job + its dedup state + any pending pipeline runs
+sqlite3 ~/.forge/data/workflow.db <<'SQL'
+DELETE FROM jobs WHERE name='mr-watch-FortiNAC-14636';
+DELETE FROM job_dedup_keys WHERE job_id NOT IN (SELECT id FROM jobs);
+DELETE FROM pipelines WHERE workflow_name='mr-review-fix' AND status IN ('pending','running');
+SQL
+
+# Force re-trigger on next tick — clears dedup so any state looks "new"
+sqlite3 ~/.forge/data/workflow.db "DELETE FROM job_dedup_keys WHERE job_id IN (SELECT id FROM jobs WHERE source_tool='get_mr');"
+```
+
+## Where things live on disk
+
+| Path | Purpose |
+|---|---|
+| `~/.forge/data/recipes/*.yaml` | Local recipe copies |
+| `~/.forge/data/flows/*.yaml` | Local workflow copies (mr-review-fix, mantis-bug-fix-and-mr, custom) |
+| `~/.forge/data/workflow.db` | Job rows, dedup keys, run history |
+| `~/.forge/data/pipelines/*.json` | Per-run state for each pipeline execution |
+| `~/.forge/data/workflow-cache.json` | Last-synced registry from `forge-workflow` repo |

package/lib/help-docs/CLAUDE.md

@@ -51,6 +51,7 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 | `18-chrome-mcp.md` | Connect Forge Claude Code sessions to a real Chrome via chrome-devtools-mcp — dev-time browser access for connector authoring |
 | `19-jobs.md` | Jobs — scheduled connector polls that dedup and fan out to Pipeline / Chat |
 | `20-mantis-bug-fix.md` | Mantis → Bug Fix → MR builtin pipeline (mantis-bug-fix-and-mr) |
+| `22-recipes.md` | Recipes (parameterized Job templates) + the `mr-review-fix` pipeline — gitlab_mr_url param, 4-action triage (act/skip/close/noop), GitLab label setup, per-MR vs per-comment dispatch, Marketplace ↔ local-copy split |
 
 ## Matching questions to docs
 
@@ -81,3 +82,4 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 - Chrome MCP / chrome-devtools-mcp / dev-time browser / CDP / remote debugging → `18-chrome-mcp.md`
 - Job / scheduled job / connector poll / dedup / periodic fetch / Teams poll / Mantis bug poll → `19-jobs.md`
 - Mantis bug fix pipeline / mantis-bug-fix-and-mr / open MR for Mantis bug / notify Teams from pipeline / connector-tool endpoint → `20-mantis-bug-fix.md`
+- Recipe / parameterized job / "From recipe" form / mr-review-fix / MR review auto-fix / triage instructions / act vs skip vs close vs noop / forge:no-fix-needed / forge:no-merge label / gitlab_mr_url param / per-MR vs per-comment / Marketplace local-only filter → `22-recipes.md`

package/lib/jobs/recipes.ts

@@ -40,7 +40,7 @@ import { getDataDir } from '../dirs';
 import { createJob } from './store';
 import type { Job, PipelineDispatchParams, ChatDispatchParams } from './types';
 
-export type ParamType = 'string' | 'number' | 'boolean' | 'select' | 'project_picker' | 'gitlab_mr_url';
+export type ParamType = 'string' | 'number' | 'boolean' | 'select' | 'project_picker' | 'gitlab_mr_url' | 'csv_ids';
 
 export interface RecipeParam {
   name: string;
@@ -164,7 +164,23 @@ function renderString(input: string, ctx: RenderContext): string {
 
 function renderDeep(value: any, ctx: RenderContext): any {
   if (value == null) return value;
-  if (typeof value === 'string') return renderString(value, ctx);
+  if (typeof value === 'string') {
+    // When the WHOLE string is one placeholder like "{{params.foo}}"
+    // AND it resolves to a non-string (array / object / number),
+    // return the typed value directly instead of JSON-stringifying.
+    // Lets a recipe plug an array into source_input.items, etc.
+    const single = value.trim().match(/^\{\{\s*([a-zA-Z0-9_]+)\.([a-zA-Z0-9_.]+)\s*\}\}$/);
+    if (single && KNOWN_NAMESPACES.has(single[1])) {
+      const root: any = (ctx as any)[single[1]];
+      let cur: any = root;
+      for (const seg of single[2].split('.')) {
+        if (cur == null || typeof cur !== 'object') { cur = undefined; break; }
+        cur = cur[seg];
+      }
+      if (cur !== undefined && typeof cur !== 'string') return cur;
+    }
+    return renderString(value, ctx);
+  }
   if (Array.isArray(value)) return value.map((v) => renderDeep(v, ctx));
   if (typeof value === 'object') {
     const out: Record<string, any> = {};
@@ -218,6 +234,18 @@ export function instantiateRecipe(name: string, rawParams: Record<string, any>):
       }
       params[`${p.name}__path`] = m[1];
       params[`${p.name}__iid`] = parseInt(m[2], 10);
+    } else if (p.type === 'csv_ids' && val !== '') {
+      // Comma-separated numeric ids → derived `<name>__items` array of
+      // `{ id }` objects, suitable as a Job's source_input.items for
+      // an `inline` source. Lets a batch recipe ask the user "give me
+      // a list of bug ids" and have the scheduler iterate without
+      // needing a per-connector transformer tool.
+      const ids = String(val).split(',').map(s => s.trim()).filter(Boolean)
+        .map(s => parseInt(s, 10)).filter(Number.isFinite);
+      if (ids.length === 0) {
+        return { ok: false, error: `param "${p.name}" must be a comma-separated list of numeric ids — got: ${String(val).slice(0, 80)}` };
+      }
+      params[`${p.name}__items`] = ids.map(id => ({ id }));
     }
     params[p.name] = val;
   }
@@ -252,6 +280,9 @@ export function instantiateRecipe(name: string, rawParams: Record<string, any>):
       dispatch_type: rendered.dispatch_type || 'pipeline',
       dispatch_params: (rendered.dispatch_params || {}) as PipelineDispatchParams | ChatDispatchParams,
       skills: Array.isArray(rendered.skills) ? rendered.skills : [],
+      max_per_tick: typeof rendered.max_per_tick === 'number'
+        ? rendered.max_per_tick
+        : (rendered.max_per_tick != null && rendered.max_per_tick !== '' ? Number(rendered.max_per_tick) : undefined),
     });
     return { ok: true, job };
   } catch (e) {

package/lib/jobs/scheduler.ts

@@ -9,11 +9,39 @@
 
 import {
   ensureSchema, getDueJobs, hasInflightRun, startRun, finishRun,
-  markSeen, recordDispatch, getJob, updateJob,
+  markSeen, isSeen, recordDispatch, getJob, updateJob,
 } from './store';
 import type { Job, JobRunStatus, PipelineDispatchParams, ChatDispatchParams } from './types';
 import { dispatchTool } from '@/lib/chat/tool-dispatcher';
 import { dispatchToPipeline, dispatchToChat, dispatchToChatSummary } from './dispatcher';
+import { getDb } from '@/src/core/db/database';
+import { getDbPath } from '@/src/config';
+
+/** Count pipelines currently running or pending. Used as the global
+ *  concurrency budget — paired with settings.maxConcurrentPipelines. */
+function countActivePipelines(): number {
+  try {
+    const r = getDb(getDbPath()).prepare(
+      `SELECT COUNT(*) AS n FROM pipeline_runs WHERE status IN ('running', 'pending')`,
+    ).get() as { n: number } | undefined;
+    return r?.n ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** Read settings.maxConcurrentPipelines (default 5, ceiling 20). */
+async function getMaxConcurrentPipelines(): Promise<number> {
+  try {
+    const { loadSettings } = await import('@/lib/settings');
+    const s = loadSettings();
+    const v = (s as any).maxConcurrentPipelines;
+    if (!Number.isFinite(v)) return 5;
+    return Math.min(Math.max(Math.trunc(v), 1), 20);
+  } catch {
+    return 5;
+  }
+}
 
 const TICK_INTERVAL_MS = 60_000;
 
@@ -166,32 +194,43 @@ export async function executeRun(job: Job, runId: string): Promise<void> {
     const { __mark_existing_as_seen, ...sourceInput } = job.source_input as any;
     logLine('info', `tick start trigger=${(__mark_existing_as_seen ? 'backfill' : 'normal')} dispatch=${job.dispatch_type}`);
     logLine('info', `source input: ${JSON.stringify(sourceInput)}`);
-    logLine('info', `calling connector ${callName}…`);
-
-    const toolResult = await dispatchTool(
-      { id: `job-${runId}`, name: callName, input: sourceInput },
-      // We JSON.parse the response — the 8KB LLM-friendly truncation
-      // would break parsing on any moderately large list (Todos, big MR
-      // searches, etc.). Ask for the raw body.
-      { noTruncation: true },
-    );
-
-    const respBytes = toolResult.content?.length ?? 0;
-    logLine(toolResult.is_error ? 'error' : 'info',
-      `connector returned ${toolResult.is_error ? 'is_error=true ' : ''}${respBytes} bytes`);
-    logLine('info', `response preview:\n${truncate(toolResult.content || '(empty)', 600)}`, false);
-
-    if (toolResult.is_error) {
-      throw new Error(`connector ${callName} failed: ${toolResult.content.slice(0, 500)}`);
-    }
 
-    // ── Parse + extract items ────────────────────────────────────
-    const parsed = safeParseJson(toolResult.content);
-    if (parsed === undefined) {
-      const note = `Connector returned non-JSON content (${respBytes} bytes). Preview: ${toolResult.content.slice(0, 200)}`;
-      logLine('warn', note);
-      persist({ status: 'ok', notes: note });
-      return;
+    // ── Source path A: inline ───────────────────────────────────
+    // When source_connector === 'inline', the recipe / Job baked the
+    // items list directly into source_input.items at instantiation —
+    // no tool dispatch, no extension round-trip. Common case: a
+    // user-typed list of ids being fanned out into pipeline runs.
+    // Skips the entire dispatchTool / JSON parse layer.
+    let parsed: unknown;
+    let respBytes = 0;
+    if (job.source_connector === 'inline') {
+      logLine('info', `inline source — skipping tool dispatch`);
+      parsed = { items: Array.isArray(sourceInput.items) ? sourceInput.items : [] };
+      respBytes = JSON.stringify(parsed).length;
+    } else {
+      logLine('info', `calling connector ${callName}…`);
+      const toolResult = await dispatchTool(
+        { id: `job-${runId}`, name: callName, input: sourceInput },
+        // We JSON.parse the response — the 8KB LLM-friendly truncation
+        // would break parsing on any moderately large list (Todos, big MR
+        // searches, etc.). Ask for the raw body.
+        { noTruncation: true },
+      );
+      respBytes = toolResult.content?.length ?? 0;
+      logLine(toolResult.is_error ? 'error' : 'info',
+        `connector returned ${toolResult.is_error ? 'is_error=true ' : ''}${respBytes} bytes`);
+      logLine('info', `response preview:\n${truncate(toolResult.content || '(empty)', 600)}`, false);
+
+      if (toolResult.is_error) {
+        throw new Error(`connector ${callName} failed: ${toolResult.content.slice(0, 500)}`);
+      }
+      parsed = safeParseJson(toolResult.content);
+      if (parsed === undefined) {
+        const note = `Connector returned non-JSON content (${respBytes} bytes). Preview: ${toolResult.content.slice(0, 200)}`;
+        logLine('warn', note);
+        persist({ status: 'ok', notes: note });
+        return;
+      }
     }
     logLine('info', `parsed JSON; type=${Array.isArray(parsed) ? 'array' : typeof parsed}`);
 
@@ -291,7 +330,25 @@ export async function executeRun(job: Job, runId: string): Promise<void> {
     }
 
     // ── Per-item dispatch ────────────────────────────────────────
-    let dedupHits = 0, missingKey = 0;
+    //
+    // Two budgets gate dispatch:
+    //   (a) Per-Job `max_per_tick` (default 5, capped 1-10) — how many
+    //       NEW items this job is allowed to fan out per tick. Anything
+    //       over that stays unmarked → rolls over to next tick.
+    //   (b) Global concurrent-pipeline cap (settings.maxConcurrentPipelines,
+    //       default 5, max 20) — counted across ALL running/pending
+    //       pipelines, not just this job's. Prevents one job from
+    //       monopolizing all slots.
+    // Why both: a single job with max_per_tick=10 can still go over if
+    // there are already 15 pipelines from OTHER jobs in flight.
+    const budget = (() => {
+      const v = (job as any).max_per_tick;
+      if (!Number.isFinite(v) || v == null) return 5;
+      return Math.min(Math.max(Math.trunc(v), 1), 10);
+    })();
+    const globalCap = await getMaxConcurrentPipelines();
+    let dispatchedThisTick = 0;
+    let dedupHits = 0, missingKey = 0, deferred = 0;
     for (const [idx, item] of itemsArr.entries()) {
       const key = pickDedupKey(item, job.dedup_field);
       if (!key) {
@@ -299,14 +356,31 @@ export async function executeRun(job: Job, runId: string): Promise<void> {
         logLine('warn', `[${idx}] item missing dedup_field "${job.dedup_field}" — skipping`);
         continue;
       }
-      const isNew = markSeen(job.id, key);
-      if (!isNew) {
+      // Read-only dedup check — don't mark yet, in case we hit budget.
+      if (isSeen(job.id, key)) {
         dedupHits++;
-        // Don't mirror to console — too chatty in the typical "0 new" case
         logLine('info', `[${idx}] ${key} — already seen, skip`, false);
         continue;
       }
+      // Per-Job budget?
+      if (dispatchedThisTick >= budget) {
+        deferred++;
+        continue;
+      }
+      // Global cap? Re-check each iteration since other jobs' pipelines
+      // may finish or new ones start while we loop.
+      if (job.dispatch_type === 'pipeline') {
+        const inFlight = countActivePipelines();
+        if (inFlight >= globalCap) {
+          deferred++;
+          logLine('info', `[${idx}] ${key} — global pipeline cap (${globalCap}) reached; deferring to next tick`);
+          continue;
+        }
+      }
+      // OK to commit dedup + dispatch.
+      markSeen(job.id, key);
       itemsNew++;
+      dispatchedThisTick++;
       const preview = renderItemPreview(item);
       logLine('info', `[${idx}] ${key} — new — dispatching ${job.dispatch_type}…`);
       const dispatchStart = Date.now();
@@ -359,7 +433,11 @@ export async function executeRun(job: Job, runId: string): Promise<void> {
       else if (missingKey === itemsSeen) note = `All ${itemsSeen} items lacked the dedup_field "${job.dedup_field}". Check the field name vs the connector's response shape.`;
     }
 
-    logLine('info', `tick done in ${Date.now() - t0}ms — ${itemsSeen} seen, ${itemsNew} new, ${itemsDispatched} dispatched, ${dedupHits} dedup hits` + (missingKey ? `, ${missingKey} missing-key` : ''));
+    if (deferred > 0) {
+      const baseNote = note ? note + ' ' : '';
+      note = `${baseNote}${deferred} item(s) deferred to next tick (per-Job budget ${budget} or global cap ${globalCap} reached).`;
+    }
+    logLine('info', `tick done in ${Date.now() - t0}ms — ${itemsSeen} seen, ${itemsNew} new, ${itemsDispatched} dispatched, ${dedupHits} dedup hits` + (deferred ? `, ${deferred} deferred` : '') + (missingKey ? `, ${missingKey} missing-key` : ''));
     persist({ status: 'ok', notes: note });
   } catch (e) {
     runError = e instanceof Error ? e.message : String(e);

package/lib/jobs/store.ts

@@ -40,6 +40,12 @@ export function ensureSchema(): void {
       schedule_kind               TEXT NOT NULL DEFAULT 'period',
       schedule_at                 TEXT,
       schedule_cron               TEXT,
+      /** Per-tick dispatch budget. The scheduler dispatches at most
+          this many NEW items per run; the rest stay unmarked and get
+          picked up on the next tick. Hard ceiling enforced in code
+          to protect against catastrophic fan-out (e.g. mantis search
+          returning 200 bugs and spawning 200 worktrees). */
+      max_per_tick                INTEGER NOT NULL DEFAULT 5,
       last_run_at                 TEXT,
       next_run_at                 TEXT,
       created_at                  TEXT NOT NULL DEFAULT (datetime('now')),
@@ -88,6 +94,7 @@ export function ensureSchema(): void {
   try { db().exec(`ALTER TABLE jobs ADD COLUMN schedule_kind TEXT NOT NULL DEFAULT 'period'`); } catch {}
   try { db().exec(`ALTER TABLE jobs ADD COLUMN schedule_at TEXT`); } catch {}
   try { db().exec(`ALTER TABLE jobs ADD COLUMN schedule_cron TEXT`); } catch {}
+  try { db().exec(`ALTER TABLE jobs ADD COLUMN max_per_tick INTEGER NOT NULL DEFAULT 5`); } catch {}
   ensured = true;
 }
 
@@ -110,6 +117,7 @@ function rowToJob(r: any): Job {
     schedule_kind: (r.schedule_kind as 'period' | 'once' | 'cron' | 'manual') || 'period',
     schedule_at: toIsoUTC(r.schedule_at),
     schedule_cron: r.schedule_cron || null,
+    max_per_tick: typeof r.max_per_tick === 'number' ? r.max_per_tick : 5,
     last_run_at: toIsoUTC(r.last_run_at),
     next_run_at: toIsoUTC(r.next_run_at),
     created_at: toIsoUTC(r.created_at) || r.created_at,
@@ -167,6 +175,16 @@ export function getJob(id: string): Job | null {
   return r ? rowToJob(r) : null;
 }
 
+/** Per-tick dispatch budget — clamped [1, 10]. Centralized so the
+ *  ceiling is one constant, not duplicated across createJob/updateJob/
+ *  scheduler. Catastrophic fan-out (mantis returns 200 bugs → 200
+ *  worktrees → disk full) was the motivating incident. */
+export const MAX_PER_TICK_CEILING = 10;
+function clampMaxPerTick(v: number | undefined): number {
+  if (!Number.isFinite(v) || v == null) return 5;
+  return Math.min(Math.max(Math.trunc(v as number), 1), MAX_PER_TICK_CEILING);
+}
+
 export function createJob(input: CreateJobInput): Job {
   ensureSchema();
   const id = randomUUID().slice(0, 12);
@@ -175,8 +193,8 @@ export function createJob(input: CreateJobInput): Job {
       source_connector, source_tool, source_input,
       items_path, dedup_field,
       dispatch_type, dispatch_params, skills,
-      schedule_kind, schedule_at, schedule_cron)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      schedule_kind, schedule_at, schedule_cron, max_per_tick)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(
     id,
     input.name,
@@ -193,6 +211,7 @@ export function createJob(input: CreateJobInput): Job {
     input.schedule_kind || 'period',
     input.schedule_at || null,
     input.schedule_cron || null,
+    clampMaxPerTick(input.max_per_tick),
   );
 
   // Backfill guard: if mark_existing_as_seen is true (default), we don't pre-seed
@@ -232,6 +251,7 @@ export function updateJob(id: string, patch: Partial<{
   schedule_kind: 'period' | 'once' | 'cron' | 'manual';
   schedule_at: string | null;
   schedule_cron: string | null;
+  max_per_tick: number;
 }>): boolean {
   ensureSchema();
   const sets: string[] = []; const vals: any[] = [];
@@ -249,6 +269,7 @@ export function updateJob(id: string, patch: Partial<{
   if (patch.schedule_kind !== undefined) { sets.push('schedule_kind = ?'); vals.push(patch.schedule_kind); }
   if (patch.schedule_at !== undefined) { sets.push('schedule_at = ?'); vals.push(patch.schedule_at); }
   if (patch.schedule_cron !== undefined) { sets.push('schedule_cron = ?'); vals.push(patch.schedule_cron); }
+  if (patch.max_per_tick !== undefined) { sets.push('max_per_tick = ?'); vals.push(clampMaxPerTick(patch.max_per_tick)); }
   if (sets.length === 0) return false;
   sets.push("updated_at = datetime('now')");
   vals.push(id);
@@ -335,6 +356,15 @@ export function markSeen(jobId: string, key: string): boolean {
   return r.changes > 0;
 }
 
+/** Read-only check — does NOT mutate dedup state. Use when you might
+ *  defer a "new" item to a later tick (budget cap) and don't want to
+ *  prematurely mark it as seen. */
+export function isSeen(jobId: string, key: string): boolean {
+  ensureSchema();
+  const r = db().prepare(`SELECT 1 FROM job_seen WHERE job_id = ? AND dedup_key = ? LIMIT 1`).get(jobId, key);
+  return !!r;
+}
+
 export function resetDedup(jobId: string): number {
   ensureSchema();
   const r = db().prepare('DELETE FROM job_seen WHERE job_id = ?').run(jobId);

package/lib/jobs/types.ts

@@ -84,6 +84,12 @@ export interface Job {
   /** Cron expression (5 fields); only used when schedule_kind === 'cron'. */
   schedule_cron: string | null;
 
+  /** Per-tick dispatch budget. Default 5, hard ceiling 10 in the
+   *  scheduler. Source can return 200 items; only this many spawn
+   *  pipelines per tick — the rest stay un-dedup-marked and roll
+   *  over to the next tick. Protects disk/RAM from fan-out blow-up. */
+  max_per_tick: number;
+
   last_run_at: string | null;
   next_run_at: string | null;
   created_at: string;
@@ -144,6 +150,9 @@ export interface CreateJobInput {
   /** Cron expression, required when schedule_kind === 'cron'. */
   schedule_cron?: string | null;
 
+  /** Per-tick dispatch budget (default 5, capped 1-10 in scheduler). */
+  max_per_tick?: number;
+
   /** Default true: first tick records existing items as seen without dispatching. */
   mark_existing_as_seen?: boolean;
 }

package/lib/settings.ts

@@ -76,6 +76,13 @@ export interface Settings {
    * shape as connectorsRepoUrl. Default: `aiwatching/forge-workflow`.
    */
   workflowRepoUrl: string;
+  /**
+   * Maximum concurrent pipeline runs (running + pending). When a Job's
+   * scheduler tick would push the total above this, additional items
+   * are deferred to the next tick instead of dispatched.
+   * Default 5; ceiling 20 enforced in scheduler.
+   */
+  maxConcurrentPipelines: number;
   displayName: string;
   displayEmail: string;
   favoriteProjects: string[];
@@ -132,6 +139,7 @@ const defaults: Settings = {
   skillsRepoUrl: 'https://raw.githubusercontent.com/aiwatching/forge-skills/main',
   connectorsRepoUrl: 'https://raw.githubusercontent.com/aiwatching/forge-connectors/main',
   workflowRepoUrl: 'https://raw.githubusercontent.com/aiwatching/forge-workflow/main',
+  maxConcurrentPipelines: 5,
   displayName: 'Forge',
   displayEmail: '',
   favoriteProjects: [],

package/package.json

@@ -1,18 +1,20 @@
 {
   "name": "@aion0/forge",
-  "version": "0.8.8",
+  "version": "0.9.0",
   "description": "Unified AI workflow platform — multi-model task orchestration, persistent sessions, web terminal, remote access",
   "type": "module",
   "scripts": {
     "dev": "next dev --turbopack",
     "build": "next build",
     "start": "next start",
-    "forge": "npx tsx cli/mw.ts"
+    "forge": "npx tsx cli/mw.ts",
+    "build:cli": "esbuild cli/mw.ts --bundle --platform=node --format=esm --target=node18 --outfile=cli/mw.mjs --banner:js='#!/usr/bin/env node' --external:better-sqlite3 --external:node-pty && chmod +x cli/mw.mjs",
+    "prepack": "npm run build:cli"
   },
   "bin": {
-    "forge": "cli/mw.ts",
+    "forge": "cli/mw.mjs",
     "forge-server": "bin/forge-server.mjs",
-    "mw": "cli/mw.ts"
+    "mw": "cli/mw.mjs"
   },
   "keywords": [
     "ai",
@@ -53,7 +55,6 @@
     "react-dom": "^19.2.4",
     "react-markdown": "^10.1.0",
     "remark-gfm": "^4.0.1",
-    "tsx": "^4.21.0",
     "ws": "^8.19.0",
     "yaml": "^2.8.2",
     "zod": "^4.3.6"
@@ -74,6 +75,7 @@
     "@types/ws": "^8.18.1",
     "postcss": "^8.5.8",
     "tailwindcss": "^4.2.1",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   }
 }