@aion0/forge 0.10.40 → 0.10.41

package/lib/help-docs/17-connectors.md

@@ -16,25 +16,21 @@ connector list; the user picks what they want from the marketplace.
 
 ## Marketplace flow
 
-1. On boot, Forge fetches `registry.json` from `connectorsRepoUrl`
-   (default `https://raw.githubusercontent.com/aiwatching/forge-connectors/main`)
-   and caches it at `<dataDir>/connectors/registry-cache.json`.
-2. The Settings → Connectors panel reads the cache and lists every
-   available connector with its install state:
-   - **Available** — in registry, not installed
-   - **Installed v0.5.0** — manifest on disk, config row present
-   - **Update 0.5 → 0.6** — registry has newer version
-3. Clicking **Install** fetches `<id>/manifest.yaml` from the registry,
-   writes it to `<dataDir>/connectors/<id>/manifest.yaml`, and adds a
-   row to `<dataDir>/connector-configs.json`.
-4. The user fills in settings (host URL, PAT, etc.) via the existing
-   settings UI in the extension or `/api/connectors/<id>/settings`.
-5. Chat tools become available the instant the manifest lands on disk —
-   no Forge restart.
-
-Sync re-runs every hour and on manual **Refresh** in the Settings panel.
-Network failures are silent — the cache from the last successful sync
-keeps the marketplace usable offline.
+1. On boot, Forge syncs every configured **marketplace source**:
+   - **Public** — default `https://raw.githubusercontent.com/aiwatching/forge-connectors/main` (override via `connectorsRepoUrl`). Fetched anonymously.
+   - **Enterprise repos** — any keys registered via Settings → Marketplace Providers (or `--enterprise-key=`). Each gets pulled via the GitHub Contents API with its bearer PAT. Sources are ordered by configured priority; the first one added wins on conflict.
+   Each source's `registry.json` is cached at `<dataDir>/connectors/sources/<source-id>/registry-cache.json`.
+2. The Settings → Connectors panel merges all source caches into a single marketplace view:
+   - Same id present in multiple sources → highest-priority source is "in use", lower sources land in `hidden_sources` (shown in the detail pane).
+   - Every row carries a source badge: `🌐 public` / `🔒 <tenant>` / `📦 local` (install-local upload).
+   - Install state: **Available** / **Installed v0.5.0** / **Update 0.5 → 0.6**.
+3. Clicking **Install** fetches `<id>/manifest.yaml` from the winning source, writes it to `<dataDir>/connectors/<id>/manifest.yaml`, and records `installed_source_id` in `<dataDir>/connector-configs.json`. The badge in the marketplace reflects that installed_source — not the current registry winner — so users can see "I installed mantis from fortinet" even after the public version bumps.
+4. The user fills in settings (host URL, PAT, etc.) via the existing settings UI in the extension or `/api/connectors/<id>/settings`.
+5. Chat tools become available the instant the manifest lands on disk — no Forge restart.
+
+Sync re-runs on manual **Refresh** in the Settings panel and after adding a new enterprise key. Network failures per-source are isolated — the offline cache from each source's last successful sync keeps the marketplace usable.
+
+See `01-settings.md` § Marketplace Providers for how to register enterprise keys and what the priority rules mean in practice.
 
 ## Repository layout
 
@@ -57,11 +53,18 @@ source of truth for that user.
 ```
 <dataDir>/
 ├── connectors/
-│   ├── registry-cache.json       last fetch from forge-connectors
-│   ├── mantis/manifest.yaml      installed manifest copy
+│   ├── sources/
+│   │   ├── public/
+│   │   │   ├── registry-cache.json    last fetch from public source
+│   │   │   └── wizard-template.json   optional wizard template cache
+│   │   └── enterprise-fortinet/       one dir per enterprise key
+│   │       ├── registry-cache.json
+│   │       └── wizard-template.json
+│   ├── mantis/manifest.yaml           installed manifest copy (one per id, regardless of source)
 │   ├── gitlab/manifest.yaml
 │   └── …
-└── connector-configs.json        { "<id>": { config, installed_version, enabled } }
+├── connector-configs.json             { "<id>": { config, installed_version, enabled, installed_source_id } }
+└── .enterprise-keys.json              encrypted list of registered enterprise keys
 ```
 
 Secret fields (`type: secret`) in `config` are encrypted at rest with

