@aion0/forge 0.9.0 → 0.9.2

package/lib/schedules/types.ts

@@ -0,0 +1,117 @@
+/**
+ * Forge Schedules — types (V2)
+ *
+ * V2 generalizes Schedule from "pipeline + input + trigger" to
+ * "trigger + body + action". body is one of pipeline / skill /
+ * connector_tool (skill + connector_tool land in later phases).
+ * action is one of none / chat / email / telegram (chat/email/telegram
+ * land in later phases).
+ *
+ * Phase 1 only renames + extends fields; runtime behavior unchanged
+ * (body_kind defaults to 'pipeline', action_kind defaults to 'none').
+ */
+
+export type ScheduleKind = 'period' | 'once' | 'cron' | 'manual';
+export type ScheduleRunStatus = 'started' | 'done' | 'failed' | 'cancelled';
+export type ScheduleRunTrigger = 'schedule' | 'manual';
+
+export type ScheduleBodyKind = 'pipeline' | 'skill' | 'connector_tool';
+export type ScheduleActionKind = 'none' | 'chat' | 'email' | 'telegram';
+export type ScheduleActionStatus = 'pending' | 'done' | 'failed' | 'skipped';
+
+/** Persisted Schedule config. status is NOT here — computed on read. */
+export interface Schedule {
+  id: string;
+  name: string;
+  enabled: boolean;
+
+  // Body — what to run when this schedule fires.
+  body_kind: ScheduleBodyKind;
+  /** Reference depends on body_kind: pipeline name / skill id / `<plugin>.<tool>`. */
+  body_ref: string;
+  /** Input params; shape depends on body_kind. */
+  input: Record<string, unknown>;
+
+  /** Extra Forge skills attached to the dispatched body. For body=pipeline
+   *  these are forwarded to startPipeline({skills}) → every task gets the
+   *  --append-system-prompt block. For body=skill they're merged with
+   *  body_ref into a single prompt. body=connector_tool ignores this. */
+  skills: string[];
+
+  // Action — what to do with body's output. action_config JSON shape
+  // is kind-specific (see help doc 13-schedules.md).
+  action_kind: ScheduleActionKind;
+  action_config: Record<string, unknown>;
+  action_skip_on_empty: boolean;
+
+  // Trigger
+  schedule_kind: ScheduleKind;
+  schedule_interval_minutes: number;
+  schedule_at: string | null;
+  schedule_cron: string | null;
+  next_run_at: string | null;
+  last_run_at: string | null;
+
+  created_at: string;
+  updated_at: string;
+}
+
+/** UI-facing schedule with computed state fields. */
+export type ActiveState = 'idle' | 'running' | 'last_failed' | 'paused';
+
+export interface DecoratedSchedule extends Schedule {
+  /** Number of schedule_runs.status='started' for this schedule. */
+  inflight_count: number;
+  /** Most recent terminal run's status, null if never run. */
+  last_status: ScheduleRunStatus | null;
+  /** Computed from enabled + inflight + last_status. */
+  active_state: ActiveState;
+}
+
+export interface ScheduleRun {
+  id: string;
+  schedule_id: string;
+  /** ID of the dispatched body — pipeline_id for body=pipeline,
+   *  task_id for body=skill, fresh uuid for body=connector_tool. */
+  target_id: string;
+  trigger: ScheduleRunTrigger;
+  status: ScheduleRunStatus;
+  /** Captured output of the body — fed into action. May be null
+   *  while body is still running, or if body produced no output. */
+  body_output: string | null;
+  action_status: ScheduleActionStatus | null;
+  action_error: string | null;
+  started_at: string;
+  finished_at: string | null;
+  error: string | null;
+}
+
+export interface CreateScheduleInput {
+  name: string;
+  body_kind?: ScheduleBodyKind;
+  body_ref: string;
+  input?: Record<string, unknown>;
+  skills?: string[];
+  action_kind?: ScheduleActionKind;
+  action_config?: Record<string, unknown>;
+  action_skip_on_empty?: boolean;
+  enabled?: boolean;
+  schedule_kind?: ScheduleKind;
+  schedule_interval_minutes?: number;
+  schedule_at?: string | null;
+  schedule_cron?: string | null;
+}
+
+export interface UpdateScheduleInput {
+  name?: string;
+  input?: Record<string, unknown>;
+  skills?: string[];
+  enabled?: boolean;
+  action_kind?: ScheduleActionKind;
+  action_config?: Record<string, unknown>;
+  action_skip_on_empty?: boolean;
+  schedule_kind?: ScheduleKind;
+  schedule_interval_minutes?: number;
+  schedule_at?: string | null;
+  schedule_cron?: string | null;
+}

