@aion0/forge 0.5.26 → 0.5.28

package/.forge/worktrees/pipeline-4dd8dc2d/lib/help-docs/CLAUDE.md

@@ -0,0 +1,62 @@
+You are a help assistant for **Forge** — a self-hosted Vibe Coding platform.
+
+Your job is to answer user questions about Forge features, configuration, and troubleshooting.
+
+## How to answer
+
+1. Read the relevant documentation file(s) from this directory before answering
+2. Base your answers on the documentation content, not assumptions
+3. If the answer isn't in the docs, say so honestly
+4. Give concise, actionable answers with code examples when helpful
+5. When generating files (YAML workflows, configs, scripts, etc.), **always save the file directly** to the appropriate directory rather than printing it. For pipeline workflows, save to `~/.forge/data/flows/<name>.yaml`. Tell the user the file path so they can find it. The terminal does not support copy/paste.
+
+## API Authentication
+
+When you need to call Forge APIs (e.g., workspace, settings) that return "unauthorized", ask the user for their admin password and authenticate:
+
+```bash
+# Step 1: Get API token (ask user for their admin password)
+TOKEN=$(curl -s -X POST http://localhost:8403/api/auth/verify \
+  -H "Content-Type: application/json" \
+  -d '{"password":"USER_PASSWORD"}' | python3 -c "import sys,json; print(json.load(sys.stdin).get('token',''))")
+
+# Step 2: Use token in subsequent requests
+curl -s -H "X-Forge-Token: $TOKEN" http://localhost:8403/api/workspace/...
+```
+
+The token is valid for 24 hours. Store it in a variable and reuse for all API calls in this session. Only ask for the password once.
+
+## Available documentation
+
+| File | Topic |
+|------|-------|
+| `00-overview.md` | Installation, startup, data paths, architecture |
+| `01-settings.md` | All settings fields and configuration |
+| `02-telegram.md` | Telegram bot setup and commands |
+| `03-tunnel.md` | Remote access via Cloudflare tunnel |
+| `04-tasks.md` | Background task system |
+| `05-pipelines.md` | Pipeline/workflow engine — YAML format, nodes, templates, routing, scheduling, project bindings |
+| `06-skills.md` | Skills marketplace and installation |
+| `07-projects.md` | Project management |
+| `08-rules.md` | CLAUDE.md templates and rule injection |
+| `09-issue-autofix.md` | GitHub issue auto-fix pipeline |
+| `10-troubleshooting.md` | Common issues and solutions |
+| `11-workspace.md` | Workspace (Forge Smiths) — multi-agent orchestration, daemon, message bus, profiles |
+
+## Matching questions to docs
+
+- Pipeline/workflow/DAG/YAML → `05-pipelines.md`
+- Issue/PR/auto-fix → `09-issue-autofix.md` + `05-pipelines.md`
+- Telegram/notification → `02-telegram.md`
+- Tunnel/remote/cloudflare → `03-tunnel.md`
+- Task/background/queue → `04-tasks.md`
+- Settings/config/agent/profile/provider → `01-settings.md`
+- Install/start/update → `00-overview.md`
+- Error/bug/crash → `10-troubleshooting.md`
+- Skill/marketplace → `06-skills.md`
+- Project/favorite/terminal → `07-projects.md`
+- Rules/CLAUDE.md/template → `08-rules.md`
+- Workspace/smith/daemon/multi-agent/bus/message/ticket → `11-workspace.md`
+- Watch/monitor/detect/file changes/autonomous → `11-workspace.md`
+- Agent profile/env/model/cliType → `01-settings.md` + `11-workspace.md`
+- Agent log/logs/history/clear logs → `11-workspace.md`

package/.forge/worktrees/pipeline-4dd8dc2d/lib/init.ts

