@aion0/forge 0.10.47 → 0.10.49

package/components/SettingsModal.tsx

@@ -205,6 +205,126 @@ function SecretField({ label, description, isSet, onEdit }: {
   );
 }
 
+// ─── API Key Section ───────────────────────────────────────────
+
+interface ApiKeyPublic { id: string; name: string; prefix: string; createdAt: string; lastUsedAt: string | null }
+
+function ApiKeySection() {
+  const [keys, setKeys] = useState<ApiKeyPublic[]>([]);
+  // Whether an admin password is configured — read from the keys endpoint's
+  // purpose-built `adminConfigured` flag, not inferred from an unrelated secret
+  // field, so this section isn't coupled to how the admin password is stored.
+  const [adminSet, setAdminSet] = useState(false);
+  const [dialog, setDialog] = useState<null | { mode: 'generate' } | { mode: 'revoke'; id: string; prefix: string }>(null);
+  const [adminPassword, setAdminPassword] = useState('');
+  const [name, setName] = useState('agent key');
+  const [error, setError] = useState('');
+  const [busy, setBusy] = useState(false);
+  const [revealed, setRevealed] = useState('');
+  const [copied, setCopied] = useState(false);
+
+  const refresh = async () => {
+    try { const r = await fetch('/api/auth/keys'); const d = await r.json(); setKeys(d.keys || []); setAdminSet(!!d.adminConfigured); } catch { /* ignore */ }
+  };
+  useEffect(() => { refresh(); }, []);
+
+  const closeDialog = () => { setDialog(null); setAdminPassword(''); setError(''); };
+
+  const generate = async () => {
+    setBusy(true); setError('');
+    try {
+      const r = await fetch('/api/auth/keys', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ name, adminPassword }) });
+      const d = await r.json();
+      if (!r.ok) { setError(d.error || 'Failed to generate key'); setBusy(false); return; }
+      setRevealed(d.key); setCopied(false); closeDialog(); refresh();
+    } catch (e) { setError((e as Error).message || 'Failed'); }
+    setBusy(false);
+  };
+
+  const revoke = async () => {
+    if (dialog?.mode !== 'revoke') return;
+    setBusy(true); setError('');
+    try {
+      const r = await fetch(`/api/auth/keys/${dialog.id}`, { method: 'DELETE', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ adminPassword }) });
+      const d = await r.json().catch(() => ({}));
+      if (!r.ok) { setError(d.error || 'Failed to revoke'); setBusy(false); return; }
+      closeDialog(); refresh();
+    } catch (e) { setError((e as Error).message || 'Failed'); }
+    setBusy(false);
+  };
+
+  const inputClass = "w-full px-2 py-1.5 bg-[var(--bg-tertiary)] border border-[var(--border)] rounded text-xs text-[var(--text-primary)] font-mono focus:outline-none focus:border-[var(--accent)]";
+
+  return (
+    <div className="space-y-2" data-testid="api-key-section">
+      <label className="text-xs text-[var(--text-secondary)] font-semibold uppercase">API Key</label>
+      <p className="text-[10px] text-[var(--text-secondary)]">
+        Lets an agent or service act on your behalf — MCP operations and automation — without sharing your admin password. Generated, revocable, shown once.
+      </p>
+
+      {!adminSet ? (
+        <p className="text-[10px] text-[var(--text-secondary)] italic">Set an admin password first to generate an API key.</p>
+      ) : (
+        <>
+          {revealed && (
+            <div className="p-2 bg-[var(--bg-tertiary)] border border-[var(--accent)] rounded space-y-1" data-testid="api-key-revealed">
+              <p className="text-[9px] text-[var(--accent)]">⚠ Copy now — you won't be able to see this again.</p>
+              <div className="flex items-center gap-2">
+                <code className="flex-1 text-[10px] font-mono text-[var(--text-primary)] break-all">{revealed}</code>
+                <button onClick={() => { navigator.clipboard?.writeText(revealed); setCopied(true); }} className="text-[10px] px-2 py-1 border border-[var(--accent)] text-[var(--accent)] rounded hover:bg-[var(--accent)] hover:text-white shrink-0">{copied ? 'Copied' : 'Copy'}</button>
+              </div>
+              <button onClick={() => { setRevealed(''); setCopied(false); }} className="text-[9px] text-[var(--text-secondary)] hover:text-[var(--text-primary)]">Dismiss</button>
+            </div>
+          )}
+
+          {keys.length === 0 ? (
+            <button onClick={() => setDialog({ mode: 'generate' })} data-testid="api-key-generate" className="text-[10px] px-2 py-1 border border-[var(--accent)] text-[var(--accent)] rounded hover:bg-[var(--accent)] hover:text-white">Generate API Key</button>
+          ) : (
+            <div className="space-y-1">
+              {keys.map(k => (
+                <div key={k.id} className="flex items-center justify-between gap-2 px-2 py-1.5 bg-[var(--bg-tertiary)] border border-[var(--border)] rounded">
+                  <div className="min-w-0">
+                    <div className="text-xs font-mono text-[var(--text-primary)] truncate">{k.prefix}</div>
+                    <div className="text-[9px] text-[var(--text-secondary)]">{k.name} · created {k.createdAt?.slice(0, 10)} · last used {k.lastUsedAt ? new Date(k.lastUsedAt).toLocaleDateString() : 'never'}</div>
+                  </div>
+                  <button onClick={() => setDialog({ mode: 'revoke', id: k.id, prefix: k.prefix })} className="text-[10px] px-2 py-1 border border-[var(--red)] text-[var(--red)] rounded hover:bg-[var(--red)] hover:text-white shrink-0">Revoke</button>
+                </div>
+              ))}
+              <button onClick={() => setDialog({ mode: 'generate' })} data-testid="api-key-generate" className="text-[10px] px-2 py-1 border border-[var(--accent)] text-[var(--accent)] rounded hover:bg-[var(--accent)] hover:text-white">Generate New Key</button>
+            </div>
+          )}
+        </>
+      )}
+
+      {dialog && (
+        <div className="fixed inset-0 bg-black/60 flex items-center justify-center z-[60]" onClick={closeDialog}>
+          <div className="bg-[var(--bg-secondary)] border border-[var(--border)] rounded-lg w-[380px] p-4 space-y-3" onClick={e => e.stopPropagation()}>
+            <h3 className="text-xs font-bold">{dialog.mode === 'generate' ? 'Generate API Key' : 'Revoke API Key'}</h3>
+            {dialog.mode === 'revoke' && (
+              <p className="text-[10px] text-[var(--text-secondary)]">Revoke <code className="text-[var(--text-primary)]">{dialog.prefix}</code>? Any agent using it will stop working.</p>
+            )}
+            {dialog.mode === 'generate' && (
+              <div className="space-y-1">
+                <label className="text-[10px] text-[var(--text-secondary)]">Key name</label>
+                <input value={name} onChange={e => setName(e.target.value)} placeholder="e.g. laptop, ci, agent" className={inputClass} data-testid="api-key-name" />
+              </div>
+            )}
+            <div className="space-y-1">
+              <label className="text-[10px] text-[var(--text-secondary)]">Admin password</label>
+              <SecretInput value={adminPassword} onChange={v => { setAdminPassword(v); setError(''); }} placeholder="Enter admin password" className={inputClass} />
+            </div>
+            {error && <p className="text-[10px] text-[var(--red)]" data-testid="api-key-error">{error}</p>}
+            <div className="flex justify-end gap-2 pt-1">
+              <button onClick={closeDialog} className="px-3 py-1.5 text-xs text-[var(--text-secondary)] hover:text-[var(--text-primary)]">Cancel</button>
+              <button onClick={dialog.mode === 'generate' ? generate : revoke} disabled={!adminPassword || busy} data-testid="api-key-confirm" className={`px-3 py-1.5 text-xs text-white rounded hover:opacity-90 disabled:opacity-50 ${dialog.mode === 'revoke' ? 'bg-[var(--red)]' : 'bg-[var(--accent)]'}`}>{busy ? '...' : dialog.mode === 'generate' ? 'Generate' : 'Revoke'}</button>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
 // ─── Settings Modal ────────────────────────────────────────────
 
 interface Settings {
@@ -873,6 +993,9 @@ export default function SettingsModal({ onClose }: { onClose: () => void }) {
           </p>
         </div>
 
+        {/* API Key */}
+        <ApiKeySection />
+
         {/* Actions */}
         <div className="flex items-center justify-between pt-2 border-t border-[var(--border)]">
           <span className="text-[10px] text-[var(--green)]">

package/lib/api-auth.ts

@@ -0,0 +1,50 @@
+/**
+ * Request authentication for Forge's API surface (API-key / session).
+ *
+ * A request is authenticated if it carries a valid persistent API key — a
+ * `forge_sk_`-prefixed key in Authorization: Bearer, the x-forge-token header,
+ * or the forge-api-token cookie — OR a VALIDATED NextAuth browser session. The
+ * session is checked with the framework decoder (auth()), NOT by cookie presence
+ * — a forged or unsigned session-token cookie does not pass. The legacy
+ * admin-minted in-memory token is NOT handled here; routes that accept it call
+ * isValidToken() in addition. Centralizes the key+session check so those routes
+ * share one implementation. (Named api-auth to avoid colliding with lib/auth.ts,
+ * the NextAuth config.)
+ *
+ * Route handlers call isAuthenticated() for the combined key-or-session check.
+ */
+
+import { verifyApiKey } from './api-keys';
+import { auth } from './auth';
+
+/** Extract a bearer/token credential from the request, if any. */
+export function extractToken(req: Request): string | null {
+  const authz = req.headers.get('authorization');
+  if (authz && /^Bearer\s+/i.test(authz)) return authz.replace(/^Bearer\s+/i, '').trim();
+  const header = req.headers.get('x-forge-token');
+  if (header) return header;
+  const cookie = req.headers.get('cookie') || '';
+  const m = cookie.match(/forge-api-token=([^;]+)/);
+  return m ? m[1] : null;
+}
+
+/** True if the request carries a valid persistent API key — a `forge_sk_` key in
+ *  Authorization: Bearer, x-forge-token, or the forge-api-token cookie. (The
+ *  legacy admin-minted token is checked separately by isValidToken.) */
+export function hasValidApiKey(req: Request): boolean {
+  return verifyApiKey(extractToken(req));
+}
+
+/** True if there is a VALIDATED NextAuth browser session for the current request.
+ *  Uses the framework decoder (auth()) — NOT cookie presence — so a forged or
+ *  unsigned session-token cookie does not pass. Must be called within a request
+ *  context (route handler / server component); returns false otherwise. */
+export async function hasSession(): Promise<boolean> {
+  try { return !!(await auth()); } catch { return false; }
+}
+
+/** True if the request presents a valid API key or a validated browser session. */
+export async function isAuthenticated(req: Request): Promise<boolean> {
+  if (hasValidApiKey(req)) return true;
+  return hasSession();
+}

package/lib/api-keys.ts

@@ -0,0 +1,157 @@
+/**
+ * API key store — credentials for services/agents acting on the user's behalf
+ * (MCP operations, automation), distinct from the human admin password.
+ *
+ * Keys are stored HASHED (sha256) in <dataDir>/api-keys.json — the plaintext is
+ * shown to the user exactly once at creation and is never recoverable from disk.
+ * Verification is constant-time. Minting/revoking is gated by the admin password
+ * at the route layer.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes, createHash, timingSafeEqual } from 'node:crypto';
+import { getDataDir } from './dirs';
+
+const KEY_PREFIX = 'forge_sk_';
+
+export interface ApiKeyRecord {
+  id: string;
+  name: string;
+  prefix: string;        // non-secret display prefix, e.g. "forge_sk_a1b2c3…"
+  hash: string;          // sha256(full key)
+  createdAt: string;
+  lastUsedAt: string | null;
+}
+
+/** Public view — never includes the hash. */
+export type ApiKeyPublic = Omit<ApiKeyRecord, 'hash'>;
+
+function file(): string {
+  return join(getDataDir(), 'api-keys.json');
+}
+
+// Parsed-records cache keyed by file mtime. verifyApiKey() runs on every /api/mcp
+// POST, so re-reading + JSON.parse per call is wasted I/O. Any write (this process
+// via persist(), or another worker) changes mtime, so the cache self-invalidates.
+let _cache: { mtimeMs: number; keys: ApiKeyRecord[] } | null = null;
+
+function load(): ApiKeyRecord[] {
+  try {
+    const fp = file();
+    if (!existsSync(fp)) { _cache = null; return []; }
+    const mtimeMs = statSync(fp).mtimeMs;
+    if (_cache && _cache.mtimeMs === mtimeMs) return _cache.keys;
+    const parsed = JSON.parse(readFileSync(fp, 'utf-8'));
+    const keys = Array.isArray(parsed) ? parsed : [];
+    _cache = { mtimeMs, keys };
+    return keys;
+  } catch {
+    return [];
+  }
+}
+
+function persist(keys: ApiKeyRecord[]): void {
+  const dir = getDataDir();
+  mkdirSync(dir, { recursive: true });
+  // Atomic write: serialize to a fresh 0600 temp file in the same dir, then
+  // rename over the target. A crash or a concurrent reader never sees a
+  // half-written api-keys.json, and the rename is atomic on the same filesystem.
+  const tmp = join(dir, `.api-keys.${randomBytes(6).toString('hex')}.tmp`);
+  try {
+    writeFileSync(tmp, JSON.stringify(keys, null, 2), { mode: 0o600 });
+    renameSync(tmp, file());
+    _cache = null; // invalidate; next load() re-reads at the new mtime
+  } catch (e) {
+    try { rmSync(tmp, { force: true }); } catch { /* leave nothing behind */ }
+    throw e;
+  }
+}
+
+function sha256(s: string): string {
+  return createHash('sha256').update(s).digest('hex');
+}
+
+const toPublic = (r: ApiKeyRecord): ApiKeyPublic => ({
+  id: r.id, name: r.name, prefix: r.prefix, createdAt: r.createdAt, lastUsedAt: r.lastUsedAt,
+});
+
+/** Create a new key. Returns the plaintext ONCE (caller must show + discard).
+ *
+ *  createApiKey/revokeApiKey load()→persist() the whole array, loading immediately
+ *  before the write (same minimal in-process window as touchLastUsed). They do NOT
+ *  take a file lock, so two WORKERS mutating concurrently still last-writer-win and
+ *  one change is dropped. Acceptable here because minting/revoking is admin-gated and
+ *  rare; if that stops holding, wrap the read-modify-write below in a short lock. */
+export function createApiKey(name: string): { key: string; record: ApiKeyPublic } {
+  const key = `${KEY_PREFIX}${randomBytes(24).toString('base64url')}`;
+  const record: ApiKeyRecord = {
+    id: randomBytes(6).toString('hex'),
+    name: name.trim() || 'agent key',
+    prefix: `${key.slice(0, KEY_PREFIX.length + 6)}…`,
+    hash: sha256(key),
+    createdAt: new Date().toISOString(),
+    lastUsedAt: null,
+  };
+  const keys = load();
+  keys.push(record);
+  persist(keys);
+  return { key, record: toPublic(record) };
+}
+
+export function listApiKeys(): ApiKeyPublic[] {
+  return load().map(toPublic);
+}
+
+export function revokeApiKey(id: string): boolean {
+  const keys = load();
+  const idx = keys.findIndex((k) => k.id === id);
+  if (idx < 0) return false;
+  keys.splice(idx, 1);
+  persist(keys);
+  return true;
+}
+
+/** Bump one key's lastUsedAt by id, re-loading the freshest file immediately
+ *  before the write. verifyApiKey must NOT persist the array it read before the
+ *  hash compare: a concurrent createApiKey/revokeApiKey in another worker would
+ *  be clobbered (last-writer-wins on the whole file). Re-loading here shrinks the
+ *  window to the load→write span and, if the key was revoked meanwhile, leaves it
+ *  deleted (find returns undefined → no write) instead of resurrecting it. */
+function touchLastUsed(id: string, whenISO: string): void {
+  const keys = load();
+  const k = keys.find((r) => r.id === id);
+  if (!k) return;
+  k.lastUsedAt = whenISO;
+  persist(keys);
+}
+
+/** Constant-time verification of a presented key. Bumps lastUsedAt (throttled). */
+export function verifyApiKey(presented: string | null | undefined): boolean {
+  if (!presented || !presented.startsWith(KEY_PREFIX)) return false;
+  const presentedHash = Buffer.from(sha256(presented));
+  const keys = load();
+  let matched: ApiKeyRecord | undefined;
+  for (const k of keys) {
+    const stored = Buffer.from(k.hash);
+    if (stored.length === presentedHash.length && timingSafeEqual(stored, presentedHash)) {
+      matched = k;
+      break;
+    }
+  }
+  if (!matched) return false;
+  // Throttle the lastUsedAt write to at most once a minute to avoid disk churn;
+  // write through a fresh re-load (touchLastUsed) so a concurrent mint/revoke
+  // isn't lost.
+  const now = Date.now();
+  // A corrupt (unparseable) lastUsedAt yields NaN; treat it as stale so the bad
+  // value self-heals on the next use instead of freezing forever.
+  const last = matched.lastUsedAt ? new Date(matched.lastUsedAt).getTime() : NaN;
+  if (!Number.isFinite(last) || now - last > 60_000) {
+    // Bookkeeping only — a failed lastUsedAt write (e.g. api-keys.json owned by a
+    // different user after a local `forge mcp install`) must never turn a valid
+    // key into an auth error.
+    try { touchLastUsed(matched.id, new Date(now).toISOString()); } catch { /* ignore */ }
+  }
+  return true;
+}

package/lib/auth/idp-login.ts

@@ -103,14 +103,36 @@ function readIdpBlocks(): IdpTemplateBlock[] {
   return tryRead() || [];
 }
 
-/** First installed SP from saml_sps wins as trigger. */
+/** Pick the SP whose tab we'll open to trigger the SAML flow.
+ *
+ *  Preference order:
+ *   1. A SP whose login-status cache currently shows ✗ — opening it forces
+ *      a SAML redirect to the IdP, which is exactly what we want when the
+ *      IdP cookie has expired even though some sibling SPs still have a
+ *      valid session cookie (Mantis can be ✓ while pmdb/tp are ✗ because
+ *      per-SP cookies are independent of the IdP SSO state).
+ *   2. Otherwise first installed SP with a base_url (legacy fallback).
+ *
+ *  Without (1) the IdP login flow would open Mantis (first in saml_sps),
+ *  see the cookie still good, declare "no form needed", and exit — leaving
+ *  the broken siblings unrefreshed.
+ */
 function pickTriggerUrl(saml_sps: string[]): string | null {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { getCachedResult } = require('./login-status') as typeof import('./login-status');
+  let fallback: string | null = null;
   for (const id of saml_sps) {
     const c = getInstalledConnector(id);
     const url = (c?.config as { base_url?: string } | undefined)?.base_url;
-    if (url) return url.replace(/\/+$/, '/');
+    if (!url) continue;
+    const normalized = url.replace(/\/+$/, '/');
+    fallback ||= normalized;
+    const cached = getCachedResult(`connector:${id}`);
+    if (cached && cached.ok === false) {
+      return normalized;
+    }
   }
-  return null;
+  return fallback;
 }
 
 async function runOneIdp(block: IdpTemplateBlock, req: IdpLoginRequest): Promise<IdpLoginEntry> {

package/lib/jobs/store.ts

@@ -313,6 +313,31 @@ export function setNextRunAt(id: string, nextRunAt: string | null): void {
   db().prepare("UPDATE jobs SET next_run_at = ?, last_run_at = datetime('now') WHERE id = ?").run(nextRunAt, id);
 }
 
+/** Recompute next_run_at from the job's trigger without touching last_run_at.
+ *  Use on resume: cancelJobDrain nulled next_run_at, and NULL = due now, so
+ *  a bare re-enable would fire off-schedule. once-in-the-past fires next tick;
+ *  period seeds now + interval to avoid an instant re-run. */
+export function seedNextRunAt(id: string): void {
+  ensureSchema();
+  const j = getJob(id);
+  if (!j) return;
+  const fmt = (d: Date) => d.toISOString().replace('T', ' ').slice(0, 19);
+  let next: string | null = null;
+  if (j.schedule_kind === 'once' && j.schedule_at) {
+    const t = new Date(j.schedule_at);
+    if (!Number.isNaN(t.getTime())) next = fmt(t);
+  } else if (j.schedule_kind === 'cron' && j.schedule_cron) {
+    try {
+      const iter = CronExpressionParser.parse(j.schedule_cron, { currentDate: new Date() });
+      next = fmt(iter.next().toDate());
+    } catch { next = null; }
+  } else if (j.schedule_kind === 'period') {
+    const mins = j.schedule_interval_minutes > 0 ? j.schedule_interval_minutes : 30;
+    next = fmt(new Date(Date.now() + mins * 60_000));
+  }
+  db().prepare('UPDATE jobs SET next_run_at = ? WHERE id = ?').run(next, id);
+}
+
 /** Jobs due to run: enabled AND (next_run_at IS NULL OR next_run_at <= now). */
 export function getDueJobs(): Job[] {
   ensureSchema();

package/lib/projects.ts

@@ -1,7 +1,7 @@
 import { readdirSync, existsSync, statSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve, isAbsolute, parse } from 'node:path';
 import { homedir } from 'node:os';
-import { loadSettings } from './settings';
+import { loadSettings, saveSettings } from './settings';
 import { getDataDir } from './dirs';
 
 export interface LocalProject {
@@ -75,11 +75,22 @@ function scratchProject(): LocalProject {
   };
 }
 
+let scanCache: { at: number; key: string; result: LocalProject[] } | null = null;
+const SCAN_TTL_MS = 5_000;
+
+/** Drop the scanProjects cache (call after registering/unregistering a root). */
+export function invalidateProjectScan(): void { scanCache = null; }
+
 export function scanProjects(): LocalProject[] {
   const settings = loadSettings();
-  const roots = settings.projectRoots;
+  const roots = settings.projectRoots || [];
+  const cacheKey = roots.join('\n');
+  const now = Date.now();
+  if (scanCache && scanCache.key === cacheKey && now - scanCache.at < SCAN_TTL_MS) {
+    return scanCache.result;
+  }
 
-  if (roots.length === 0) return [];
+  if (roots.length === 0) { scanCache = { at: now, key: cacheKey, result: [] }; return []; }
 
   const projects: LocalProject[] = [];
 
@@ -118,7 +129,9 @@ export function scanProjects(): LocalProject[] {
   // Prepend the synthetic scratch project so the UI surfaces it as a
   // first-class option. It's stamped with the current date so it tends
   // to sort to the top — that's intentional: it's the default fallback.
-  return [scratchProject(), ...projects.sort((a, b) => b.lastModified.localeCompare(a.lastModified))];
+  const result = [scratchProject(), ...projects.sort((a, b) => b.lastModified.localeCompare(a.lastModified))];
+  scanCache = { at: now, key: cacheKey, result };
+  return result;
 }
 
 function detectLanguage(projectPath: string): string | null {
@@ -234,3 +247,64 @@ export function getProjectClaudeMd(projectPath: string): string | null {
   if (!existsSync(claudeMdPath)) return null;
   return readFileSync(claudeMdPath, 'utf-8');
 }
+
+/** Register a project root — a directory whose immediate subdirectories Forge
+ *  lists as projects (see scanProjects). Idempotent; validates the path is an
+ *  existing directory. Returns the normalized root and whether it was already
+ *  registered. */
+const MAX_ROOT_SUBDIRS = 200;
+
+export function addProjectRoot(rootPath: string): {
+  ok: boolean; root: string; error?: string; alreadyRegistered?: boolean;
+} {
+  const trimmed = (rootPath || '').trim();
+  if (!trimmed) return { ok: false, root: '', error: 'Path is required' };
+  // Require an absolute path: resolve('') is process.cwd() and a relative path
+  // resolves against the server's cwd — neither is a project root the caller meant.
+  if (!isAbsolute(trimmed)) return { ok: false, root: trimmed, error: 'Path must be absolute' };
+  const root = resolve(trimmed);
+  if (!existsSync(root)) return { ok: false, root, error: 'Path does not exist' };
+  try {
+    if (!statSync(root).isDirectory()) return { ok: false, root, error: 'Path is not a directory' };
+  } catch {
+    return { ok: false, root, error: 'Path is not accessible' };
+  }
+  // A root is meant to CONTAIN projects, not be a giant tree. Refuse the
+  // filesystem root and absurdly broad dirs so scanProjects stays cheap.
+  if (root === parse(root).root) {
+    return { ok: false, root, error: 'Refusing to register the filesystem root' };
+  }
+  let subdirs = 0;
+  try {
+    for (const e of readdirSync(root, { withFileTypes: true })) {
+      if (e.isDirectory() && !e.name.startsWith('.') && ++subdirs > MAX_ROOT_SUBDIRS) break;
+    }
+  } catch {
+    return { ok: false, root, error: 'Path is not accessible' };
+  }
+  if (subdirs > MAX_ROOT_SUBDIRS) {
+    return { ok: false, root, error: `Too many subdirectories (>${MAX_ROOT_SUBDIRS}); point at the folder that directly contains your repos` };
+  }
+  const settings = loadSettings();
+  const roots = settings.projectRoots || [];
+  if (roots.includes(root)) return { ok: true, root, alreadyRegistered: true };
+  settings.projectRoots = [...roots, root];
+  saveSettings(settings);
+  invalidateProjectScan();
+  return { ok: true, root };
+}
+
+/** Unregister a project root. Does not touch files — only stops scanProjects
+ *  from listing its subdirectories as projects. */
+export function removeProjectRoot(rootPath: string): { ok: boolean; root: string; error?: string } {
+  const root = resolve((rootPath || '').trim());
+  const settings = loadSettings();
+  const roots = settings.projectRoots || [];
+  if (!roots.includes(root)) {
+    return { ok: false, root, error: `Not a registered root. Registered: ${roots.join(', ') || 'none'}` };
+  }
+  settings.projectRoots = roots.filter((r) => r !== root);
+  saveSettings(settings);
+  invalidateProjectScan();
+  return { ok: true, root };
+}

package/lib/settings.ts

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, rmSync } from 'node:fs';
 import { join, dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
 import YAML from 'yaml';
 import { encryptSecret, decryptSecret, isEncrypted, SECRET_FIELDS } from './crypto';
 import { getDataDir } from './dirs';
@@ -423,7 +424,16 @@ export function saveSettings(settings: Settings) {
   }
   // Encrypt nested apiKeys
   encryptNestedSecrets(toSave);
-  writeFileSync(SETTINGS_FILE, YAML.stringify(toSave), 'utf-8');
+  // Atomic write: serialize to a temp file in the same dir, then rename over the
+  // target so a crash or concurrent reader never sees a half-written settings.yaml.
+  const tmp = join(dir, `.settings.${randomBytes(6).toString('hex')}.tmp`);
+  try {
+    writeFileSync(tmp, YAML.stringify(toSave), 'utf-8');
+    renameSync(tmp, SETTINGS_FILE);
+  } catch (e) {
+    try { rmSync(tmp, { force: true }); } catch { /* leave nothing behind */ }
+    throw e;
+  }
 }
 
 /** Verify a secret field's current value */

package/mcp/README.md

@@ -0,0 +1,46 @@
+# Forge Management MCP
+
+Manage Forge — projects, tasks, pipelines, schedules, jobs, connectors, usage — from an
+MCP client like Claude Code, instead of clicking through the UI. It manages Forge; it does
+not read your project files or run coding tasks (that's the separate workspace agent MCP
+on `:8406`).
+
+## Add it to Claude Code
+
+```bash
+forge mcp install
+```
+
+This mints an API key if you don't have one and registers the server with Claude Code.
+Run `/mcp` in a session to confirm. No admin password — running `forge` already proves
+local access, so the key is minted directly on disk (into `FORGE_DATA_DIR`, else
+`~/.forge/data`; set `FORGE_DATA_DIR` for a non-default instance); the running server
+picks it up automatically (and need not even be up).
+
+Options: `--http` (register the HTTP transport instead of the stdio proxy), `--scope user`
+(use it in every project), `--remote https://forge.example.com` (target a remote Forge —
+set `FORGE_API_KEY` first, since the remote's data dir isn't local), `--print` (print the
+`claude mcp add` command instead of running it).
+
+## What you can do
+
+Tools cover projects, tasks, pipelines, schedules and jobs, connectors, the marketplace,
+usage and status, log tailing, and workspace agents. Ask "what forge tools do you have?"
+to list them.
+
+## How it works
+
+Runs in-process at `/api/mcp` (Streamable HTTP), behind Forge's existing auth — same port
+as the web UI. All logic stays in the server: tools call `lib/` in-process and the wire
+carries named intents, never SQL. The `forge mcp` proxy (`cli/mcp-proxy.ts`) is
+transport-only; the same `mcp/server.ts` backs both the HTTP route and the proxy.
+
+Manual setup, if you're not using `forge mcp install`:
+
+```bash
+forge key create "claude-code" --save     # mint + save a key (no password — local)
+claude mcp add forge -- forge mcp          # stdio proxy (reads ~/.forge/mcp-key)
+# or, direct HTTP:
+claude mcp add --transport http forge http://localhost:8403/api/mcp \
+  --header "Authorization: Bearer forge_sk_..."
+```

package/mcp/server.ts

@@ -0,0 +1,30 @@
+/**
+ * Forge Management MCP — server factory.
+ *
+ * Transport-agnostic: this builds the McpServer and registers tools. It knows
+ * nothing about stdio vs HTTP. The Next.js route (`app/api/mcp`) hosts it over
+ * Streamable HTTP today; a hosted entrypoint can wrap the same server later.
+ *
+ * All tools run IN-PROCESS inside the Forge server and call `lib/` directly.
+ * The client never touches the database — see mcp/README.md (the contract).
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerTools } from './tools/index';
+
+/** Per-connection context, resolved server-side from the authenticated request. */
+export interface ManagementContext {
+  /** Reserved for future per-key audit logging — not yet wired into tools. */
+  actor?: string;
+}
+
+export function createManagementMcpServer(ctx: ManagementContext = {}): McpServer {
+  const server = new McpServer({
+    name: 'forge-management',
+    version: '0.1.0',
+  });
+
+  registerTools(server, ctx);
+
+  return server;
+}