package/lib/help-docs/CLAUDE.md

@@ -79,6 +79,7 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 - Craft/custom tab/mini-app/extend project/AI-generated tab/builder → `15-crafts.md`
 - GitLab/glab/MR/merge request/issue auto-fix/epic → `16-gitlab-autofix.md`
 - Connector/connector marketplace/install connector/forge-connectors registry/Mantis manifest → `17-connectors.md`
+- Enterprise key / enterprise marketplace / `--enterprise-key=` / `🔒 fortinet` badge / "add fortinet key" / Marketplace Providers panel / `add_enterprise_key` / multi-source marketplace / hidden_sources / wizard template per company → `01-settings.md` § Marketplace Providers (+ `17-connectors.md` for the connector side, `00-overview.md` for install)
 - Build / author / write / create a new connector / "make me a connector for X" / custom connector → `21-build-connector.md`
 - Chrome MCP / chrome-devtools-mcp / dev-time browser / CDP / remote debugging → `18-chrome-mcp.md`
 - Job / scheduled job / connector poll / "Jobs tab" → tell user: **Jobs is deprecated**; use Schedules (`13-schedules.md`) instead.

package/lib/init.ts

@@ -285,13 +285,20 @@ export function restartTelegramBot() {
 
 let telegramChild: ReturnType<typeof spawn> | null = null;
 
+/** Instance tag every standalone spawn carries — lets /api/monitor filter
+ *  by the running web port so dev-test (port 4000) doesn't surface the
+ *  user's production Forge (port 8403) processes and vice versa. */
+function instanceTag(): string {
+  return `--forge-port=${process.env.PORT || 8403}`;
+}
+
 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], {
+  telegramChild = spawn('npx', ['tsx', script, instanceTag()], {
     stdio: ['ignore', 'inherit', 'inherit'],
     env: { ...process.env, PORT: String(process.env.PORT || 8403) },
     detached: false,
@@ -315,7 +322,7 @@ function startTerminalProcess() {
   tester.once('listening', () => {
     tester.close();
     const script = join(process.cwd(), 'lib', 'terminal-standalone.ts');
-    terminalChild = spawn('npx', ['tsx', script], {
+    terminalChild = spawn('npx', ['tsx', script, instanceTag()], {
       stdio: ['ignore', 'inherit', 'inherit'],
       env: { ...Object.fromEntries(Object.entries(process.env).filter(([k]) => k !== 'CLAUDECODE')) } as NodeJS.ProcessEnv,
       detached: false,
@@ -352,7 +359,7 @@ function startWorkspaceProcess() {
 
 function launchWorkspaceDaemon() {
   const script = join(process.cwd(), 'lib', 'workspace-standalone.ts');
-  workspaceChild = spawn('npx', ['tsx', script], {
+  workspaceChild = spawn('npx', ['tsx', script, instanceTag()], {
     stdio: ['ignore', 'inherit', 'inherit'],
     env: { ...process.env },
     detached: false,
@@ -376,7 +383,7 @@ function startChatProcess() {
   tester.once('listening', () => {
     tester.close();
     const script = join(process.cwd(), 'lib', 'chat-standalone.ts');
-    chatChild = spawn('npx', ['tsx', script], {
+    chatChild = spawn('npx', ['tsx', script, instanceTag()], {
       stdio: ['ignore', 'inherit', 'inherit'],
       env: { ...process.env },
       detached: false,
@@ -402,7 +409,7 @@ function startBrowserBridgeProcess() {
   tester.once('listening', () => {
     tester.close();
     const script = join(process.cwd(), 'lib', 'browser-bridge-standalone.ts');
-    bridgeChild = spawn('npx', ['tsx', script], {
+    bridgeChild = spawn('npx', ['tsx', script, instanceTag()], {
       stdio: ['ignore', 'inherit', 'inherit'],
       env: { ...process.env },
       detached: false,
@@ -419,7 +426,7 @@ function startMemoryProcess() {
   if (memoryChild) return;
   // No HTTP port — pure background poller. Just spawn-if-not-running.
   const script = join(process.cwd(), 'lib', 'memory-standalone.ts');
-  memoryChild = spawn('npx', ['tsx', script], {
+  memoryChild = spawn('npx', ['tsx', script, instanceTag()], {
     stdio: ['ignore', 'inherit', 'inherit'],
     env: { ...process.env },
     detached: false,

package/lib/marketplace-sync.ts

@@ -0,0 +1,70 @@
+/**
+ * Unified marketplace sync — one call refreshes everything from every
+ * configured source (public + each enterprise tenant):
+ *   - registry.json + wizard templates per source (lib/connectors/sync)
+ *   - installed connector manifests (so on-disk yaml updates)
+ *   - workflows: pipelines + recipes per source (lib/workflow-marketplace)
+ *   - skills: public only for now; enterprise skill sync is a separate task
+ *
+ * Errors per sub-step are isolated — a failing skills repo doesn't block
+ * connector sync, etc. Returned summary spells out each leg so the UI
+ * can show what actually landed.
+ */
+
+import { syncRegistry } from './connectors/sync';
+import { syncMarketplace as syncWorkflows } from './workflow-marketplace';
+import { syncSkills } from './skills';
+
+export interface MarketplaceSyncResult {
+  ok: boolean;
+  connectors: { ok: boolean; sources_ok?: number; sources_total?: number; manifests_refreshed?: number; error?: string };
+  workflows: { ok: boolean; recipes?: number; pipelines?: number; error?: string };
+  skills: { ok: boolean; synced?: number; error?: string };
+  fetched_at: string;
+}
+
+export async function syncAll(): Promise<MarketplaceSyncResult> {
+  const fetched_at = new Date().toISOString();
+
+  // 1. Connectors — registry + wizard templates per source + installed manifests
+  let connectors: MarketplaceSyncResult['connectors'];
+  try {
+    const r = await syncRegistry({ refreshInstalled: true });
+    connectors = {
+      ok: !!r.ok,
+      sources_ok: (r.sources || []).filter(s => s.ok).length,
+      sources_total: (r.sources || []).length,
+      manifests_refreshed: r.manifests_refreshed || 0,
+      error: r.error,
+    };
+  } catch (e) {
+    connectors = { ok: false, error: (e as Error).message };
+  }
+
+  // 2. Workflows — pipelines + recipes per source
+  let workflows: MarketplaceSyncResult['workflows'];
+  try {
+    const r = await syncWorkflows();
+    workflows = { ok: !!r.ok, recipes: r.recipes, pipelines: r.pipelines, error: r.error };
+  } catch (e) {
+    workflows = { ok: false, error: (e as Error).message };
+  }
+
+  // 3. Skills — public only for now (enterprise skill sources are a
+  // separate phase in the marketplace roadmap).
+  let skills: MarketplaceSyncResult['skills'];
+  try {
+    const r = await syncSkills();
+    skills = { ok: !r.error, synced: r.synced, error: r.error };
+  } catch (e) {
+    skills = { ok: false, error: (e as Error).message };
+  }
+
+  return {
+    ok: connectors.ok && workflows.ok && skills.ok,
+    connectors,
+    workflows,
+    skills,
+    fetched_at,
+  };
+}

package/lib/memory/temper-provision.ts

@@ -0,0 +1,92 @@
+/**
+ * Temper auto-provisioning — calls Temper's POST /v1/onboarding/provision
+ * with the super-admin token (baked into an enterprise wizard template as
+ * `_temperAdmin: { url, token }` and shipped encrypted via ent:) to create
+ * a per-user memory account on first onboarding.
+ *
+ * Org + group are get-or-create (idempotent on slug). User is non-idempotent
+ * — a 409 on re-run means the user already exists; treat that as a soft skip
+ * so re-running the wizard doesn't blow up.
+ */
+
+export interface ProvisionInput {
+  url: string;
+  adminToken: string;
+  username: string;
+  email: string;
+  company: string;
+  dept: string;
+  displayName?: string;
+}
+
+export interface ProvisionResult {
+  ok: true;
+  user_id: string;
+  username: string;
+  email: string;
+  display_name?: string;
+  org_slug: string;
+  group_slug: string;
+  api_key: string;
+  api_key_prefix?: string;
+  default_password?: string;
+  must_change_password?: boolean;
+  created?: { org?: boolean; group?: boolean; user?: boolean };
+}
+
+export interface ProvisionError {
+  ok: false;
+  status: number;
+  error: string;
+  /** True when 409 — user exists; caller may treat as soft-skip. */
+  conflict?: boolean;
+}
+
+export async function provisionTemperUser(input: ProvisionInput): Promise<ProvisionResult | ProvisionError> {
+  const baseUrl = input.url.replace(/\/+$/, '');
+  if (!baseUrl) return { ok: false, status: 0, error: 'temper url missing' };
+  if (!input.adminToken) return { ok: false, status: 0, error: 'temper admin token missing' };
+  if (!input.username || !input.email || !input.company || !input.dept) {
+    return { ok: false, status: 0, error: 'username/email/company/dept all required' };
+  }
+
+  const body = {
+    username: input.username,
+    email: input.email,
+    company: input.company,
+    dept: input.dept,
+    ...(input.displayName ? { display_name: input.displayName } : {}),
+  };
+
+  let res: Response;
+  try {
+    res = await fetch(`${baseUrl}/v1/onboarding/provision`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-API-Key': input.adminToken,
+      },
+      body: JSON.stringify(body),
+    });
+  } catch (e) {
+    return { ok: false, status: 0, error: `network: ${(e as Error).message}` };
+  }
+
+  let parsed: any = null;
+  const text = await res.text();
+  try { parsed = JSON.parse(text); } catch { parsed = { raw: text }; }
+
+  if (res.ok) {
+    if (!parsed?.api_key || !parsed?.user_id) {
+      return { ok: false, status: res.status, error: 'response missing api_key/user_id' };
+    }
+    return { ok: true, ...parsed };
+  }
+
+  return {
+    ok: false,
+    status: res.status,
+    error: parsed?.error || parsed?.message || `HTTP ${res.status}`,
+    conflict: res.status === 409,
+  };
+}

package/lib/pipeline-gc.ts

@@ -20,8 +20,8 @@
  */
 
 import { readdirSync, statSync, rmSync, existsSync } from 'node:fs';
+import { scanProjects, getProjectWorktreeRoot } from './projects';
 import { join } from 'node:path';
-import { scanProjects } from './projects';
 import { getPipeline } from './pipeline';
 import { loadSettings } from './settings';
 
@@ -45,7 +45,10 @@ export function gcPipelineTmp(opts: { dryRun?: boolean } = {}): GcResult {
   let scanned = 0;
 
   for (const proj of scanProjects()) {
-    const wtDir = join(proj.path, '.forge', 'worktrees');
+    // Scratch uses a flatter <dataDir>/scratch/worktrees/ layout — see
+    // getProjectWorktreeRoot for the rationale. Every other project sticks
+    // to the regular <project>/.forge/worktrees/ convention.
+    const wtDir = getProjectWorktreeRoot(proj);
     if (!existsSync(wtDir)) continue;
     let entries: string[];
     try { entries = readdirSync(wtDir); } catch { continue; }

package/lib/pipeline.ts

@@ -11,7 +11,7 @@ import { execSync } from 'node:child_process';
 import { join } from 'node:path';
 import YAML from 'yaml';
 import { createTask, getTask, onTaskEvent, taskModelOverrides, taskAppendSystemPromptOverrides, cancelTask } from './task-manager';
-import { getProjectInfo } from './projects';
+import { getProjectInfo, resolveOrCloneProject, getProjectWorktreeRoot } from './projects';
 import { loadSettings } from './settings';
 import { getAgent, listAgents } from './agents';
 import type { Task } from '../src/types';
@@ -755,9 +755,8 @@ function computePipelineTmpDir(pipeline: Pipeline): string {
   if (!name) return '';
   const proj = getProjectInfo(name);
   if (!proj) return '';
-  // `.forge/worktrees/` matches the existing convention used by the auto-
-  // worktree path (see line ~1450) and by older fortinet-* pipelines.
-  return join(proj.path, '.forge', 'worktrees', `pipeline-${pipeline.id}`);
+  // Worktree root differs for scratch vs real projects — see getProjectWorktreeRoot.
+  return join(getProjectWorktreeRoot(proj), `pipeline-${pipeline.id}`);
 }
 
 /**
@@ -1048,15 +1047,19 @@ function scheduleNextConversationTurn(pipeline: Pipeline, contextForAgent: strin
     return;
   }
 
-  // Resolve project
+  // Resolve project — three-tier fallback in lib/projects.ts:
+  //   1. existing project by name
+  //   2. auto-clone GitLab default_project_path → projectRoots[0] / ~/IdeaProjects
+  //   3. scratch (<dataDir>/scratch, always writable)
+  // Never fails. The scratch fallback means a pipeline that needs no real
+  // repo still runs (connector-only flows, talk-only agents); pipelines that
+  // truly need source files will fail later inside their own nodes with a
+  // domain-specific error, not a "Project not found".
   const projectName = agentDef.project || pipeline.input.project || '';
-  const projectInfo = getProjectInfo(projectName);
-  if (!projectInfo) {
-    pipeline.status = 'failed';
-    pipeline.completedAt = new Date().toISOString();
-    savePipeline(pipeline);
-    notifyPipelineComplete(pipeline);
-    return;
+  const resolved = resolveOrCloneProject(projectName);
+  const projectInfo = resolved.project;
+  if (resolved.source !== 'existing') {
+    console.log(`[pipeline ${pipeline.id.slice(0,8)}] project resolved via ${resolved.source}: ${projectInfo.path}`);
   }
 
   // Build the prompt: role context + conversation history + new message
@@ -1771,13 +1774,14 @@ async function scheduleReadyNodes(pipeline: Pipeline, workflow: Workflow) {
     const project = resolveTemplate(nodeDef.project, ctx);
     const prompt = resolveTemplate(nodeDef.prompt, ctx, isShell);
 
-    const projectInfo = getProjectInfo(project);
-    if (!projectInfo) {
-      nodeState.status = 'failed';
-      nodeState.error = `Project not found: ${project}`;
-      savePipeline(pipeline);
-      notifyStep(pipeline, nodeId, 'failed', nodeState.error);
-      continue;
+    // Three-tier project resolution (existing → gitlab clone → scratch).
+    // Never null. Worktrees land under projectInfo.path/.forge/worktrees/
+    // regardless of which tier resolved — scratch is Forge-owned and
+    // always writable, so even the worst case keeps the pipeline running.
+    const resolved = resolveOrCloneProject(project);
+    const projectInfo = resolved.project;
+    if (resolved.source !== 'existing') {
+      console.log(`[pipeline ${pipeline.id.slice(0,8)} node ${nodeId}] project '${project}' resolved via ${resolved.source}: ${projectInfo.path}`);
     }
 
     // All pipeline steps use worktree for isolated execution.
@@ -1791,8 +1795,9 @@ async function scheduleReadyNodes(pipeline: Pipeline, workflow: Workflow) {
     const useWorktree = nodeDef.worktree !== false && !nodeDef.workdir;
     const branchName = nodeDef.branch ? resolveTemplate(nodeDef.branch, ctx) : `pipeline/${pipeline.id.slice(0, 8)}`;
     if (useWorktree) try {
-      const worktreePath = `${projectInfo.path}/.forge/worktrees/${branchName.replace(/\//g, '-')}`;
-      mkdirSync(`${projectInfo.path}/.forge/worktrees`, { recursive: true });
+      const wtRoot = getProjectWorktreeRoot(projectInfo);
+      const worktreePath = `${wtRoot}/${branchName.replace(/\//g, '-')}`;
+      mkdirSync(wtRoot, { recursive: true });
 
       // Create branch if needed.
       // Silent catch: `git branch X` fails with "already exists" — the

package/lib/plugins/templates.ts

@@ -6,29 +6,94 @@
  * tool arguments ({args.*}) are left literal — the extension's runner expands
  * those at execution time.
  *
+ * `{connector:<id>.<field>}` cross-references another connector's runtime
+ * config — e.g. Jenkins inject_params can pull a GitLab PAT without baking
+ * it. Read at dispatch time, never persisted in the dependent connector's
+ * own config, so changing the GitLab token automatically reflects in
+ * Jenkins.
+ *
  * See docs/Connector-DeclarativeExtract-Spec.md §4.
  */
 
+import { getInstalledConnector } from '../connectors/registry';
+import { loadSettings } from '../settings';
+
 type SettingsMap = Record<string, any>;
 
+/**
+ * `{user.<field>}` resolves to the operator's global identity from
+ * settings.yaml. Replaces per-connector username fields so an org
+ * has one source of truth.
+ *
+ *   {user.name}   displayName → fallback: local-part of displayEmail → ''
+ *   {user.email}  displayEmail
+ *   {user.login}  email local-part (same as {user.name}'s fallback)
+ */
+function resolveUserRef(ref: string): string | null {
+  let s: { displayName?: string; displayEmail?: string };
+  try { s = loadSettings() as any; } catch { return null; }
+  const email = s.displayEmail || '';
+  const localPart = email.includes('@') ? email.split('@')[0] : email;
+  switch (ref) {
+    case 'name':
+      return (s.displayName && s.displayName.trim() && s.displayName.trim() !== 'Forge')
+        ? s.displayName.trim()
+        : localPart;
+    case 'email':
+      return email;
+    case 'login':
+      return localPart;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Look up `{connector:<id>.<field>}` by reading the target connector's
+ * runtime config from connector-configs.json. Secret fields are
+ * auto-decrypted by getInstalledConnector. Missing connector / field
+ * returns null so the caller leaves the token literal (matches the
+ * "unknown token → pass through" behaviour of the other resolvers).
+ */
+function resolveConnectorRef(ref: string): string | null {
+  const dot = ref.indexOf('.');
+  if (dot < 0) return null;
+  const id = ref.slice(0, dot).trim();
+  const field = ref.slice(dot + 1).trim();
+  if (!id || !field) return null;
+  const inst = getInstalledConnector(id);
+  if (!inst) return null;
+  const v = (inst.config as Record<string, unknown>)[field];
+  if (v == null) return null;
+  return typeof v === 'string' ? v : String(v);
+}
+
 /**
  * Expand {base_url} and {settings.<key>} tokens in a string. Other tokens
  * (including {args.*}) are passed through unchanged so the extension can
  * finish substitution at run time.
  */
 export function expandSettingsTokens(template: string, settings: SettingsMap | undefined): string {
-  if (!template || !settings) return template;
+  if (!template) return template;
   return template.replace(/\{([^{}]+)\}/g, (full, raw) => {
     const key = String(raw).trim();
     if (key === 'base_url') {
-      const v = settings.base_url;
+      const v = settings?.base_url;
       return typeof v === 'string' ? stripTrailingSlashes(v) : full;
     }
     if (key.startsWith('settings.')) {
       const path = key.slice('settings.'.length);
-      const v = settings[path];
+      const v = settings?.[path];
       return typeof v === 'string' ? stripTrailingSlashes(v) : full;
     }
+    if (key.startsWith('connector:')) {
+      const v = resolveConnectorRef(key.slice('connector:'.length));
+      return v == null ? full : v;
+    }
+    if (key.startsWith('user.')) {
+      const v = resolveUserRef(key.slice('user.'.length));
+      return v == null ? full : v;
+    }
     return full;
   });
 }
@@ -78,6 +143,14 @@ export function expandAllTokens(
       if (typeof v === 'number' || typeof v === 'boolean') return String(v);
       try { return JSON.stringify(v); } catch { return full; }
     }
+    if (key.startsWith('connector:')) {
+      const v = resolveConnectorRef(key.slice('connector:'.length));
+      return v == null ? full : v;
+    }
+    if (key.startsWith('user.')) {
+      const v = resolveUserRef(key.slice('user.'.length));
+      return v == null ? full : v;
+    }
     return full;
   });
 }

package/lib/projects.ts

@@ -1,5 +1,6 @@
 import { readdirSync, existsSync, statSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { homedir } from 'node:os';
 import { loadSettings } from './settings';
 import { getDataDir } from './dirs';
 
@@ -144,6 +145,90 @@ export function getProjectInfo(name: string): LocalProject | null {
   return projects.find(p => p.name === name) || null;
 }
 
+/**
+ * Resolve a project by name, with a best-effort fallback for the common
+ * "user hasn't added any projects yet" case:
+ *
+ *   1. If `name` matches a scanned project — return it. (Same as getProjectInfo.)
+ *   2. Else if the GitLab connector has `default_project_path` set, try to
+ *      clone it under `projectRoots[0]` (or ~/IdeaProjects if none set), add
+ *      that parent to projectRoots, and return the cloned project.
+ *   3. Else return null — callers fall back to their existing failure path
+ *      (which typically surfaces a clear "Project not found" error so the
+ *      user can fix it via Settings → Project roots).
+ *
+ * Designed to be additive: never throws, never overwrites existing projects,
+ * idempotent on re-entry (clone is skipped if the target dir already exists).
+ *
+ * Returns a `{ project, source }` so callers can log how the project was
+ * resolved without re-scanning.
+ */
+export interface ResolveResult {
+  project: LocalProject;
+  source: 'existing' | 'cloned' | 'scratch';
+  clone_url?: string;
+}
+
+/**
+ * Pick a writable directory to clone into, in priority order:
+ *   1. settings.projectRoots[0] — what the user already trusts
+ *   2. ~/IdeaProjects — common convention; mkdir on demand
+ *   3. <dataDir>/scratch — Forge-owned, always writable, last resort
+ *
+ * Each candidate is mkdir-tested before use so we never return a path the
+ * caller will fail to clone into.
+ */
+export function getDefaultCloneRoot(): string {
+  const s = loadSettings();
+  const candidates: string[] = [];
+  if (s.projectRoots.length > 0) candidates.push(s.projectRoots[0]);
+  candidates.push(join(homedir(), 'IdeaProjects'));
+  candidates.push(join(getDataDir(), 'scratch'));
+  for (const c of candidates) {
+    try { mkdirSync(c, { recursive: true }); return c; }
+    catch { /* try next */ }
+  }
+  // mkdir of <dataDir>/scratch should always work (we own it); reaching here
+  // means the dataDir itself is broken, which has bigger problems than this.
+  return join(getDataDir(), 'scratch');
+}
+
+export function resolveOrCloneProject(name: string | undefined): ResolveResult {
+  const trimmed = (name || '').trim();
+  if (trimmed) {
+    const hit = getProjectInfo(trimmed);
+    if (hit) return { project: hit, source: 'existing' };
+  }
+
+  // Default to scratch when the name doesn't match a real project root. The
+  // earlier behavior was to auto-clone from gitlab.default_project_path — but
+  // that ran a `git clone` in-band (slow, surprising, leaves dirs scattered
+  // under ~/IdeaProjects). Pipelines now always run inside Forge-managed
+  // `<dataDir>/scratch/worktrees/pipeline-<id>/` unless the user has
+  // explicitly added the named project under Settings → Project roots.
+  // Explicit clone is still available via `POST /api/projects/clone` for
+  // users who want it.
+  return { project: scratchProject(), source: 'scratch' };
+}
+
+/**
+ * Where pipeline worktrees go for a given project.
+ *
+ *   • Regular project (any `projectRoots` dir) → `<project>/.forge/worktrees/`
+ *     — the dot-prefixed `.forge/` keeps Forge's scratch out of the way of
+ *     the user's source tree.
+ *   • Scratch project (`<dataDir>/scratch/`) → `<dataDir>/scratch/worktrees/`
+ *     — scratch already lives under `.forge/data/`, so the inner `.forge/`
+ *     would just be a redundant nesting. Flatter path here.
+ *
+ * Used by pipeline.ts (worktree creation + `{{run.tmp_dir}}`) and
+ * pipeline-gc.ts (scan + cleanup).
+ */
+export function getProjectWorktreeRoot(project: LocalProject): string {
+  if (project.name === SCRATCH_PROJECT_NAME) return join(project.path, 'worktrees');
+  return join(project.path, '.forge', 'worktrees');
+}
+
 export function getProjectClaudeMd(projectPath: string): string | null {
   const claudeMdPath = join(projectPath, 'CLAUDE.md');
   if (!existsSync(claudeMdPath)) return null;

package/lib/settings.ts

@@ -135,6 +135,14 @@ export interface Settings {
   maxConcurrentPipelines: number;
   displayName: string;
   displayEmail: string;
+  /** User profile — company + dept. Auto-filled by the wizard when the
+   *  user picks an enterprise template (company = tenant display name,
+   *  dept = chosen department's display name). Editable in Settings →
+   *  Identity. Changing `dept` re-applies the matching dept template
+   *  to rotate dept-flavored connector defaults (default_project_path,
+   *  jenkins instance, etc.). */
+  company: string;
+  dept: string;
   favoriteProjects: string[];
   defaultAgent: string;
   telegramAgent: string;
@@ -228,6 +236,8 @@ const defaults: Settings = {
   maxConcurrentPipelines: 5,
   displayName: 'Forge',
   displayEmail: '',
+  company: '',
+  dept: '',
   favoriteProjects: [],
   defaultAgent: 'claude',
   telegramAgent: '',