@@ -0,0 +1,266 @@
+/**
+ * Server-side initialization — called once on first API request per worker.
+ * When FORGE_EXTERNAL_SERVICES=1 (set by forge-server), telegram/terminal/tunnel
+ * are managed externally — only task runner starts here.
+ */
+
+import { ensureRunnerStarted } from './task-manager';
+import { startTelegramBot, stopTelegramBot } from './telegram-bot';
+import { startWatcherLoop } from './session-watcher';
+import { getAdminPassword } from './password';
+import { loadSettings, saveSettings } from './settings';
+import { startTunnel } from './cloudflared';
+import { isEncrypted, SECRET_FIELDS } from './crypto';
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+
+const initKey = Symbol.for('mw-initialized');
+const gInit = globalThis as any;
+
+/** Migrate plaintext secrets to encrypted on first run */
+function migrateSecrets() {
+  try {
+    const { existsSync, readFileSync } = require('node:fs');
+    const YAML = require('yaml');
+    const { getDataDir: _gdd } = require('./dirs');
+    const dataDir = _gdd();
+    const file = join(dataDir, 'settings.yaml');
+    if (!existsSync(file)) return;
+    const raw = YAML.parse(readFileSync(file, 'utf-8')) || {};
+    let needsSave = false;
+    for (const field of SECRET_FIELDS) {
+      if (raw[field] && typeof raw[field] === 'string' && !isEncrypted(raw[field])) {
+        needsSave = true;
+        break;
+      }
+    }
+    if (needsSave) {
+      // loadSettings returns decrypted, saveSettings encrypts
+      const settings = loadSettings();
+      saveSettings(settings);
+      console.log('[init] Migrated plaintext secrets to encrypted storage');
+    }
+  } catch (e) {
+    console.error('[init] Secret migration error:', e);
+  }
+}
+
+/** Auto-detect agent binaries */
+function autoDetectAgents() {
+  try {
+    const settings = loadSettings();
+    // Backward compat: detect claude if not configured
+    if (!settings.claudePath) {
+      const { execSync } = require('node:child_process');
+      try {
+        const path = execSync('which claude', { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        if (path) {
+          settings.claudePath = path;
+          saveSettings(settings);
+          console.log(`[init] Auto-detected claude: ${path}`);
+        }
+      } catch {}
+    }
+    // Detect all agents
+    const { autoDetectAgents: detect } = require('./agents');
+    detect();
+  } catch {}
+}
+
+export function ensureInitialized() {
+  if (gInit[initKey]) return;
+  gInit[initKey] = true;
+
+  // Add timestamps to all console output
+  try { const { initLogger } = require('./logger'); initLogger(); } catch {}
+
+  // Migrate old data layout (~/.forge/* → ~/.forge/data/*) on first run
+  try { const { migrateDataDir } = require('./dirs'); migrateDataDir(); } catch {}
+
+  // Migrate plaintext secrets on startup
+  migrateSecrets();
+
+  // Cleanup old notifications
+  try {
+    const { cleanupNotifications } = require('./notifications');
+    cleanupNotifications();
+  } catch {}
+
+  // Auto-detect claude path if not configured
+  autoDetectAgents();
+
+  // Install/update forge skills to ~/.claude/skills/ on every startup
+  try {
+    const { installForgeSkills } = require('./workspace/skill-installer');
+    installForgeSkills('', '', '', Number(process.env.PORT) || 8403);
+    console.log('[init] Forge skills installed/updated');
+  } catch {}
+
+  // Sync help docs + CLAUDE.md to data dir on startup
+  try {
+    const { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } = require('node:fs');
+    const { join: joinPath } = require('node:path');
+    const { getConfigDir, getDataDir } = require('./dirs');
+    const helpDir = joinPath(getConfigDir(), 'help');
+    const sourceDir = joinPath(process.cwd(), 'lib', 'help-docs');
+    if (existsSync(sourceDir)) {
+      if (!existsSync(helpDir)) mkdirSync(helpDir, { recursive: true });
+      for (const f of readdirSync(sourceDir)) {
+        if (f.endsWith('.md')) writeFileSync(joinPath(helpDir, f), readFileSync(joinPath(sourceDir, f)));
+      }
+      const claudeMd = joinPath(helpDir, 'CLAUDE.md');
+      if (existsSync(claudeMd)) writeFileSync(joinPath(getDataDir(), 'CLAUDE.md'), readFileSync(claudeMd));
+    }
+  } catch {}
+
+  // Sync skills registry (async, non-blocking) — on startup + every 30 min
+  try {
+    const { syncSkills } = require('./skills');
+    syncSkills().catch(() => {});
+    setInterval(() => { syncSkills().catch(() => {}); }, 60 * 60 * 1000);
+  } catch {}
+
+  // Usage scanner — scan JSONL files for token usage on startup + every hour
+  try {
+    const { scanUsage } = require('./usage-scanner');
+    scanUsage();
+    setInterval(() => { try { scanUsage(); } catch {} }, 60 * 60 * 1000);
+  } catch {}
+
+  // Task runner is safe in every worker (DB-level coordination)
+  ensureRunnerStarted();
+
+  // Session watcher is safe (file-based, idempotent)
+  startWatcherLoop();
+
+  // Pipeline scheduler — periodic execution + issue scanning for project-bound workflows
+  try {
+    const { startScheduler } = require('./pipeline-scheduler');
+    startScheduler();
+  } catch {}
+
+  // If services are managed externally (forge-server), skip
+  if (process.env.FORGE_EXTERNAL_SERVICES === '1') {
+    // Password display
+    const admin = getAdminPassword();
+    if (admin) {
+      console.log(`[init] Admin password: configured`);
+    } else {
+      console.log('[init] No admin password set — configure in Settings');
+    };
+    return;
+  }
+
+  // Standalone mode (pnpm dev without forge-server) — start everything here
+  const admin2 = getAdminPassword();
+  if (admin2) {
+    console.log(`[init] Admin password: configured`);
+  } else {
+    console.log('[init] No admin password set — configure in Settings');
+  }
+
+  startTelegramBot(); // registers task event listener only
+  startTerminalProcess();
+  startTelegramProcess(); // spawns telegram-standalone
+  startWorkspaceProcess(); // spawns workspace-standalone
+
+  const settings = loadSettings();
+  if (settings.tunnelAutoStart) {
+    startTunnel().then(result => {
+      if (result.url) console.log(`[init] Tunnel started: ${result.url}`);
+      else if (result.error) console.log(`[init] Tunnel failed: ${result.error}`);
+    });
+  }
+
+  console.log('[init] Background services started');
+}
+
+/** Restart Telegram bot (e.g. after settings change) */
+export function restartTelegramBot() {
+  stopTelegramBot();
+  startTelegramBot();
+  // Kill existing telegram process and restart if configured
+  if (telegramChild) {
+    try { telegramChild.kill('SIGTERM'); } catch {}
+    telegramChild = null;
+  }
+  startTelegramProcess();
+}
+
+let telegramChild: ReturnType<typeof spawn> | null = null;
+
+function startTelegramProcess() {
+  if (telegramChild) return;
+  const settings = loadSettings();
+  if (!settings.telegramBotToken || !settings.telegramChatId) return;
+
+  const script = join(process.cwd(), 'lib', 'telegram-standalone.ts');
+  telegramChild = spawn('npx', ['tsx', script], {
+    stdio: ['ignore', 'inherit', 'inherit'],
+    env: { ...process.env, PORT: String(process.env.PORT || 8403) },
+    detached: false,
+  });
+  telegramChild.on('exit', () => { telegramChild = null; });
+  console.log('[telegram] Started standalone (pid:', telegramChild.pid, ')');
+}
+
+let terminalChild: ReturnType<typeof spawn> | null = null;
+
+function startTerminalProcess() {
+  if (terminalChild) return;
+
+  const termPort = Number(process.env.TERMINAL_PORT) || 8404;
+
+  const net = require('node:net');
+  const tester = net.createServer();
+  tester.once('error', () => {
+    console.log(`[terminal] Port ${termPort} already in use, reusing existing`);
+  });
+  tester.once('listening', () => {
+    tester.close();
+    const script = join(process.cwd(), 'lib', 'terminal-standalone.ts');
+    terminalChild = spawn('npx', ['tsx', script], {
+      stdio: ['ignore', 'inherit', 'inherit'],
+      env: { ...Object.fromEntries(Object.entries(process.env).filter(([k]) => k !== 'CLAUDECODE')) } as NodeJS.ProcessEnv,
+      detached: false,
+    });
+    terminalChild.on('exit', () => { terminalChild = null; });
+    console.log('[terminal] Started standalone server (pid:', terminalChild.pid, ')');
+  });
+  tester.listen(termPort);
+}
+
+let workspaceChild: ReturnType<typeof spawn> | null = null;
+
+function startWorkspaceProcess() {
+  if (workspaceChild) return;
+
+  const wsPort = Number(process.env.WORKSPACE_PORT) || 8405;
+
+  const net = require('node:net');
+  const tester = net.createServer();
+  tester.once('error', () => {
+    // Port in use — kill stale process and retry after 2s
+    console.log(`[workspace] Port ${wsPort} in use, killing stale process...`);
+    try { require('node:child_process').execSync(`lsof -ti:${wsPort} | xargs kill -9 2>/dev/null`, { timeout: 3000 }); } catch {}
+    setTimeout(() => {
+      if (!workspaceChild) launchWorkspaceDaemon();
+    }, 2000);
+  });
+  tester.once('listening', () => {
+    tester.close();
+    launchWorkspaceDaemon();
+  });
+  tester.listen(wsPort);
+}
+
+function launchWorkspaceDaemon() {
+  const script = join(process.cwd(), 'lib', 'workspace-standalone.ts');
+  workspaceChild = spawn('npx', ['tsx', script], {
+    stdio: ['ignore', 'inherit', 'inherit'],
+    env: { ...process.env },
+    detached: false,
+  });
+  workspaceChild.on('exit', () => { workspaceChild = null; });
+  console.log('[workspace] Started daemon (pid:', workspaceChild.pid, ')');
+}

package/.forge/worktrees/pipeline-4dd8dc2d/lib/issue-scanner.ts

@@ -0,0 +1,298 @@
+/**
+ * Issue Scanner — periodically scans GitHub issues for configured projects
+ * and triggers issue-fix-and-review pipeline for new issues.
+ *
+ * Per-project config stored in DB:
+ *   - enabled: boolean
+ *   - interval: minutes (0 = manual only)
+ *   - labels: string[] (only process issues with these labels, empty = all)
+ *   - baseBranch: string (default: auto-detect)
+ */
+
+import { execSync } from 'node:child_process';
+import { getDb } from '@/src/core/db/database';
+import { getDbPath } from '@/src/config';
+import { startPipeline } from './pipeline';
+import { loadSettings } from './settings';
+import { homedir } from 'node:os';
+
+function db() { return getDb(getDbPath()); }
+
+export interface IssueAutofixConfig {
+  projectPath: string;
+  projectName: string;
+  enabled: boolean;
+  interval: number;      // minutes, 0 = manual
+  labels: string[];      // filter labels
+  baseBranch: string;    // default: '' (auto-detect)
+}
+
+// ─── DB setup ────────────────────────────────────────────
+
+function migrateTable() {
+  try { db().exec('ALTER TABLE issue_autofix_config ADD COLUMN last_scan_at TEXT'); } catch {}
+}
+
+export function ensureTable() {
+  db().exec(`
+    CREATE TABLE IF NOT EXISTS issue_autofix_config (
+      project_path TEXT PRIMARY KEY,
+      project_name TEXT NOT NULL,
+      enabled INTEGER NOT NULL DEFAULT 0,
+      interval_min INTEGER NOT NULL DEFAULT 30,
+      labels TEXT NOT NULL DEFAULT '[]',
+      base_branch TEXT NOT NULL DEFAULT '',
+      last_scan_at TEXT
+    );
+    CREATE TABLE IF NOT EXISTS issue_autofix_processed (
+      project_path TEXT NOT NULL,
+      issue_number INTEGER NOT NULL,
+      pipeline_id TEXT,
+      pr_number INTEGER,
+      status TEXT NOT NULL DEFAULT 'processing',
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      PRIMARY KEY (project_path, issue_number)
+    );
+  `);
+  migrateTable();
+}
+
+// ─── Config CRUD ─────────────────────────────────────────
+
+export function getConfig(projectPath: string): IssueAutofixConfig | null {
+  ensureTable();
+  const row = db().prepare('SELECT * FROM issue_autofix_config WHERE project_path = ?').get(projectPath) as any;
+  if (!row) return null;
+  return {
+    projectPath: row.project_path,
+    projectName: row.project_name,
+    enabled: !!row.enabled,
+    interval: row.interval_min,
+    labels: JSON.parse(row.labels || '[]'),
+    baseBranch: row.base_branch || '',
+  };
+}
+
+export function saveConfig(config: IssueAutofixConfig): void {
+  ensureTable();
+  db().prepare(`
+    INSERT OR REPLACE INTO issue_autofix_config (project_path, project_name, enabled, interval_min, labels, base_branch)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(config.projectPath, config.projectName, config.enabled ? 1 : 0, config.interval, JSON.stringify(config.labels), config.baseBranch);
+}
+
+export function listConfigs(): IssueAutofixConfig[] {
+  ensureTable();
+  return (db().prepare('SELECT * FROM issue_autofix_config WHERE enabled = 1').all() as any[]).map(row => ({
+    projectPath: row.project_path,
+    projectName: row.project_name,
+    enabled: !!row.enabled,
+    interval: row.interval_min,
+    labels: JSON.parse(row.labels || '[]'),
+    baseBranch: row.base_branch || '',
+  }));
+}
+
+// ─── Issue scanning ──────────────────────────────────────
+
+function getRepoFromProject(projectPath: string): string | null {
+  try {
+    return execSync('gh repo view --json nameWithOwner -q .nameWithOwner', {
+      cwd: projectPath, encoding: 'utf-8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim() || null;
+  } catch {
+    try {
+      const url = execSync('git remote get-url origin', {
+        cwd: projectPath, encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'],
+      }).trim();
+      return url.replace(/.*github\.com[:/]/, '').replace(/\.git$/, '') || null;
+    } catch { return null; }
+  }
+}
+
+function fetchOpenIssues(projectPath: string, labels: string[]): { number: number; title: string; error?: string }[] {
+  const repo = getRepoFromProject(projectPath);
+  if (!repo) return [{ number: -1, title: '', error: 'Could not detect GitHub repo. Run: gh auth login' }];
+  try {
+    const labelFilter = labels.length > 0 ? ` --label "${labels.join(',')}"` : '';
+    const out = execSync(`gh issue list --state open --json number,title${labelFilter} -R ${repo}`, {
+      cwd: projectPath, encoding: 'utf-8', timeout: 15000, stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return JSON.parse(out) || [];
+  } catch (e: any) {
+    const msg = e.stderr?.toString() || e.message || 'gh CLI failed';
+    return [{ number: -1, title: '', error: msg.includes('auth') ? 'GitHub CLI not authenticated. Run: gh auth login' : msg }];
+  }
+}
+
+function isProcessed(projectPath: string, issueNumber: number): boolean {
+  const row = db().prepare('SELECT 1 FROM issue_autofix_processed WHERE project_path = ? AND issue_number = ?')
+    .get(projectPath, issueNumber);
+  return !!row;
+}
+
+function markProcessed(projectPath: string, issueNumber: number, pipelineId: string): void {
+  db().prepare(`
+    INSERT OR REPLACE INTO issue_autofix_processed (project_path, issue_number, pipeline_id, status)
+    VALUES (?, ?, ?, 'processing')
+  `).run(projectPath, issueNumber, pipelineId);
+}
+
+export function updateProcessedStatus(projectPath: string, issueNumber: number, status: string, prNumber?: number): void {
+  if (prNumber) {
+    db().prepare('UPDATE issue_autofix_processed SET status = ?, pr_number = ? WHERE project_path = ? AND issue_number = ?')
+      .run(status, prNumber, projectPath, issueNumber);
+  } else {
+    db().prepare('UPDATE issue_autofix_processed SET status = ? WHERE project_path = ? AND issue_number = ?')
+      .run(status, projectPath, issueNumber);
+  }
+}
+
+/** Reset a processed issue so it can be re-scanned or retried */
+export function resetProcessedIssue(projectPath: string, issueNumber: number): void {
+  db().prepare('DELETE FROM issue_autofix_processed WHERE project_path = ? AND issue_number = ?')
+    .run(projectPath, issueNumber);
+}
+
+export function getProcessedIssues(projectPath: string): { issueNumber: number; pipelineId: string; prNumber: number | null; status: string; createdAt: string }[] {
+  ensureTable();
+  return (db().prepare('SELECT * FROM issue_autofix_processed WHERE project_path = ? ORDER BY created_at DESC').all(projectPath) as any[]).map(r => ({
+    issueNumber: r.issue_number,
+    pipelineId: r.pipeline_id,
+    prNumber: r.pr_number,
+    status: r.status,
+    createdAt: r.created_at,
+  }));
+}
+
+// ─── Scan & trigger ──────────────────────────────────────
+
+function saveLastScan(projectPath: string) {
+  const now = Date.now();
+  scannerState.lastScan.set(projectPath, now);
+  try { db().prepare('UPDATE issue_autofix_config SET last_scan_at = ? WHERE project_path = ?').run(new Date(now).toISOString(), projectPath); } catch {}
+}
+
+function loadLastScan(projectPath: string): number | null {
+  try {
+    const row = db().prepare('SELECT last_scan_at FROM issue_autofix_config WHERE project_path = ?').get(projectPath) as any;
+    return row?.last_scan_at ? new Date(row.last_scan_at).getTime() : null;
+  } catch { return null; }
+}
+
+export function scanAndTrigger(config: IssueAutofixConfig): { triggered: number; issues: number[]; total: number; error?: string } {
+  saveLastScan(config.projectPath);
+  const issues = fetchOpenIssues(config.projectPath, config.labels);
+
+  // Check for errors
+  if (issues.length === 1 && (issues[0] as any).error) {
+    return { triggered: 0, issues: [], total: 0, error: (issues[0] as any).error };
+  }
+
+  const triggered: number[] = [];
+
+  for (const issue of issues) {
+    if (issue.number < 0) continue;
+    if (isProcessed(config.projectPath, issue.number)) continue;
+
+    try {
+      const pipeline = startPipeline('issue-fix-and-review', {
+        issue_id: String(issue.number),
+        project: config.projectName,
+        base_branch: config.baseBranch || 'auto-detect',
+      });
+      markProcessed(config.projectPath, issue.number, pipeline.id);
+      triggered.push(issue.number);
+      console.log(`[issue-scanner] Triggered fix for #${issue.number} "${issue.title}" in ${config.projectName} (pipeline: ${pipeline.id})`);
+    } catch (e) {
+      console.error(`[issue-scanner] Failed to trigger for #${issue.number}:`, e);
+    }
+  }
+
+  return { triggered: triggered.length, issues: triggered, total: issues.length };
+}
+
+// ─── Periodic scanner ────────────────────────────────────
+
+// Use global symbol to prevent multiple workers from starting duplicate scanners
+const scannerKey = Symbol.for('forge-issue-scanner');
+const gAny = globalThis as any;
+if (!gAny[scannerKey]) gAny[scannerKey] = { timers: new Map<string, NodeJS.Timeout>(), started: false, lastScan: new Map<string, number>() };
+const scannerState = gAny[scannerKey] as { timers: Map<string, NodeJS.Timeout>; started: boolean; lastScan: Map<string, number> };
+
+export function startScanner() {
+  if (scannerState.started) return;
+  scannerState.started = true;
+  ensureTable();
+  const configs = listConfigs();
+  for (const config of configs) {
+    if (config.interval > 0 && !scannerState.timers.has(config.projectPath)) {
+      const projectPath = config.projectPath;
+      const intervalMs = config.interval * 60 * 1000;
+
+      // Restore lastScan from DB
+      const dbLastScan = loadLastScan(projectPath);
+      if (dbLastScan) {
+        scannerState.lastScan.set(projectPath, dbLastScan);
+      } else {
+        scannerState.lastScan.set(projectPath, Date.now());
+      }
+
+      // Calculate delay: if time since lastScan > interval, run soon; otherwise wait remaining
+      const elapsed = Date.now() - (scannerState.lastScan.get(projectPath) || 0);
+      const firstDelay = Math.max(0, intervalMs - elapsed);
+
+      const startInterval = () => {
+        const timer = setInterval(() => {
+          const latestConfig = getConfig(projectPath);
+          if (!latestConfig || !latestConfig.enabled) return;
+          try { scanAndTrigger(latestConfig); } catch {}
+        }, intervalMs);
+        scannerState.timers.set(projectPath, timer);
+      };
+
+      // First run after remaining delay, then regular interval
+      if (firstDelay > 0) {
+        setTimeout(() => {
+          const latestConfig = getConfig(projectPath);
+          if (latestConfig?.enabled) { try { scanAndTrigger(latestConfig); } catch {} }
+          startInterval();
+        }, firstDelay);
+      } else {
+        // Overdue — run immediately then start interval
+        const latestConfig = getConfig(projectPath);
+        if (latestConfig?.enabled) { try { scanAndTrigger(latestConfig); } catch {} }
+        startInterval();
+      }
+
+      const nextTime = new Date((scannerState.lastScan.get(projectPath) || Date.now()) + intervalMs);
+      console.log(`[issue-scanner] Started scanner for ${config.projectName} (every ${config.interval}min, next: ${nextTime.toLocaleTimeString()})`);
+    }
+  }
+}
+
+export function getNextScanTime(projectPath: string): { lastScan: string | null; nextScan: string | null } {
+  const last = scannerState.lastScan.get(projectPath);
+  const config = getConfig(projectPath);
+  if (!last || !config || !config.enabled || config.interval <= 0) return { lastScan: null, nextScan: null };
+  const next = last + config.interval * 60 * 1000;
+  return {
+    lastScan: new Date(last).toISOString(),
+    nextScan: new Date(next).toISOString(),
+  };
+}
+
+export function restartScanner() {
+  for (const timer of scannerState.timers.values()) clearInterval(timer);
+  scannerState.timers.clear();
+  scannerState.started = false;
+  startScanner();
+}
+
+export function stopScanner(projectPath: string) {
+  const timer = scannerState.timers.get(projectPath);
+  if (timer) {
+    clearInterval(timer);
+    scannerState.timers.delete(projectPath);
+  }
+}