package/lib/settings.ts

@@ -117,6 +117,31 @@ export interface Settings {
    * Used by the extension's date formatter for chat / jobs / pipeline run timestamps.
    */
   timezone: string;
+  /**
+   * SMTP transport for Schedule action=email (and any future email-out
+   * paths). Flat fields so smtpPassword fits SECRET_FIELDS encryption.
+   * Empty smtpHost disables the email channel.
+   *   smtpSecure: true → implicit TLS (port 465).
+   *                false + port 587 → STARTTLS.
+   *   smtpFrom: e.g. "Forge <noreply@example.com>"; falls back to smtpUser.
+   */
+  smtpHost: string;
+  smtpPort: number;
+  smtpSecure: boolean;
+  smtpUser: string;
+  smtpPassword: string;
+  smtpFrom: string;
+  /**
+   * Pipeline tmp dir GC — controls retention of `<project>/worktrees/pipeline-<id>/`
+   * directories that nodes write scratch files to via `{{run.tmp_dir}}`.
+   *   pipelineTmpCleanDoneImmediate: true (default) → wipe immediately when pipeline status flips to 'done'
+   *   pipelineTmpKeepFailedDays / pipelineTmpKeepCancelledDays: keep these many days, then sweep
+   *   pipelineTmpGcIntervalHours: how often the background sweep runs (clamped to >= 1h)
+   */
+  pipelineTmpCleanDoneImmediate: boolean;
+  pipelineTmpKeepFailedDays: number;
+  pipelineTmpKeepCancelledDays: number;
+  pipelineTmpGcIntervalHours: number;
 }
 
 const defaults: Settings = {
@@ -154,6 +179,16 @@ const defaults: Settings = {
   agents: {},
   mcpServers: {},
   timezone: '',
+  smtpHost: '',
+  smtpPort: 587,
+  smtpSecure: false,
+  smtpUser: '',
+  smtpPassword: '',
+  smtpFrom: '',
+  pipelineTmpCleanDoneImmediate: true,
+  pipelineTmpKeepFailedDays: 3,
+  pipelineTmpKeepCancelledDays: 3,
+  pipelineTmpGcIntervalHours: 6,
 };
 
 /** Decrypt nested apiKey fields in agent profiles */

package/lib/task-manager.ts

@@ -6,14 +6,27 @@
 import { randomUUID } from 'node:crypto';
 import { spawn, execSync } from 'node:child_process';
 import { realpathSync } from 'node:fs';
+import * as pty from 'node-pty';
 import { getDb } from '@/src/core/db/database';
 import { getDbPath } from '@/src/config';
 import { loadSettings } from './settings';
 import { notifyTaskComplete, notifyTaskFailed } from './notify';
+import { getInstalledConnector } from './connectors/registry';
+import { getAgent } from './agents';
+import { recordUsage } from './usage-scanner';
 import type { Task, TaskLogEntry, TaskStatus, TaskMode, WatchConfig } from '@/src/types';
 
 import { toIsoUTC } from './iso-time';
 
+/** Access pipeline.ts's pipelineTaskIds Set via the shared globalThis
+ *  Symbol it registers at module load. Avoids the circular static
+ *  import (pipeline.ts → task-manager). Returns empty Set if pipeline.ts
+ *  hasn't initialized — caller treats as "not a pipeline task". */
+function pipelineTaskIdsRef(): Set<string> {
+  const key = Symbol.for('mw-pipeline-task-ids');
+  return (globalThis as any)[key] || new Set<string>();
+}
+
 const runnerKey = Symbol.for('mw-task-runner');
 const gRunner = globalThis as any;
 if (!gRunner[runnerKey]) gRunner[runnerKey] = { runner: null, currentTaskId: null };
@@ -261,6 +274,29 @@ export function deleteTask(id: string): boolean {
   return true;
 }
 
+/** Bulk-delete completed tasks older than the given cutoff. Skips
+ *  anything currently running so we never yank state from under the
+ *  task runner. Returns the count removed. */
+export interface BulkDeleteTasksFilter {
+  /** ISO timestamp; rows with created_at < this are eligible. */
+  before: string;
+  /** Statuses to include. Default ['done','failed','cancelled']. */
+  statuses?: TaskStatus[];
+}
+
+export function bulkDeleteTasks(filter: BulkDeleteTasksFilter): number {
+  const statuses = filter.statuses && filter.statuses.length
+    ? filter.statuses
+    : (['done', 'failed', 'cancelled'] as TaskStatus[]);
+  const placeholders = statuses.map(() => '?').join(',');
+  const r = db().prepare(
+    `DELETE FROM tasks
+       WHERE status IN (${placeholders})
+         AND created_at < ?`,
+  ).run(...statuses, filter.before);
+  return r.changes;
+}
+
 export function updateTask(id: string, updates: { prompt?: string; projectName?: string; projectPath?: string; priority?: number; scheduledAt?: string; restart?: boolean }): Task | null {
   const task = getTask(id);
   if (!task) return null;
@@ -349,8 +385,13 @@ async function processNextTask() {
     // Execute async — don't await so we can process tasks for other projects in parallel
     executeTask(task)
       .catch((err: any) => {
-        appendLog(task.id, { type: 'system', subtype: 'error', content: err.message, timestamp: new Date().toISOString() });
-        updateTaskStatus(task.id, 'failed', err.message);
+        // Verbose diagnostic dump — the stack alone hid an issue where
+        // err.stack was undefined (zombie tsx-runner-process throws had
+        // no stack); name/typeof/keys helped pin it down. Keep verbose.
+        const stack = err?.stack || err?.message || String(err);
+        console.error(`[task-runner] executeTask failed for ${task.id}:`, JSON.stringify({ msg: err?.message, name: err?.name, stack: err?.stack, str: String(err), type: typeof err, keys: err && Object.keys(err) }));
+        appendLog(task.id, { type: 'system', subtype: 'error', content: stack, timestamp: new Date().toISOString() });
+        updateTaskStatus(task.id, 'failed', err?.message || String(err));
       })
       .finally(() => {
         runningProjects.delete(task.projectName);
@@ -371,7 +412,6 @@ async function processNextTask() {
  */
 function connectorEnv(): Record<string, string> {
   try {
-    const { getInstalledConnector } = require('./connectors/registry');
     const out: Record<string, string> = {};
     const gitlab = getInstalledConnector('gitlab');
     if (gitlab?.enabled) {
@@ -471,7 +511,6 @@ function executeTask(task: Task): Promise<void> {
 
   return new Promise((resolve, reject) => {
     const settings = loadSettings();
-    const { getAgent } = require('./agents');
     const agentId = (task as any).agent || settings.defaultAgent || 'claude';
     const adapter = getAgent(agentId);
 
@@ -512,8 +551,9 @@ function executeTask(task: Task): Promise<void> {
     let ptyProcess: any = null;
 
     if (needsTTY) {
-      // Use node-pty for agents that require a terminal environment
-      const pty = require('node-pty');
+      // Use node-pty for agents that require a terminal environment.
+      // pty is imported at top level (was a runtime require() that
+      // hit "require is not defined" under ESM + concurrent loads).
       ptyProcess = pty.spawn(spawnOpts.cmd, spawnOpts.args, {
         name: 'xterm-256color',
         cols: 120,
@@ -584,8 +624,10 @@ function executeTask(task: Task): Promise<void> {
     let totalOutputTokens = 0;
 
     child.on('error', (err: any) => {
-      console.error(`[task-runner] Spawn error:`, err.message);
-      updateTaskStatus(task.id, 'failed', err.message);
+      const stack = err?.stack || err?.message || String(err);
+      console.error(`[task-runner] Spawn error for ${task.id}:`, stack);
+      appendLog(task.id, { type: 'system', subtype: 'error', content: `[spawn-error] ${stack}`, timestamp: new Date().toISOString() });
+      updateTaskStatus(task.id, 'failed', err?.message || String(err));
       reject(err);
     });
 
@@ -674,7 +716,6 @@ function executeTask(task: Task): Promise<void> {
       //   2. `git diff @{u}..HEAD`  — commits ahead of upstream (worktree pushed nothing yet)
       //   3. `git show HEAD`        — last commit's diff (fallback when no upstream tracking)
       try {
-        const { execSync } = require('node:child_process');
         const tryDiff = (cmd: string): string => {
           try {
             return execSync(cmd, { cwd: task.projectPath, timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] }).toString();
@@ -703,9 +744,8 @@ function executeTask(task: Task): Promise<void> {
         console.log(`[task] Done: ${task.id} ${task.projectName} (cost: $${totalCost?.toFixed(4) || '0'}, ${totalInputTokens}in/${totalOutputTokens}out)`);
         // Record usage
         try {
-          const { recordUsage } = require('./usage-scanner');
           let isPipeline = false;
-          try { const { pipelineTaskIds: ptids } = require('./pipeline'); isPipeline = ptids.has(task.id); } catch {}
+          isPipeline = pipelineTaskIdsRef().has(task.id);
           recordUsage({
             sessionId: sessionId || task.id,
             source: isPipeline ? 'pipeline' : 'task',
@@ -733,7 +773,10 @@ function executeTask(task: Task): Promise<void> {
     });
 
     child.on('error', (err: any) => {
-      updateTaskStatus(task.id, 'failed', err.message);
+      const stack = err?.stack || err?.message || String(err);
+      console.error(`[task:shell] child error for ${task.id}:`, stack);
+      appendLog(task.id, { type: 'system', subtype: 'error', content: `[child-error] ${stack}`, timestamp: new Date().toISOString() });
+      updateTaskStatus(task.id, 'failed', err?.message || String(err));
       reject(err);
     });
   });
@@ -748,7 +791,7 @@ function executeTask(task: Task): Promise<void> {
 function notifyTerminalSession(task: Task, status: 'done' | 'failed', sessionId?: string) {
   // Skip pipeline tasks — they have their own notification system
   try {
-    const { pipelineTaskIds } = require('./pipeline');
+    const pipelineTaskIds = pipelineTaskIdsRef();
     if (pipelineTaskIds.has(task.id)) return;
   } catch {}
 

package/lib/workflow-marketplace.ts

@@ -190,7 +190,13 @@ async function fetchText(url: string): Promise<string | null> {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
   try {
-    const res = await fetch(url, { signal: controller.signal });
+    // Cache-bust + no-cache so a Sync click bypasses any intermediate
+    // HTTP cache and pulls the latest yaml from the repo CDN.
+    const sep = url.includes('?') ? '&' : '?';
+    const res = await fetch(`${url}${sep}_t=${Date.now()}`, {
+      signal: controller.signal,
+      headers: { 'Cache-Control': 'no-cache', 'User-Agent': 'forge-workflow-sync/1.0' },
+    });
     clearTimeout(timer);
     if (!res.ok) return null;
     return await res.text();

package/lib/workspace/skill-installer.ts

@@ -3,7 +3,7 @@
  * so they are available across all projects and sessions.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, unlinkSync, rmSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -53,7 +53,9 @@ export function installForgeSkills(
   for (const file of files) {
     const flatFile = join(skillsDir, file);
     if (existsSync(flatFile)) {
-      try { require('node:fs').unlinkSync(flatFile); } catch {}
+      try { unlinkSync(flatFile); } catch (e) {
+        console.warn(`[skill-installer] unlink ${flatFile} failed: ${(e as Error).message}`);
+      }
     }
   }
 
@@ -270,9 +272,8 @@ export function removeForgeSkills(projectPath: string): void {
   const forgeSkills = readdirSync(skillsDir).filter(f => f.startsWith('forge-'));
   for (const name of forgeSkills) {
     const p = join(skillsDir, name);
-    try {
-      const { rmSync } = require('node:fs');
-      rmSync(p, { recursive: true, force: true });
-    } catch {}
+    try { rmSync(p, { recursive: true, force: true }); } catch (e) {
+      console.warn(`[skill-installer] rmSync ${p} failed: ${(e as Error).message}`);
+    }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aion0/forge",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Unified AI workflow platform — multi-model task orchestration, persistent sessions, web terminal, remote access",
   "type": "module",
   "scripts": {
@@ -51,6 +51,7 @@
     "next": "^16.2.1",
     "next-auth": "5.0.0-beta.30",
     "node-pty": "1.0.0",
+    "nodemailer": "^8.0.8",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "react-markdown": "^10.1.0",
@@ -70,6 +71,7 @@
     "@tailwindcss/postcss": "^4.2.1",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.4.0",
+    "@types/nodemailer": "^8.0.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@types/ws": "^8.18.1",

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

@@ -1,145 +0,0 @@
-# Jobs
-
-A **Job** runs a connector tool on a schedule, dedups items, and dispatches
-each new item to a Pipeline or a Chat session.
-
-Typical examples:
-- Every 30 min, search Mantis for open bugs in version 25.4 → for each new
-  bug, trigger the `bug-triage` pipeline bound to project `my-app`.
-- Every 5 min, list Teams messages in the current chat → for each new
-  message, POST to a chat session that drafts a reply.
-
-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 |
-|---|---|
-| `source_connector`, `source_tool` | Which connector + tool to call each tick (e.g. `mantis.search_bugs`) |
-| `source_input` | JSON passed verbatim to the tool |
-| `items_path` | Dotted path into the tool's response to find the item array (`bugs`, empty = whole response if already an array) |
-| `dedup_field` | Field on each item used as the dedup key (e.g. `id`) |
-| `schedule_interval_minutes` | How often the scheduler ticks this job |
-| `dispatch_type` | `pipeline` or `chat` |
-| `dispatch_params` | Shape depends on dispatch_type — see below |
-
-### `dispatch_type: pipeline`
-
-```json
-{
-  "workflow_name": "bug-triage",
-  "project_path": "/Users/me/code/my-app",
-  "project_name": "my-app",
-  "input_template": {
-    "bug_id": "{{item.id}}",
-    "summary": "{{item.summary}}"
-  }
-}
-```
-
-Per new item, Forge renders `input_template` and calls the existing
-`triggerPipeline`. The pipeline shows up in the regular Pipelines view.
-
-### `dispatch_type: chat`
-
-```json
-{
-  "agent_profile": "my-litellm",
-  "session_title_template": "Bug {{item.id}}: {{item.summary}}",
-  "message_template": "Triage bug {{item.id}}.\nSummary: {{item.summary}}",
-  "reuse_session": false
-}
-```
-
-Per new item, Forge creates (or reuses, if `reuse_session: true`) a chat
-session and POSTs a message rendered from `message_template`. The chat
-agent gets the message and decides what tools to call.
-
-## Template syntax
-
-Only `{{item.<dotted.path>}}` is supported in v1. Missing paths render to
-empty string; objects render via `JSON.stringify`. `{{item}}` alone dumps
-the full item.
-
-## Backfill guard
-
-New jobs default to `mark_existing_as_seen: true` — on first tick, every
-item the connector returns is added to `job_seen` but **no dispatch
-happens**. This stops a fresh job from firing on historical data. Set to
-`false` at create time to dispatch immediately on first tick.
-
-## CLI
-
-```
-forge jobs                              # list
-forge jobs show <id>                    # full JSON detail
-forge jobs runs <id>                    # recent ticks (summary line per run)
-forge jobs dispatches <id> <run_id>     # per-item dispatches for one run (target ids)
-forge jobs run <id>                     # fire now (manual trigger)
-forge jobs enable <id>
-forge jobs disable <id>
-forge jobs reset <id>                   # wipe dedup state — next tick re-processes everything
-forge jobs rm <id>
-```
-
-## Tracking results
-
-| Want to know | Where |
-|---|---|
-| Job list, schedule, enabled, last/next run | Extension → Jobs tab |
-| Last 10 ticks summary (seen/new/dispatched, error) | Expand a job in Jobs tab |
-| Which items got dispatched in a single tick | Expand a run row — shows item_key + preview + target id + open-link |
-| What the resulting pipeline run did | Click "open →" on a pipeline dispatch — deep-links to Forge web Pipelines view |
-| What the resulting chat session said | Click "open →" on a chat dispatch — switches the side panel to chat tab and loads that session |
-| Run / dispatch detail from terminal | `forge jobs runs <id>` then `forge jobs dispatches <id> <run_id>` |
-| Raw rows | sqlite: `select * from job_runs / job_dispatches` |
-| Server-side log lines (every tick / error / dispatch) | Forge web → Logs view, search `[jobs]` (per-job: `[jobs] <job_id>`). The Jobs view has "View logs" buttons that pre-fill this filter. CLI: `tail -f ~/.forge/data/forge.log \| grep '\[jobs\]'`. |
-| Why a run shows 0 dispatches | Read the italic note under the run row — the scheduler writes a `notes` field explaining backfill / non-JSON response / items_path mismatch. |
-
-Create + edit happen via the Forge extension Jobs tab, or by `curl`ing
-`POST /api/jobs`. There is no YAML-on-disk format for Jobs (definitions
-live in sqlite).
-
-## Lifecycle
-
-1. Scheduler ticks every 60s. For each enabled job where `next_run_at`
-   has elapsed:
-2. Skip if a previous tick is still running (idempotent).
-3. Advance `next_run_at = now + schedule_interval_minutes`.
-4. Spawn a background tick:
-   - Call the connector via the chat tool-dispatcher (handles
-     `http` / `shell` / `browser` protocols uniformly).
-   - Parse the response — find items via `items_path`.
-   - For each item, compute `dedup_key = item[dedup_field]`,
-     `INSERT OR IGNORE INTO job_seen`. If new: dispatch.
-   - Update the `job_runs` row with counts + status.
-
-## Browser-protocol caveat
-
-If `source_connector` is a `protocol: browser` connector (Mantis, GitLab,
-Teams, PMDB), the job tick can only fire **when the extension bridge is
-connected** — the tool needs a live tab and `chrome.scripting`. A tick
-with no extension fails with `connector ... failed: No extension
-connected to the bridge`. The run is marked errored; the next tick
-retries.
-
-For 24/7 background polling, prefer connectors with `protocol: http`
-(e.g. `github-api`) — those run server-side and don't need a browser.
-
-## Tables
-
-```
-jobs                — definition (one row per job)
-job_runs            — one row per tick (success / failure)
-job_seen            — dedup keys per job (PRIMARY KEY (job_id, dedup_key))
-job_dispatches      — one row per per-item dispatch attempt (link to pipeline run / chat session)
-```
-
-All cascaded on `ON DELETE`.

package/lib/help-docs/20-mantis-bug-fix.md

@@ -1,115 +0,0 @@
-# Mantis → Bug Fix → MR pipeline
-
-End-to-end: a Mantis bug surfaces (via a Forge **Job** polling mantis.get_bug
-/ mantis.search_bugs) → triggers a Pipeline → Pipeline checks out the right
-base branch in a worktree → headless Claude implements the fix → pipeline
-opens a GitLab MR via `glab` → pipeline pings the assignee + reporter on
-Teams with the MR URL.
-
-Mirrors the `gitlab-issue-fix-and-review` builtin but driven by Mantis
-content (description / priority / category / assignee / reporter), MR
-opens against an explicit `base_branch` you pass in from the Job (because
-Mantis doesn't carry milestones the way GitLab issues do).
-
-## Builtin name
-
-`mantis-bug-fix-and-mr` — registered in Forge's built-in workflow set,
-visible in the Pipelines view's workflow dropdown and pickable from the
-extension Jobs tab when you wire a Pipeline-dispatch Job.
-
-## Inputs (set by the Job's `input_template`)
-
-| Key | Required | Source |
-|---|---|---|
-| `bug_id` | yes | `{{item.id}}` |
-| `project` | yes | injected by `triggerPipeline` from the Job's project setting |
-| `base_branch` | **yes** | `{{item.product_version}}` mapped to a branch, OR a literal like `"release/25.4"` you write into the template |
-| `summary` | yes | `{{item.summary}}` |
-| `description` | yes | `{{item.description}}` |
-| `priority` | opt | `{{item.priority}}` |
-| `category` | opt | `{{item.category}}` |
-| `assignee` | opt | `{{item.assignee}}` — used as Teams chat name |
-| `reporter` | opt | `{{item.reporter}}` — used as Teams chat name |
-| `extra_context` | opt | literal hint text for Claude |
-| `mr_title_template` | opt | default `Fix Mantis #{bug_id}: {summary}` |
-| `mr_body_template` | opt | default closes-ref + Claude summary; vars `{bug_id} {summary} {description} {claude_summary}` |
-| `teams_message_template` | opt | default `🤖 Mantis #{bug_id} fixed — please review MR: {mr_url}\nBug: {summary}`; vars `{bug_id} {summary} {role} {mr_url}` |
-
-## Nodes
-
-```
-resolve              parse git remote → HOST + PROJECT_PATH; check glab; require base_branch
-worktree-setup       git worktree add -b fix/mantis-<id> .forge/worktrees/mantis-<id> origin/<base>
-fix-code             headless Claude — reads bug context, edits in worktree, commits
-push-and-mr          if any commits: push fix/mantis-<id>, glab mr create → MR_URL
-notify-teams         curl /api/connector-tool teams.send_message twice (assignee + reporter)
-```
-
-`fix-code` runs as a normal Claude task (not shell) so it can think, browse,
-edit, and commit. `notify-teams` short-circuits if `push-and-mr` couldn't
-create an MR (e.g. Claude made no changes).
-
-## Talking to connectors from a pipeline
-
-`notify-teams` calls `POST http://127.0.0.1:8403/api/connector-tool` —
-a loopback-only endpoint that wraps `lib/chat/tool-dispatcher`. Body:
-
-```json
-{ "plugin_id": "teams", "tool": "send_message",
-  "input": { "name": "Alice", "text": "MR: https://..." } }
-```
-
-Returns the standard `{ content, is_error }` tool-result shape. Works for
-`browser` / `http` / `shell` protocol connectors. Browser-protocol calls
-need the extension bridge connected at pipeline runtime (Chrome open +
-extension signed in).
-
-## Wiring it up from a Job
-
-1. Confirm `glab` is installed + authed for the target host:
-   `glab auth login --hostname <your-gitlab.example.com>`
-2. Make sure the project has a git remote (`git remote get-url origin`) the
-   `glab mr create` call can reach.
-3. Forge extension → Jobs → + New job. Pick:
-   - Connector / tool: `mantis` / `get_bug` (single bug) or `search_bugs` (a query)
-   - dispatch: Pipeline → workflow `mantis-bug-fix-and-mr` → your project
-   - `input_template` (auto-prefilled when you pick the workflow; map item
-     keys to inputs, hardcode `base_branch` if Mantis doesn't carry it):
-     ```json
-     {
-       "bug_id":      "{{item.id}}",
-       "summary":     "{{item.summary}}",
-       "description": "{{item.description}}",
-       "priority":    "{{item.priority}}",
-       "category":    "{{item.category}}",
-       "assignee":    "{{item.assignee}}",
-       "reporter":    "{{item.reporter}}",
-       "base_branch": "release/25.4"
-     }
-     ```
-4. Save → Run now (first tick is a backfill-no-op; click Reset dedup +
-   Run now to force one actual dispatch for testing).
-
-## Customising
-
-- Branch derivation rules (e.g. `target_version` → `release/<major.minor>`):
-  edit the `resolve` node in your local copy at
-  `~/.forge/data/flows/mantis-bug-fix-and-mr.yaml` (a copy will be created
-  when you click Edit in the Pipelines view; once a local file exists it
-  overrides the builtin).
-- MR title / body templates: set via the Job's `input_template` — no
-  pipeline edit needed.
-- Teams routing: today it uses the Mantis username verbatim as the Teams
-  chat name (substring match). For better mapping, post-process in
-  `notify-teams` to convert username → real name via a lookup table or
-  a second connector call.
-
-## Troubleshooting
-
-| Symptom | Cause + fix |
-|---|---|
-| `ERROR: base_branch is required` | The Job's `input_template` didn't supply it — Mantis bugs don't always carry one. Hardcode it in the template or map from `product_version`. |
-| `NO_CHANGES — Claude did not commit` | Bug description was too thin or Claude couldn't find the affected code. Add hints via `extra_context` or open the worktree manually and iterate. |
-| `glab mr create` returns nothing | Token expired / target branch protected / source branch already has an open MR. The pipeline falls back to `glab mr view` to surface the existing URL — check Pipelines log. |
-| Teams send returns `No extension connected to the bridge` | The pipeline ran when Chrome / extension weren't online. Notification fails but the MR still landed; re-fire the `notify-teams` node manually or message the people yourself. |
-| Mantis username doesn't match any Teams chat | The fuzzy substring match in `teams.send_message` falls back to whatever the LLM-less DOM script can match. Add a lookup step before `notify-teams` to translate names. |