@aion0/forge 0.9.19 → 0.10.2

package/RELEASE_NOTES.md

@@ -1,18 +1,8 @@
-# Forge v0.9.19
+# Forge v0.10.2
 
-Released: 2026-05-29
+Released: 2026-05-30
 
-## Changes since v0.9.18
+## Changes since v0.10.1
 
-### Other
-- feat(memory): writeEpisode dual-write + Memory drawer in /chat web
-- feat(monitor): D3 — Memory Worker row in Settings Monitor
-- feat(chat): Phase C — agent-loop reads summarized memory + token-budget history
-- feat(memory): B11 — spawn memory-standalone from forge-server + dev supervisor
-- fix(memory): bypass ai-sdk for summarizer LLM call — raw fetch instead
-- feat(memory): Phase B — memory-standalone process + Temper Summary sub-task
-- feat(memory): Phase A — key conventions + buildMemoryContext + OR-match search
-- fix(chat): cap LLM history at last 40 messages and drop orphan tool_results
 
-
-**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.9.18...v0.9.19
+**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.10.1...v0.10.2

package/app/api/agents/[id]/test/route.ts

@@ -35,7 +35,9 @@ interface TestResult {
 export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params;
   const settings = loadSettings();
-  const saved = (settings.agents || {})[id] as any | undefined;
+  // Post-migration API profiles live in settings.apiProfiles; fall back to
+  // settings.agents for the migration window or for legacy entries.
+  const saved = (settings.apiProfiles || {})[id] || (settings.agents || {})[id] as any | undefined;
 
   let override: any = {};
   try { override = (await req.json()) ?? {}; } catch { override = {}; }
@@ -53,7 +55,7 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
     apiKey:   unmask(override.apiKey, saved?.apiKey) ?? saved?.apiKey,
     baseUrl:  override.baseUrl  ?? saved?.baseUrl,
     model:    override.model    ?? saved?.model,
-    env:      saved?.env,
+    env:      (saved as any)?.env,   // legacy agent entries may have env; apiProfiles don't
   };
 
   if (!profile.provider) {

package/app/api/agents/route.ts

@@ -1,5 +1,6 @@
 import { NextResponse } from 'next/server';
 import { listAgents, getDefaultAgentId, resolveTerminalLaunch } from '@/lib/agents';
+import { loadSettings } from '@/lib/settings';
 
 export async function GET(req: Request) {
   const url = new URL(req.url);
@@ -16,12 +17,31 @@ export async function GET(req: Request) {
   // default hides them. WorkspaceView's API mode passes ?include=all
   // (or ?include=api) to surface them when needed.
   const include = (url.searchParams.get('include') || 'cli').toLowerCase();
-  const all = listAgents();
-  const agents = include === 'all'
-    ? all
-    : include === 'api'
-      ? all.filter((a: any) => a.backendType === 'api')
-      : all.filter((a: any) => a.backendType !== 'api');
+  const cliAgents = listAgents();
+  const apiAgents = include === 'cli' ? [] : apiProfilesAsAgents();
+  const agents = include === 'cli' ? cliAgents
+    : include === 'api' ? apiAgents
+    : [...cliAgents, ...apiAgents];
   const defaultAgent = getDefaultAgentId();
   return NextResponse.json({ agents, defaultAgent });
 }
+
+// Render settings.apiProfiles as agent-shaped entries so the workspace
+// API-mode picker can list them (Phase 2 moved them out of listAgents).
+function apiProfilesAsAgents() {
+  const profiles = loadSettings().apiProfiles || {};
+  return Object.entries(profiles)
+    .filter(([, p]: [string, any]) => p && p.enabled !== false)
+    .map(([id, p]: [string, any]) => ({
+      id,
+      name: p.name || id,
+      path: '',
+      enabled: true,
+      type: 'generic' as const,
+      capabilities: { supportsResume: false, supportsStreamJson: false, supportsModel: false, supportsSkipPermissions: false, hasSessionFiles: false, requiresTTY: false },
+      isProfile: true,
+      backendType: 'api' as const,
+      provider: p.provider,
+      model: p.model,
+    }));
+}

package/app/api/schedules/extract/route.ts

@@ -100,19 +100,21 @@ export async function POST(req: Request) {
   if (!text) return NextResponse.json({ ok: false, error: 'text required' }, { status: 400 });
 
   const settings = loadSettings();
-  const agents = settings.agents || {};
-  const candidates = Object.entries(agents).filter(([_, a]) => {
-    if (!a || a.type !== 'api' || a.enabled === false) return false;
-    return pickApiKey(a, inferAdapter(a.provider)).length > 0;
+  const profiles = settings.apiProfiles || {};
+  const candidates = Object.entries(profiles).filter(([_, p]: [string, any]) => {
+    if (!p || p.enabled === false) return false;
+    return (p.apiKey || '').length > 0;
   });
   if (candidates.length === 0) {
     return NextResponse.json({
       ok: false,
-      error: 'No API agent profile with an API key. Add one under Settings → Agents (type: API).',
+      error: 'No API profile with an API key. Add one under Settings → API Profiles.',
     }, { status: 400 });
   }
   const preferredId = settings.chatAgent || candidates[0]![0];
-  const profile = agents[preferredId]?.type === 'api' ? agents[preferredId] : candidates[0]![1];
+  const profile: any = profiles[preferredId] && profiles[preferredId].enabled !== false
+    ? profiles[preferredId]
+    : candidates[0]![1];
   const adapter = inferAdapter(profile.provider);
   if (adapter !== 'anthropic') {
     return NextResponse.json({

package/components/SettingsModal.tsx

@@ -882,14 +882,16 @@ interface AgentEntry {
   backendType?: string;
 }
 
-function ProfileRow({ id, cfg, inputClass, onUpdate, onDelete }: {
+function ProfileRow({ id, cfg, inputClass, onUpdate, onDelete, isApi: isApiProp }: {
   id: string; cfg: any; inputClass: string;
   onUpdate: (cfg: any) => void; onDelete: () => void;
+  isApi?: boolean;
 }) {
   const [expanded, setExpanded] = useState(false);
   const [testing, setTesting] = useState(false);
   const [testResult, setTestResult] = useState<{ ok: boolean; message?: string; error?: string; duration_ms?: number } | null>(null);
-  const isApi = cfg.type === 'api';
+  // Post-migration apiProfile entries no longer carry `type: 'api'`. Caller passes isApi explicitly.
+  const isApi = isApiProp ?? (cfg.type === 'api');
 
   async function runTest() {
     setTesting(true);
@@ -1379,16 +1381,16 @@ function AgentsSection({ settings, setSettings }: { settings: any; setSettings:
       const agentsCfg: Record<string, any> = { ...(prev.agents || {}) };
       for (const a of updated) {
         const existing = agentsCfg[a.id] || {};
-        // NOTE: do NOT write `cliType` from the entry here. cliType is the
-        // load-time discriminator between agents and CLI profiles (see the
-        // filter ~line 1349 — `if (cfg.cliType || cfg.base) continue`).
-        // The Agents-add form seeds newAgent.cliType for cliDefaults lookup
-        // (taskFlags / resumeFlag presets), but persisting it would make
-        // the new agent show up as a profile on reload. `...existing`
-        // carries forward cliType for detected agents whose inline selector
-        // wrote it via setSettings directly (line ~1540).
+        // Persist `tool` (which CLI binary to wrap) — listAgents reads this
+        // post-migration to clone the matching builtin's adapter. cliType in
+        // the AgentEntry is the form's selector value; map it to tool.
+        const cliType = (a as any).cliType || existing.cliType;
+        const tool = existing.tool
+          || (cliType === 'claude-code' ? 'claude' : cliType === 'codex' ? 'codex' : cliType === 'aider' ? 'aider' : undefined)
+          || (['claude', 'codex', 'aider', 'opencode'].includes(a.id) ? a.id : undefined);
         agentsCfg[a.id] = {
-          ...existing, // preserve profile-specific fields + any prior cliType
+          ...existing,
+          ...(tool ? { tool } : {}),
           name: a.name,
           path: a.path,
           enabled: a.enabled,
@@ -1447,10 +1449,9 @@ function AgentsSection({ settings, setSettings }: { settings: any; setSettings:
     // settings.agents is one map keyed by id — agents + CLI profiles + API
     // profiles all coexist. A duplicate id silently overwrites whichever
     // entry was there first. Block the add and tell the user why.
-    if (agents.some(a => a.id === newAgent.id) || settings.agents?.[newAgent.id]) {
-      const existing = settings.agents?.[newAgent.id] as any;
-      const kind = existing?.type === 'api' ? 'API profile' : existing?.cliType || existing?.base ? 'CLI profile' : 'agent';
-      alert(`id "${newAgent.id}" is already in use by a ${kind}. Pick a different id.`);
+    if (agents.some(a => a.id === newAgent.id) || settings.agents?.[newAgent.id] || (settings as any).apiProfiles?.[newAgent.id]) {
+      const kind = (settings as any).apiProfiles?.[newAgent.id] ? 'API profile' : 'agent';
+      alert(`id "${newAgent.id}" is already in use by an ${kind}. Pick a different id.`);
       return;
     }
     const entry: AgentEntry = {
@@ -1552,8 +1553,12 @@ function AgentsSection({ settings, setSettings }: { settings: any; setSettings:
                     </div>
                     <div className="w-36">
                       <label className="text-[9px] text-[var(--text-secondary)]">CLI Type</label>
-                      <select value={(settings.agents?.[a.id] as any)?.cliType || (a.id === 'claude' ? 'claude-code' : a.id === 'codex' ? 'codex' : a.id === 'aider' ? 'aider' : 'generic')}
-                        onChange={e => setSettings({ ...settings, agents: { ...settings.agents, [a.id]: { ...(settings.agents?.[a.id] || {}), cliType: e.target.value } } })}
+                      <select value={(settings.agents?.[a.id] as any)?.tool || (settings.agents?.[a.id] as any)?.cliType || (a.id === 'claude' ? 'claude-code' : a.id === 'codex' ? 'codex' : a.id === 'aider' ? 'aider' : 'generic')}
+                        onChange={e => {
+                          const v = e.target.value;
+                          const tool = v === 'claude-code' ? 'claude' : v === 'generic' ? undefined : v;
+                          setSettings({ ...settings, agents: { ...settings.agents, [a.id]: { ...(settings.agents?.[a.id] || {}), ...(tool ? { tool } : {}), cliType: v } } });
+                        }}
                         className={inputClass}>
                         <option value="claude-code">Claude Code</option>
                         <option value="codex">Codex</option>
@@ -1647,24 +1652,58 @@ function AgentsSection({ settings, setSettings }: { settings: any; setSettings:
                     Requires terminal environment (TTY)
                     <span className="text-[8px]">— enable for agents that need a terminal to run (e.g. Codex)</span>
                   </label>
+
+                  {/* Env vars — was the CLI Profile feature, now lives on the agent itself */}
+                  {(() => {
+                    const envObj: Record<string, string> = ((settings.agents?.[a.id] as any)?.env) || {};
+                    const envStr = Object.entries(envObj).map(([k, v]) => `${k}=${v}`).join('\n');
+                    const tool = (settings.agents?.[a.id] as any)?.tool || (settings.agents?.[a.id] as any)?.cliType;
+                    const TEMPLATES: Record<string, string> = {
+                      claude: 'ANTHROPIC_AUTH_TOKEN=\nANTHROPIC_BASE_URL=\nANTHROPIC_SMALL_FAST_MODEL=\nCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=true\nDISABLE_TELEMETRY=true\nDISABLE_ERROR_REPORTING=true\nDISABLE_AUTOUPDATER=true\nDISABLE_NON_ESSENTIAL_MODEL_CALLS=true',
+                      'claude-code': 'ANTHROPIC_AUTH_TOKEN=\nANTHROPIC_BASE_URL=\nANTHROPIC_SMALL_FAST_MODEL=\nCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=true\nDISABLE_TELEMETRY=true\nDISABLE_ERROR_REPORTING=true\nDISABLE_AUTOUPDATER=true\nDISABLE_NON_ESSENTIAL_MODEL_CALLS=true',
+                      codex: 'OPENAI_API_KEY=\nOPENAI_BASE_URL=',
+                      aider: 'ANTHROPIC_API_KEY=\nOPENAI_API_KEY=',
+                    };
+                    const tpl = tool ? TEMPLATES[tool] : '';
+                    return (
+                      <div>
+                        <div className="flex items-center gap-2">
+                          <label className="text-[9px] text-[var(--text-secondary)]">Environment Variables <span className="text-[8px]">(KEY=VALUE per line, applied to this agent's spawned process)</span></label>
+                          {tpl && (
+                            <button onClick={() => {
+                              const merged: Record<string, string> = {};
+                              for (const line of tpl.split('\n')) {
+                                const eq = line.indexOf('=');
+                                if (eq > 0) merged[line.slice(0, eq).trim()] = line.slice(eq + 1).trim();
+                              }
+                              Object.assign(merged, envObj);   // existing values win
+                              setSettings({ ...settings, agents: { ...settings.agents, [a.id]: { ...(settings.agents?.[a.id] || {}), env: merged } } });
+                            }} className="text-[8px] px-1.5 py-0.5 rounded bg-[var(--accent)]/10 text-[var(--accent)] hover:bg-[var(--accent)]/20">
+                              Fill {tool} template
+                            </button>
+                          )}
+                        </div>
+                        <textarea
+                          value={envStr}
+                          onChange={e => {
+                            const next: Record<string, string> = {};
+                            for (const line of e.target.value.split('\n')) {
+                              const eq = line.indexOf('=');
+                              if (eq > 0) next[line.slice(0, eq).trim()] = line.slice(eq + 1).trim();
+                            }
+                            setSettings({ ...settings, agents: { ...settings.agents, [a.id]: { ...(settings.agents?.[a.id] || {}), env: Object.keys(next).length > 0 ? next : undefined } } });
+                          }}
+                          rows={4}
+                          placeholder="ANTHROPIC_AUTH_TOKEN=sk-...&#10;ANTHROPIC_BASE_URL=https://..."
+                          className={inputClass + ' resize-none font-mono'}
+                        />
+                      </div>
+                    );
+                  })()}
+
                   {a.id !== 'claude' && (
                     <button onClick={() => removeAgent(a.id)} className="text-[9px] text-red-400 hover:underline">Remove Agent</button>
                   )}
-
-                  {/* Profile selector */}
-                  <div>
-                    <label className="text-[9px] text-[var(--text-secondary)]">Profile <span className="text-[8px]">— select to override model, env vars, API endpoint</span></label>
-                    <select
-                      value={(settings.agents?.[a.id] as any)?.profile || ''}
-                      onChange={e => setSettings({ ...settings, agents: { ...settings.agents, [a.id]: { ...(settings.agents?.[a.id] || {}), profile: e.target.value || undefined } } })}
-                      className={inputClass}
-                    >
-                      <option value="">Default (no profile)</option>
-                      {Object.entries(settings.agents || {}).filter(([, cfg]: [string, any]) => cfg.cliType || cfg.base || cfg.type === 'profile' || cfg.type === 'api').map(([pid, cfg]: [string, any]) => (
-                        <option key={pid} value={pid}>{cfg.name || pid}{cfg.model ? ` (${cfg.model})` : ''}</option>
-                      ))}
-                    </select>
-                  </div>
                 </div>
               )}
             </div>
@@ -1738,54 +1777,34 @@ function AgentsSection({ settings, setSettings }: { settings: any; setSettings:
         </div>
       )}
 
-      {/* ── Profiles Section ── */}
+      {/* ── API Profiles Section ── */}
       <div className="mt-4 pt-3 border-t border-[var(--border)]">
         <div className="flex items-center gap-2 mb-2">
-          <label className="text-xs text-[var(--text-secondary)] font-semibold uppercase">Profiles</label>
-          <span className="text-[8px] text-[var(--text-secondary)]">Shared across workspace and terminal — override model, env vars, API endpoint</span>
+          <label className="text-xs text-[var(--text-secondary)] font-semibold uppercase">API Profiles</label>
+          <span className="text-[8px] text-[var(--text-secondary)]">HTTP endpoints used by chat / web / Telegram (separate from CLI agents above)</span>
         </div>
 
-        {/* All profiles (CLI + API). CLI profile marker is `cliType`
-            (new) or `base` (legacy); API profile is `type: 'api'`. */}
-        {Object.entries(settings.agents || {}).filter(([, cfg]: [string, any]) => cfg.cliType || cfg.base || cfg.type === 'api').map(([id, cfg]: [string, any]) => (
-          <ProfileRow key={id} id={id} cfg={cfg} inputClass={inputClass}
-            onUpdate={(updated) => setSettings({ ...settings, agents: { ...settings.agents, [id]: updated } })}
+        {Object.entries((settings as any).apiProfiles || {}).map(([id, cfg]: [string, any]) => (
+          <ProfileRow key={id} id={id} cfg={cfg} inputClass={inputClass} isApi
+            onUpdate={(updated) => setSettings({ ...settings, apiProfiles: { ...((settings as any).apiProfiles || {}), [id]: updated } })}
             onDelete={() => {
-              const updated = { ...settings.agents };
+              const updated = { ...((settings as any).apiProfiles || {}) };
               delete updated[id];
-              setSettings({ ...settings, agents: updated });
+              setSettings({ ...settings, apiProfiles: updated });
             }}
           />
         ))}
 
         <div className="flex gap-2 mt-1">
-          {/* Functional setSettings — non-functional form captures a stale
-              `settings` snapshot, which clobbers any agent that was saved
-              between this component's last render and the Add click
-              (debouncedSave for the Agents section fires 1s later, so the
-              window is real). Also: settings.agents is a single map keyed
-              by id — agents + CLI profiles + API profiles share it — so
-              reusing an id silently overwrites. Block dups with an alert. */}
-          <AddProfileForm type="cli" baseAgents={agents.filter(a => !a.isProfile && a.detected)} onAdd={(id, cfg) => {
-            setSettings((prev: any) => {
-              if (prev.agents?.[id]) {
-                const existing = prev.agents[id] as any;
-                const kind = existing.type === 'api' ? 'API profile' : existing.cliType || existing.base ? 'CLI profile' : 'agent';
-                alert(`id "${id}" is already in use by a ${kind}. Pick a different id.`);
-                return prev;
-              }
-              return { ...prev, agents: { ...(prev.agents || {}), [id]: cfg } };
-            });
-          }} />
+          {/* Functional setSettings — captures stale snapshot otherwise (debouncedSave window is real). */}
           <AddProfileForm type="api" baseAgents={[]} onAdd={(id, cfg) => {
             setSettings((prev: any) => {
-              if (prev.agents?.[id]) {
-                const existing = prev.agents[id] as any;
-                const kind = existing.type === 'api' ? 'API profile' : existing.cliType || existing.base ? 'CLI profile' : 'agent';
-                alert(`id "${id}" is already in use by a ${kind}. Pick a different id.`);
+              if ((prev.apiProfiles || {})[id]) {
+                alert(`API profile id "${id}" already exists. Pick a different id.`);
                 return prev;
               }
-              return { ...prev, agents: { ...(prev.agents || {}), [id]: cfg } };
+              const { type, ...rest } = cfg;   // drop legacy type:'api' field; not in new shape
+              return { ...prev, apiProfiles: { ...(prev.apiProfiles || {}), [id]: { ...rest, enabled: true } } };
             });
           }} />
         </div>
@@ -1953,8 +1972,8 @@ function TemperSection({ settings, setSettings, secretStatus, setEditingSecret }
 // Telegram /chat) picks the API profile listed here. The user can override
 // per-session by setting Session.provider to a profile id.
 function ChatAgentSelect({ settings, setSettings }: { settings: any; setSettings: (s: any) => void }) {
-  const apiProfiles = Object.entries(settings.agents || {})
-    .filter(([, a]: [string, any]) => a && a.type === 'api' && a.enabled !== false);
+  const apiProfiles = Object.entries((settings as any).apiProfiles || {})
+    .filter(([, a]: [string, any]) => a && a.enabled !== false);
 
   return (
     <div className="mt-4 pt-3 border-t border-[var(--border)]">
@@ -1974,7 +1993,7 @@ function ChatAgentSelect({ settings, setSettings }: { settings: any; setSettings
       </div>
       {apiProfiles.length === 0 ? (
         <div className="text-[9px] text-[var(--text-secondary)] mt-1.5">
-          No API profile yet. Add one in the Profiles section above (type: API). LiteLLM proxies are supported via the Base URL field.
+          No API profile yet. Add one in the API Profiles section above. LiteLLM proxies are supported via the Base URL field.
         </div>
       ) : (
         <div className="text-[9px] text-[var(--text-secondary)] mt-1.5">

package/lib/agents/claude-adapter.ts

@@ -72,7 +72,12 @@ export function createClaudeAdapter(config: AgentConfig): AgentAdapter {
 
       args.push(opts.prompt);
 
-      return { cmd: resolved.cmd, args };
+      // Forward agent-level env (e.g. ANTHROPIC_AUTH_TOKEN/BASE_URL on a
+      // user-named CLI agent that wraps claude). task-manager merges this
+      // into the child env, letting one agent point claude at a custom
+      // endpoint without touching the user's global ~/.claude config.
+      const env = (config as any).env as Record<string, string> | undefined;
+      return { cmd: resolved.cmd, args, ...(env && Object.keys(env).length ? { env } : {}) };
     },
 
     buildTerminalCommand(opts) {

package/lib/agents/generic-adapter.ts

@@ -31,7 +31,8 @@ export function createGenericAdapter(config: AgentConfig): AgentAdapter {
         args.push(...opts.extraFlags);
       }
 
-      return { cmd: config.path, args };
+      const env = (config as any).env as Record<string, string> | undefined;
+      return { cmd: config.path, args, ...(env && Object.keys(env).length ? { env } : {}) };
     },
 
     buildTerminalCommand(opts) {

package/lib/agents/index.ts

@@ -73,35 +73,39 @@ export function listAgents(): AgentConfig[] {
     agents.push({ ...aider, enabled: aiderConfig?.enabled !== false, detected: true, skipPermissionsFlag: aiderConfig?.skipPermissionsFlag || '--yes', cliType: 'aider' } as any);
   }
 
-  // Custom agents + profiles from settings
+  // User-named CLI agents from settings (post-migration shape: tool field)
   if (settings.agents) {
     for (const [id, cfg] of Object.entries(settings.agents)) {
-      if (['claude', 'codex', 'aider'].includes(id)) continue;
-
-      // API profile — no CLI detection needed. Tagged with
-      // backendType='api' so CLI-only dropdowns (Terminal launcher,
-      // NewTaskModal etc.) can filter them out via
-      // `agents.filter(a => a.backendType !== 'api')`. WorkspaceView's
-      // API mode keeps them visible. Chat backend doesn't go through
-      // this path at all — it reads settings.agents directly.
-      if (cfg.type === 'api') {
+      if (['claude', 'codex', 'aider'].includes(id)) continue;  // builtins handled above
+
+      // Post-migration: tool field identifies which CLI to wrap.
+      // Find the matching builtin we already detected and clone its
+      // adapter shape, overriding model / env / etc. from this entry.
+      if (cfg.tool) {
+        const baseAgent = agents.find(a => a.id === cfg.tool);
         agents.push({
+          ...(baseAgent || { type: 'generic' as const, capabilities: { supportsResume: false, supportsStreamJson: false, supportsModel: false, supportsSkipPermissions: false, hasSessionFiles: false, requiresTTY: false } }),
           id,
           name: cfg.name || id,
-          path: '',
+          path: baseAgent?.path || '',
           enabled: cfg.enabled !== false,
-          type: 'generic' as const,
-          capabilities: { supportsResume: false, supportsStreamJson: false, supportsModel: false, supportsSkipPermissions: false, hasSessionFiles: false, requiresTTY: false },
           isProfile: true,
-          backendType: 'api',
-          provider: cfg.provider,
-          model: cfg.model,
-          apiKey: cfg.apiKey,
+          backendType: 'cli',
+          model: cfg.model || cfg.models?.task,
+          skipPermissionsFlag: cfg.skipPermissionsFlag || baseAgent?.skipPermissionsFlag,
+          env: cfg.env,
+          cliType: (baseAgent as any)?.cliType || 'generic',
         } as any);
         continue;
       }
 
-      // CLI profile (has base) — inherit from base agent
+      // === Legacy fallback (pre-migration / un-migrated) ===
+      // type: 'api' — already moved to settings.apiProfiles by migration,
+      // but keep this branch for the migration window in case someone hits
+      // it before migrateAgentsFlatten runs. After 1-2 versions, remove.
+      if (cfg.type === 'api') continue;   // silently skip — apiProfiles is canonical now
+
+      // CLI profile via base (legacy) — same path as tool branch above
       if (cfg.base) {
         const baseAgent = agents.find(a => a.id === cfg.base);
         agents.push({
@@ -121,7 +125,7 @@ export function listAgents(): AgentConfig[] {
         continue;
       }
 
-      // Custom agent (not a profile) — detect binary
+      // Custom agent — explicit path
       if (!cfg.path) continue;
       const flags = cfg.taskFlags ? cfg.taskFlags.split(/\s+/).filter(Boolean) : cfg.flags;
       const detected = detectAgent(id, cfg.name || id, cfg.path, flags);

package/lib/agents/migrate.ts

@@ -0,0 +1,159 @@
+/**
+ * One-time migration: agents flat dict → agents (CLI) + apiProfiles (API).
+ *
+ * Pre-v0.9.20 `settings.agents` held both CLI agent configs (claude /
+ * codex / aider / user-named "CLI profiles" with `base:`) AND HTTP API
+ * profiles (`type: 'api'`). Two distinct concepts crammed into one
+ * dict with field overlap → the new-install pipeline-uses-API-model
+ * bug (see todo_pipeline_model_resolution memory).
+ *
+ * Migration walks settings.agents once on startup:
+ *   - `type: 'api'` entries → moved to settings.apiProfiles
+ *   - CLI entries: best-effort flatten `base` / `cliType` → `tool`
+ *     (if neither can be inferred, entry stays put; UI will skip it
+ *     and the user re-adds manually)
+ *   - defaultAgent / chatAgent get validated against the new dicts and
+ *     downgraded to safe defaults if they point to the wrong kind
+ *
+ * Before writing anything we drop a backup at
+ * `<dataDir>/settings.backup.agents-<ts>.yaml` containing just the
+ * agent-related slices of settings.yaml, so a botched migration can be
+ * rolled back by hand.
+ *
+ * Idempotent: once the deprecated fields are gone, the next call is a
+ * no-op (returns false, no save).
+ */
+
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import YAML from 'yaml';
+import { getDataDir } from '../dirs';
+import type { Settings } from '../settings';
+
+const BUILTIN_TOOLS = new Set(['claude', 'codex', 'aider', 'opencode']);
+
+/** Returns true if anything was mutated (caller should save). */
+export function migrateAgentsFlatten(settings: Settings): boolean {
+  const needsMigration = detectsLegacyShape(settings);
+  if (!needsMigration) return false;
+
+  writeBackup(settings);
+
+  let mutated = false;
+  (settings as any).apiProfiles ??= {};
+
+  for (const [id, raw] of Object.entries(settings.agents ?? {}) as [string, any][]) {
+    // === 必须 — type='api' 搬到 apiProfiles ===
+    if (raw.type === 'api') {
+      (settings as any).apiProfiles[id] = {
+        name: raw.name ?? id,
+        enabled: raw.enabled !== false,
+        provider: mapProvider(raw.provider),
+        model: raw.model ?? '',
+        apiKey: raw.apiKey ?? '',
+        baseUrl: raw.baseUrl ?? '',
+      };
+      delete settings.agents[id];
+      mutated = true;
+      continue;
+    }
+
+    // === Best-effort — 推断 tool 字段 ===
+    if (!raw.tool) {
+      if (raw.base && BUILTIN_TOOLS.has(raw.base)) raw.tool = raw.base;
+      else if (raw.cliType === 'claude-code') raw.tool = 'claude';
+      else if (raw.cliType && BUILTIN_TOOLS.has(raw.cliType)) raw.tool = raw.cliType;
+      else if (BUILTIN_TOOLS.has(id)) raw.tool = id;
+      if (raw.tool) mutated = true;
+      // 推断不出 → 留原样,listAgents 会跳过,用户接受手动重加
+    }
+
+    // 清掉已过期的字段(只有迁移产生过 tool 才删 base/cliType,避免无 tool 的孤儿丢标识)
+    if (raw.tool) {
+      if (raw.base !== undefined) { delete raw.base; mutated = true; }
+      if (raw.cliType !== undefined) { delete raw.cliType; mutated = true; }
+    }
+    if (raw.type !== undefined) { delete raw.type; mutated = true; }
+
+    // 老嵌套 models.task → 扁平 model(如果 model 字段空)
+    if (!raw.model && raw.models?.task && raw.models.task !== 'default') {
+      raw.model = raw.models.task;
+      mutated = true;
+    }
+  }
+
+  // === 兜底校验 defaultAgent / chatAgent ===
+  if (settings.defaultAgent && !settings.agents?.[settings.defaultAgent]) {
+    const wasApi = (settings as any).apiProfiles[settings.defaultAgent];
+    console.warn(
+      `[migrate-agents] defaultAgent="${settings.defaultAgent}" ` +
+      (wasApi ? 'is an API profile, not allowed for tasks. ' : 'not found. ') +
+      `Falling back to 'claude'.`
+    );
+    settings.defaultAgent = 'claude';
+    mutated = true;
+  }
+  if (settings.chatAgent && !(settings as any).apiProfiles[settings.chatAgent]) {
+    const wasCli = settings.agents?.[settings.chatAgent];
+    console.warn(
+      `[migrate-agents] chatAgent="${settings.chatAgent}" ` +
+      (wasCli ? 'is a CLI agent, not allowed for chat. ' : 'not found. ') +
+      `Falling back.`
+    );
+    const firstApi = Object.entries((settings as any).apiProfiles)
+      .find(([, p]: any) => p.enabled)?.[0];
+    settings.chatAgent = firstApi ?? '';
+    mutated = true;
+  }
+
+  if (mutated) {
+    console.log('[migrate-agents] migrated settings.agents → agents + apiProfiles');
+  }
+  return mutated;
+}
+
+function detectsLegacyShape(settings: Settings): boolean {
+  for (const cfg of Object.values(settings.agents ?? {}) as any[]) {
+    if (cfg.type === 'api') return true;
+    if (cfg.base !== undefined) return true;
+    if (cfg.cliType !== undefined) return true;
+    // 没有 tool + 是 builtin id → 也算需要迁移(补 tool 字段)
+  }
+  // 内置 agent 没有 tool 字段也需要补
+  for (const [id, cfg] of Object.entries(settings.agents ?? {}) as [string, any][]) {
+    if (!cfg.tool && BUILTIN_TOOLS.has(id)) return true;
+  }
+  // defaultAgent 指向不存在的 entry 也需要兜底
+  if (settings.defaultAgent && !settings.agents?.[settings.defaultAgent]) {
+    return true;
+  }
+  return false;
+}
+
+function writeBackup(settings: Settings): void {
+  try {
+    const ts = Date.now();
+    const backupPath = join(getDataDir(), `settings.backup.agents-${ts}.yaml`);
+    const slice = {
+      _backup_note: 'Pre-migration snapshot of agent-related settings. Safe to delete after verifying migration worked.',
+      _backup_ts: new Date(ts).toISOString(),
+      agents: settings.agents,
+      defaultAgent: settings.defaultAgent,
+      chatAgent: settings.chatAgent,
+      telegramAgent: settings.telegramAgent,
+      docsAgent: settings.docsAgent,
+      telegramModel: settings.telegramModel,
+      taskModel: settings.taskModel,
+      pipelineModel: settings.pipelineModel,
+    };
+    writeFileSync(backupPath, YAML.stringify(slice), 'utf-8');
+    console.log(`[migrate-agents] backup → ${backupPath}`);
+  } catch (err) {
+    console.warn('[migrate-agents] backup write failed (continuing anyway):', err instanceof Error ? err.message : err);
+  }
+}
+
+function mapProvider(p?: string): 'anthropic' | 'openai-compatible' {
+  if (!p) return 'openai-compatible';
+  return /anthropic/i.test(p) ? 'anthropic' : 'openai-compatible';
+}

package/lib/chat/agent-loop.ts

@@ -151,36 +151,34 @@ export function pickApiKey(profile: { apiKey?: string; env?: Record<string, stri
 
 export function resolveProvider(sessionProvider: string | null, sessionModel: string | null): ProviderResolution | { error: string } {
   const settings = loadSettings();
-  const agents = settings.agents || {};
+  const profiles = settings.apiProfiles || {};
 
-  // Candidate API profiles: type=='api', enabled, with a usable apiKey (direct or via env).
-  const candidates = Object.entries(agents).filter(([_, a]) => {
-    if (!a || a.type !== 'api' || a.enabled === false) return false;
-    const adapter = inferAdapter(a.provider);
-    return pickApiKey(a, adapter).length > 0;
+  // Candidate API profiles: enabled + has apiKey.
+  const candidates = Object.entries(profiles).filter(([_, p]) => {
+    if (!p || p.enabled === false) return false;
+    return (p.apiKey || '').length > 0;
   });
   if (candidates.length === 0) {
-    return { error: 'No API agent profile with an API key. Add one under Settings → Agents (type: API) and pick it as the chat agent.' };
+    return { error: 'No API profile with an API key. Add one under Settings → API Profiles and pick it as the chat profile.' };
   }
 
-  // Preferred: session.provider (an agent profile id), then settings.chatAgent, else first candidate.
+  // Preferred: session.provider (an apiProfile id), then settings.chatAgent, else first candidate.
   const preferredId = sessionProvider || settings.chatAgent || candidates[0]![0];
-  const profile = agents[preferredId] && agents[preferredId].type === 'api'
-    ? agents[preferredId]
+  const profile = profiles[preferredId] && profiles[preferredId].enabled !== false
+    ? profiles[preferredId]
     : candidates[0]![1];
-  const name = agents[preferredId]?.type === 'api' ? preferredId : candidates[0]![0];
+  const name = (profiles[preferredId] && profiles[preferredId].enabled !== false) ? preferredId : candidates[0]![0];
 
-  const adapter = inferAdapter(profile.provider);
-  const apiKey = pickApiKey(profile, adapter);
-  if (!apiKey) return { error: `Agent profile "${name}" has no apiKey (direct or via env).` };
+  const adapter: 'anthropic' | 'openai' = profile.provider === 'anthropic' ? 'anthropic' : 'openai';
+  if (!profile.apiKey) return { error: `API profile "${name}" has no apiKey.` };
 
   const model = sessionModel || profile.model || (adapter === 'anthropic' ? 'claude-sonnet-4-6' : 'gpt-4o-mini');
 
   return {
     name,
     type: adapter,
-    apiKey,
-    baseUrl: pickBaseUrl(profile, adapter),
+    apiKey: profile.apiKey,
+    baseUrl: profile.baseUrl || defaultBaseUrl(profile.provider),
     model,
   };
 }

package/lib/init.ts

@@ -94,6 +94,15 @@ export function ensureInitialized() {
     catch (e) { console.warn('[init] ensureScratchProject failed:', (e as Error).message); }
   });
   time('migrateSecrets', migrateSecrets);
+  time('migrateAgentsFlatten', () => {
+    try {
+      const { migrateAgentsFlatten } = require('./agents/migrate');
+      const settings = loadSettings();
+      if (migrateAgentsFlatten(settings)) {
+        saveSettings(settings);
+      }
+    } catch (e) { console.warn('[init] migrateAgentsFlatten failed:', (e as Error).message); }
+  });
   time('migratePluginSecrets', () => {
     try {
       const { migratePluginSecrets } = require('./plugins/registry');

package/lib/settings.ts

@@ -7,29 +7,62 @@ import { getDataDir } from './dirs';
 const DATA_DIR = getDataDir();
 const SETTINGS_FILE = join(DATA_DIR, 'settings.yaml');
 
+/**
+ * AgentEntry — a CLI agent configuration (one CLI binary + its env / model).
+ *
+ * As of v0.9.20 the agents dict is CLI-only; API endpoints live in the
+ * sibling `apiProfiles` dict. The `tool` field is the discriminator
+ * (which CLI binary to invoke). Multiple entries with the same `tool`
+ * are allowed (used to be "CLI profiles" — now just additional named
+ * agents with their own env).
+ *
+ * Deprecated fields (`base` / `cliType` / `type` / `provider` / `apiKey`
+ * / `baseUrl`) are migrated away by migrateAgentsFlatten on first load
+ * and removed from the schema in a later release.
+ */
 export interface AgentEntry {
-  // Base agent fields (for detected agents like claude, codex, aider)
+  tool?: 'claude' | 'codex' | 'aider' | 'opencode';   // which CLI binary
   path?: string; name?: string; enabled?: boolean;
   flags?: string[]; taskFlags?: string; interactiveCmd?: string; resumeFlag?: string; outputFormat?: string;
   models?: { terminal?: string; task?: string; telegram?: string; help?: string; mobile?: string };
   skipPermissionsFlag?: string;
   requiresTTY?: boolean;
-  // Profile fields (for profiles that extend a base agent)
-  base?: string;                 // base agent ID (e.g., 'claude') — makes this a profile
-  // API profile fields
-  type?: 'cli' | 'api';         // 'api' = API mode, default = 'cli'
-  provider?: string;             // API provider label (e.g., 'anthropic', 'openai', 'litellm', 'grok', 'google')
-  model?: string;                // model override (for both CLI and API profiles)
-  apiKey?: string;               // per-profile API key (encrypted)
-  /**
-   * Base URL override for API profiles. Use this for LiteLLM / Azure /
-   * self-hosted proxies. Empty = default for the provider's protocol.
-   * For CLI profiles, set base URL via `env` (ANTHROPIC_BASE_URL etc.).
-   */
-  baseUrl?: string;
+  model?: string;                // flat model override
   env?: Record<string, string>;  // environment variables injected when spawning CLI
-  cliType?: 'claude-code' | 'codex' | 'aider' | 'generic'; // CLI tool type — determines session support, resume flags, etc.
-  profile?: string;              // linked profile ID — overrides model, env, etc. when launching
+
+  // === Deprecated (kept for migration compat; removed in a later release) ===
+  /** @deprecated migrated to `tool` */
+  base?: string;
+  /** @deprecated migrated to `tool` */
+  cliType?: 'claude-code' | 'codex' | 'aider' | 'generic';
+  /** @deprecated 'api' entries migrated to apiProfiles dict */
+  type?: 'cli' | 'api';
+  /** @deprecated moved to apiProfiles entry */
+  provider?: string;
+  /** @deprecated moved to apiProfiles entry */
+  apiKey?: string;
+  /** @deprecated moved to apiProfiles entry */
+  baseUrl?: string;
+  /** @deprecated unused */
+  profile?: string;
+}
+
+/**
+ * ApiProfile — a direct HTTP LLM endpoint (anthropic / openai-compat).
+ *
+ * Used by chat / summarizer / telegram chat surface — anything that
+ * needs a single-shot or streaming LLM call without a subprocess.
+ * Stored in `settings.apiProfiles`, not `settings.agents`. The two
+ * dicts never cross: tasks/pipelines/terminal pick from agents,
+ * chat/summarizer pick from apiProfiles. UI enforces the boundary.
+ */
+export interface ApiProfile {
+  name?: string;
+  enabled?: boolean;
+  provider: 'anthropic' | 'openai-compatible';
+  model: string;
+  apiKey: string;
+  baseUrl?: string;
 }
 
 /**
@@ -108,6 +141,9 @@ export interface Settings {
    */
   memoryBackend: 'auto' | 'local' | 'temper';
   agents: Record<string, AgentEntry>;
+  /** API endpoint profiles — chat / summarizer / telegram-chat target.
+   *  Separate from `agents` (CLI subprocess) so type guard is structural. */
+  apiProfiles: Record<string, ApiProfile>;
   /** Extra MCP servers merged into each project's .mcp.json (chrome-devtools-mcp etc.) */
   mcpServers: Record<string, McpServerConfig>;
   /**
@@ -177,6 +213,7 @@ const defaults: Settings = {
   temperNamespace: '',
   memoryBackend: 'auto',
   agents: {},
+  apiProfiles: {},
   mcpServers: {},
   timezone: '',
   smtpHost: '',
@@ -191,25 +228,35 @@ const defaults: Settings = {
   pipelineTmpGcIntervalHours: 6,
 };
 
-/** Decrypt nested apiKey fields in agent profiles */
+/** Decrypt nested apiKey fields in agents (legacy migration window) +
+ *  apiProfiles (current canonical location). */
 function decryptNestedSecrets(settings: Settings): void {
+  // Legacy: agent entries may still carry apiKey until migration runs
   if (settings.agents) {
     for (const [id, a] of Object.entries(settings.agents)) {
       if (a.apiKey && isEncrypted(a.apiKey)) {
         a.apiKey = decryptSecret(a.apiKey);
       }
-      // Defensive: a past bug let the masked placeholder get encrypted
-      // and written back. Clear it so callers see "no key" instead of
-      // trying to send '••••••••' as a Bearer header.
       if (a.apiKey && /^•+$/.test(a.apiKey)) {
         console.warn(`[settings] agent '${id}' has a placeholder apiKey — clearing. Re-enter it via Settings.`);
         a.apiKey = '';
       }
     }
   }
+  if (settings.apiProfiles) {
+    for (const [id, p] of Object.entries(settings.apiProfiles)) {
+      if (p.apiKey && isEncrypted(p.apiKey)) {
+        p.apiKey = decryptSecret(p.apiKey);
+      }
+      if (p.apiKey && /^•+$/.test(p.apiKey)) {
+        console.warn(`[settings] apiProfile '${id}' has a placeholder apiKey — clearing. Re-enter it via Settings.`);
+        p.apiKey = '';
+      }
+    }
+  }
 }
 
-/** Encrypt nested apiKey fields in agent profiles */
+/** Encrypt nested apiKey fields */
 function encryptNestedSecrets(settings: Settings): void {
   if (settings.agents) {
     for (const a of Object.values(settings.agents)) {
@@ -218,6 +265,13 @@ function encryptNestedSecrets(settings: Settings): void {
       }
     }
   }
+  if (settings.apiProfiles) {
+    for (const p of Object.values(settings.apiProfiles)) {
+      if (p.apiKey && !isEncrypted(p.apiKey)) {
+        p.apiKey = encryptSecret(p.apiKey);
+      }
+    }
+  }
 }
 
 /** Load settings with secrets decrypted (for internal use) */
@@ -248,7 +302,7 @@ export function loadSettingsMasked(): Settings & { _secretStatus: Record<string,
     status[field] = !!settings[field];
     settings[field] = settings[field] ? '••••••••' : '';
   }
-  // Mask nested apiKeys (agent profiles only)
+  // Mask nested apiKeys — agents (legacy) + apiProfiles (canonical)
   if (settings.agents) {
     for (const [name, a] of Object.entries(settings.agents)) {
       if (a.apiKey) {
@@ -257,6 +311,14 @@ export function loadSettingsMasked(): Settings & { _secretStatus: Record<string,
       }
     }
   }
+  if (settings.apiProfiles) {
+    for (const [name, p] of Object.entries(settings.apiProfiles)) {
+      if (p.apiKey) {
+        status[`apiProfiles.${name}.apiKey`] = true;
+        p.apiKey = '••••••••';
+      }
+    }
+  }
   return { ...settings, _secretStatus: status };
 }
 

package/lib/workspace/skill-installer.ts

@@ -177,6 +177,11 @@ const FORGE_HOOK_MARKER = '# forge-stop-hook';
  * When Claude Code finishes a turn, the hook notifies Forge via HTTP.
  * Preserves existing user hooks. Creates backup before modifying.
  */
+// Auto-prune leaves this many timestamped backups behind. `forge-backup-manual`
+// (or anything not matching the YYYYMMDD-HHMM suffix) is left alone.
+const FORGE_BACKUP_KEEP = 5;
+const FORGE_BACKUP_RE = /^settings\.json\.forge-backup-\d{8}-\d{4}$/;
+
 function installForgeStopHook(forgePort: number): void {
   const settingsFile = join(homedir(), '.claude', 'settings.json');
   const now = new Date();
@@ -191,11 +196,11 @@ function installForgeStopHook(forgePort: number): void {
 
   try {
     let settings: any = {};
+    let raw = '';
     if (existsSync(settingsFile)) {
-      const raw = readFileSync(settingsFile, 'utf-8');
+      raw = readFileSync(settingsFile, 'utf-8');
       settings = JSON.parse(raw);
 
-      // Check if hook already installed
       // Remove old forge hook if present (will re-add with latest version)
       if (settings.hooks?.Stop) {
         settings.hooks.Stop = settings.hooks.Stop.filter((h: any) => {
@@ -204,9 +209,6 @@ function installForgeStopHook(forgePort: number): void {
           return true;
         });
       }
-
-      // Backup before modifying
-      writeFileSync(backupFile, raw, 'utf-8');
     }
 
     if (!settings.hooks) settings.hooks = {};
@@ -222,14 +224,32 @@ function installForgeStopHook(forgePort: number): void {
       }],
     });
 
+    const next = JSON.stringify(settings, null, 2) + '\n';
+    if (next === raw) return;   // no-op — settings already had the current hook
+
     mkdirSync(join(homedir(), '.claude'), { recursive: true });
-    writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    if (raw) writeFileSync(backupFile, raw, 'utf-8');
+    writeFileSync(settingsFile, next, 'utf-8');
+    pruneForgeBackups();
     console.log('[skills] Installed Forge Stop hook in ~/.claude/settings.json');
   } catch (err: any) {
     console.error('[skills] Failed to install Stop hook:', err.message);
   }
 }
 
+function pruneForgeBackups(): void {
+  try {
+    const dir = join(homedir(), '.claude');
+    const stamped = readdirSync(dir)
+      .filter(f => FORGE_BACKUP_RE.test(f))
+      .sort();   // lexicographic == chronological (YYYYMMDD-HHMM)
+    const stale = stamped.slice(0, -FORGE_BACKUP_KEEP);
+    for (const f of stale) {
+      try { unlinkSync(join(dir, f)); } catch {}
+    }
+  } catch {}
+}
+
 /**
  * Remove Forge Stop hook from user-level settings (cleanup).
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aion0/forge",
-  "version": "0.9.19",
+  "version": "0.10.2",
   "description": "Unified AI workflow platform — multi-model task orchestration, persistent sessions, web terminal, remote access",
   "type": "module",
   "scripts": {

package/scripts/test-agents-migrate.ts

@@ -0,0 +1,149 @@
+/**
+ * Migration smoke test — feed several known-shape settings through
+ * migrateAgentsFlatten and assert post-state. Runs offline, no real
+ * data needed.
+ *
+ *   npx tsx scripts/test-agents-migrate.ts
+ */
+
+import { migrateAgentsFlatten } from '../lib/agents/migrate';
+import type { Settings } from '../lib/settings';
+
+let failures = 0;
+const fail = (msg: string) => { console.log(`  ✗ ${msg}`); failures += 1; };
+const pass = (msg: string) => console.log(`  ✓ ${msg}`);
+
+function baseSettings(): Settings {
+  return {
+    projectRoots: [], docRoots: [], claudePath: '', claudeHome: '',
+    telegramBotToken: '', telegramChatId: '',
+    notifyOnComplete: true, notifyOnFailure: true,
+    tunnelAutoStart: false, telegramTunnelPassword: '',
+    taskModel: 'default', pipelineModel: 'default', telegramModel: 'sonnet',
+    skipPermissions: false, manageClaudeConfig: true,
+    notificationRetentionDays: 30,
+    skillsRepoUrl: '', connectorsRepoUrl: '', workflowRepoUrl: '',
+    maxConcurrentPipelines: 5,
+    displayName: '', displayEmail: '', favoriteProjects: [],
+    defaultAgent: 'claude', telegramAgent: '', docsAgent: '', chatAgent: '',
+    temperUrl: '', temperKey: '', temperNamespace: '', memoryBackend: 'auto',
+    agents: {}, apiProfiles: {}, mcpServers: {}, timezone: '',
+    smtpHost: '', smtpPort: 587, smtpSecure: false, smtpUser: '', smtpPassword: '', smtpFrom: '',
+    pipelineTmpCleanDoneImmediate: true,
+    pipelineTmpKeepFailedDays: 3, pipelineTmpKeepCancelledDays: 3,
+    pipelineTmpGcIntervalHours: 6,
+  } as Settings;
+}
+
+// ── Test 1: type='api' moves to apiProfiles ──────────────────────────
+{
+  console.log('Test 1 — API profile moves out of agents');
+  const s = baseSettings();
+  s.agents = {
+    claude: { enabled: true, path: '/usr/local/bin/claude' },
+    'forti-api': { type: 'api', provider: 'litellm', model: 'DeepSeek-V4-Pro', apiKey: 'sk-...', baseUrl: 'https://x' } as any,
+  };
+  s.chatAgent = 'forti-api';
+  const mutated = migrateAgentsFlatten(s);
+  if (!mutated) fail('expected mutated=true');
+  if (s.agents['forti-api']) fail('forti-api still in agents');
+  else pass('forti-api removed from agents');
+  const p = (s as any).apiProfiles?.['forti-api'];
+  if (!p) fail('forti-api not in apiProfiles');
+  else if (p.provider !== 'openai-compatible') fail(`provider mapped wrong: ${p.provider}`);
+  else if (p.model !== 'DeepSeek-V4-Pro') fail('model lost');
+  else pass(`forti-api in apiProfiles (provider=${p.provider}, model=${p.model})`);
+  if (s.chatAgent !== 'forti-api') fail(`chatAgent corrupted: ${s.chatAgent}`);
+  else pass('chatAgent unchanged');
+}
+
+// ── Test 2: base/cliType → tool flattening ──────────────────────────
+{
+  console.log('Test 2 — CLI profile flattens to tool field');
+  const s = baseSettings();
+  s.agents = {
+    claude: { enabled: true, path: '/usr/local/bin/claude' },
+    'forti-coder': { base: 'claude', model: 'sonnet', env: { ANTHROPIC_AUTH_TOKEN: 'tok' } } as any,
+    'codex-dev': { cliType: 'codex', env: { OPENAI_API_KEY: 'k' } } as any,
+  };
+  migrateAgentsFlatten(s);
+  if (s.agents['claude']?.tool !== 'claude') fail('claude builtin tool not inferred');
+  else pass('claude tool inferred from id');
+  if (s.agents['forti-coder']?.tool !== 'claude') fail(`forti-coder tool wrong: ${s.agents['forti-coder']?.tool}`);
+  else pass('forti-coder tool inferred from base');
+  if ((s.agents['forti-coder'] as any).base) fail('base field not cleaned');
+  else pass('base field removed');
+  if (s.agents['codex-dev']?.tool !== 'codex') fail(`codex-dev tool wrong: ${s.agents['codex-dev']?.tool}`);
+  else pass('codex-dev tool inferred from cliType');
+}
+
+// ── Test 3: defaultAgent pointing to API profile downgrades ──────────
+{
+  console.log('Test 3 — defaultAgent → apiProfile downgrades to claude');
+  const s = baseSettings();
+  s.agents = {
+    claude: { enabled: true, path: '' },
+    'forti-api': { type: 'api', provider: 'anthropic', model: 'm', apiKey: 'k' } as any,
+  };
+  s.defaultAgent = 'forti-api';  // wrong! API id as task default
+  migrateAgentsFlatten(s);
+  if (s.defaultAgent !== 'claude') fail(`expected 'claude', got '${s.defaultAgent}'`);
+  else pass('defaultAgent downgraded to claude');
+}
+
+// ── Test 4: chatAgent pointing to CLI downgrades ─────────────────────
+{
+  console.log('Test 4 — chatAgent → CLI agent downgrades to first apiProfile');
+  const s = baseSettings();
+  s.agents = {
+    claude: { enabled: true, path: '' },
+    'forti-coder': { base: 'claude', model: 'sonnet' } as any,
+  };
+  (s as any).apiProfiles = {
+    'real-api': { provider: 'anthropic', model: 'claude-sonnet-4-6', apiKey: 'k', enabled: true },
+  };
+  s.chatAgent = 'forti-coder';   // wrong! CLI as chat default
+  migrateAgentsFlatten(s);
+  if (s.chatAgent !== 'real-api') fail(`expected 'real-api', got '${s.chatAgent}'`);
+  else pass('chatAgent downgraded to real-api');
+}
+
+// ── Test 5: idempotent on already-migrated shape ────────────────────
+{
+  console.log('Test 5 — idempotent');
+  const s = baseSettings();
+  s.agents = {
+    claude: { tool: 'claude', enabled: true, path: '' },
+    'forti-coder': { tool: 'claude', enabled: true, model: 'sonnet', env: {} },
+  };
+  (s as any).apiProfiles = {
+    'forti-api': { provider: 'openai-compatible', model: 'X', apiKey: 'k', enabled: true },
+  };
+  s.defaultAgent = 'claude';
+  s.chatAgent = 'forti-api';
+  const mutated = migrateAgentsFlatten(s);
+  if (mutated) fail('expected no mutation on already-migrated input');
+  else pass('idempotent (no-op)');
+}
+
+// ── Test 6: orphan entry (no inference possible) is left alone ──────
+{
+  console.log('Test 6 — orphan entry preserved');
+  const s = baseSettings();
+  s.agents = {
+    'mystery-thing': { enabled: true, model: 'whatever' } as any,
+  };
+  migrateAgentsFlatten(s);
+  if (!s.agents['mystery-thing']) fail('mystery-thing got deleted');
+  else if ((s.agents['mystery-thing'] as any).tool) fail('mystery-thing tool inferred when it shouldn\'t');
+  else pass('orphan preserved without tool (UI will skip, user re-adds)');
+}
+
+console.log('');
+if (failures === 0) {
+  console.log('✓ All migration smoke checks passed');
+  process.exit(0);
+} else {
+  console.log(`✗ ${failures} check(s) failed`);
+  process.exit(1);
+}