@dieulc/workflow 0.3.3 → 0.5.0

package/index.ts

@@ -82,11 +82,21 @@ import {
 import {
   WORKFLOW_ROLE_ENV,
   explainCommandRefusal,
+  gitCommitPolicyHit,
   policyForRole,
   resolveSessionRole,
   subagentEnv,
   type WorkflowRole,
 } from "./permissions.ts";
+import {
+  commitConfigPaths,
+  describeCommitPolicyMode,
+  readCommitPolicyConfig,
+  stepCommitDecision,
+  writeCommitPolicyConfig,
+  type CommitPolicyMode,
+  type StepCommitCandidate,
+} from "./commit-policy.ts";
 import {
   isGitRepo,
   isGitRepoSync,
@@ -115,6 +125,24 @@ import {
   type RoleModel,
   type ThinkingLevel,
 } from "./roles.ts";
+import {
+  defaultProfileConfig,
+  loadProfilesDetailed,
+  profilesFingerprint,
+  saveProfiles,
+  getProfile,
+  formatProfilesForDisplay,
+  describeProfile,
+  validateProfileName,
+  applyProfileOverlay,
+  missingProfileRoles,
+  readDefaultProfileSetting,
+  writeDefaultProfileSetting,
+  defaultProfileSettingPaths,
+  PROFILE_ROLES,
+  type ProfileConfig,
+  type Profile,
+} from "./profiles.ts";
 import {
   applySubmittedPlan,
   formatReviewStatusLines,
@@ -372,6 +400,21 @@ export default function workflowExtension(pi: ExtensionAPI) {
   let todoItems: TodoItem[] = [];
   // Plan file the current todo list was derived from (drives merge vs replace).
   let todoPlanPath: string | undefined;
+  // Armed while the user-invoked /commit flow's agent turn is running: its
+  // `git commit` bypasses the commit-policy gate (staging already happened
+  // extension-side via piExecGit, outside the tool gate). Cleared on
+  // turn_end/agent_settled so the window stays one turn wide.
+  let commitBypassActive = false;
+  // ── Deterministic per-step commits (allow mode) ──
+  // In 'allow' mode the EXTENSION — not the model — owns commit timing:
+  // exactly one commit per batch of newly completed plan steps, made at the
+  // workflow_todo tool_result boundary (the runner awaits tool_result
+  // handlers, so the commit lands before the model starts the next step).
+  // committedStepRefs makes the guarantee idempotent; stepCommitsSeeded
+  // marks pre-existing done steps (session resume, re-executed plan) as
+  // already accounted for so they never trigger a spurious commit.
+  const committedStepRefs = new Set<string>();
+  let stepCommitsSeeded = false;
   // ── Reminder throttle + staleness tracking (passive enforcement layer) ──
   let turnsSinceLastTodoWrite = 0;
   let turnsSinceLastReminder = 0;
@@ -448,6 +491,232 @@ export default function workflowExtension(pi: ExtensionAPI) {
       void _e;
     }
   }
+
+  // ── Model profiles state (session-scoped activation) ───────────
+  let profilesConfig: ProfileConfig = defaultProfileConfig();
+  let profilesLoadedFor: string | undefined;
+  let profilesLoadedFingerprint: string | undefined;
+  /** Reason the last load skipped the user file — only corrupt/legacy warns. */
+  let profilesFallbackReason: string | undefined;
+  let profilesFallbackSeverity: "info" | "warning" | undefined;
+  let profilesFallbackNotified = false;
+  /** Active profile for THIS session — never global (concurrent sessions each pick their own). */
+  let activeProfileName: string | null = null;
+  /** True once the user picked explicitly in this session; otherwise workflow.defaultProfile applies. */
+  let profileExplicit = false;
+  /** Cache for the effective (profile-overlaid) roles — see effectiveRoles(). */
+  let effectiveRolesCache: {
+    base: RoleConfig;
+    profile: string | null;
+    roles: Role[];
+  } | null = null;
+
+  function invalidateEffectiveRoles(): void {
+    effectiveRolesCache = null;
+  }
+
+  /**
+   * The single profiles accessor, mirroring ensureRoleConfig: reloads when the
+   * working directory changes or either profiles.json changes on disk (mtime/
+   * size), so a `/profile` edit made in another window is picked up without a
+   * `/reload`. Non-destructive: a bad or missing file is never overwritten
+   * (see loadProfilesDetailed). A profile activated in this session that has
+   * vanished from disk is deactivated here (with the fallback warning).
+   */
+  function ensureProfilesConfig(cwd?: string): ProfileConfig {
+    const key = cwd ?? "";
+    const fingerprint = profilesFingerprint(key);
+    if (
+      profilesLoadedFor === key &&
+      profilesLoadedFingerprint === fingerprint
+    ) {
+      return profilesConfig;
+    }
+    const loaded = loadProfilesDetailed(key);
+    profilesConfig = loaded.config;
+    profilesLoadedFor = key;
+    profilesLoadedFingerprint = fingerprint;
+    profilesFallbackReason = loaded.usedDefaults ? loaded.reason : undefined;
+    profilesFallbackSeverity = loaded.usedDefaults
+      ? loaded.severity
+      : undefined;
+    profilesFallbackNotified = false;
+    invalidateEffectiveRoles();
+    // A profile selected in this session may have been deleted/renamed in
+    // another window — fall back to the base roles flow.
+    if (activeProfileName && !getProfile(profilesConfig, activeProfileName)) {
+      activeProfileName = null;
+    }
+    return profilesConfig;
+  }
+
+  /**
+   * Surface a profiles load problem once per load. A MISSING file is the
+   * normal "feature unused" state (info — never notified); only corrupt or
+   * incompatible files warn.
+   */
+  function notifyProfilesFallback(ctx?: ExtensionContext): void {
+    if (!profilesFallbackReason || profilesFallbackNotified) return;
+    profilesFallbackNotified = true;
+    if (profilesFallbackSeverity !== "warning") return;
+    try {
+      ctx?.ui.notify(`Profiles: ${profilesFallbackReason}`, "warning");
+    } catch (_e) {
+      void _e;
+    }
+  }
+
+  /** Resolve the session's active profile object (null when none/unknown). */
+  function resolveActiveProfile(): Profile | null {
+    if (!activeProfileName) return null;
+    return getProfile(profilesConfig, activeProfileName) ?? null;
+  }
+
+  /**
+   * The effective roles for THIS session: the file-backed base roles with the
+   * active profile's model overrides applied (see applyProfileOverlay). All
+   * model-RESOLUTION sites read through this; all EDITING sites (/role, role
+   * picker) keep using the base `roleConfig`. With no profile active the
+   * overlay is a shallow copy — behaviour is identical to the roles.json flow.
+   * Cache is keyed by the base config object identity (ensureRoleConfig
+   * reassigns it on file changes) + the active profile name, and invalidated
+   * by ensureProfilesConfig / setActiveProfile.
+   */
+  function effectiveRoles(): Role[] {
+    const base = roleConfig;
+    const profileName = activeProfileName;
+    const cached = effectiveRolesCache;
+    if (cached && cached.base === base && cached.profile === profileName) {
+      return cached.roles;
+    }
+    const roles = applyProfileOverlay(base.roles, resolveActiveProfile());
+    effectiveRolesCache = { base, profile: profileName, roles };
+    return roles;
+  }
+
+  /** getRole over the effective (profile-overlaid) roles. */
+  function getEffectiveRole(name: string): Role | undefined {
+    return getRole({ ...roleConfig, roles: effectiveRoles() }, name);
+  }
+
+  /** Footer label for the active profile ("" when none). */
+  function activeProfileLabel(): string {
+    return activeProfileName ? `⚡ ${activeProfileName}` : "";
+  }
+
+  /**
+   * /role display: the base roles (what /role edits) plus, when a profile is
+   * active, an explicit section naming the profile and its model overrides.
+   * Without a profile this is exactly the plain roles display.
+   */
+  function formatRolesDisplayWithProfile(): string {
+    const base = formatRolesForDisplay(roleConfig);
+    const profile = resolveActiveProfile();
+    if (!profile) return base;
+    const lines: string[] = [
+      base,
+      "",
+      `Active profile: ⚡ ${profile.name}${
+        profile.description ? ` — ${profile.description}` : ""
+      }`,
+    ];
+    for (const roleName of PROFILE_ROLES) {
+      const m = profile.roles[roleName];
+      if (m)
+        lines.push(
+          `  ${roleIcon(roleName)} ${roleName} → ${formatModelRef(m)} (${m.thinking})  (profile override)`,
+        );
+    }
+    lines.push(
+      `  /profile edit ${profile.name} to change the profile • /profile use none to deactivate`,
+    );
+    return lines.join("\n");
+  }
+
+  /** Multi-line notification describing what an activation resolves to. */
+  function profileActivationSummary(name: string): string {
+    const profile = getProfile(profilesConfig, name);
+    if (!profile) return `Profile "${name}" activated.`;
+    const lines = [`Profile ⚡ ${profile.name} activated:`];
+    for (const roleName of PROFILE_ROLES) {
+      const m = profile.roles[roleName];
+      if (m)
+        lines.push(
+          `  ${roleIcon(roleName)} ${roleName} → ${formatModelRef(m)} (${m.thinking})`,
+        );
+    }
+    const missing = missingProfileRoles(profile);
+    if (missing.length) {
+      lines.push(
+        `  ${missing.join(", ")}: base role models (not overridden by this profile)`,
+      );
+    }
+    if (workflowMode) {
+      lines.push(`  Applied to ${workflowMode} mode now; explore/review pick it up on next use.`);
+    } else {
+      lines.push(
+        "  Applies on the next /plan, /build, explore subagent, or review round.",
+      );
+    }
+    return lines.join("\n");
+  }
+
+  /**
+   * Activate/deactivate the session's profile. Session-scoped by design — the
+   * state rides the `workflow` session entry (persistState), never a global
+   * file, so two concurrent sessions can run different profiles. When the
+   * session is in plan/build mode the role model is re-applied immediately so
+   * the profile's planner/builder take effect right away; explorer/reviewer
+   * resolution picks the profile up on next subagent/review round.
+   */
+  async function setActiveProfile(
+    ctx: ExtensionContext,
+    name: string | null,
+    opts?: { explicit?: boolean; quiet?: boolean },
+  ): Promise<void> {
+    ensureProfilesConfig((ctx as any)?.cwd);
+    const trimmed = name ? String(name).trim() : null;
+    if (trimmed) {
+      const profile = getProfile(profilesConfig, trimmed);
+      if (!profile) {
+        ctx.ui.notify(
+          `Unknown profile "${trimmed}". Available: ${
+            profilesConfig.profiles.map((p) => p.name).join(", ") ||
+            "(none — /profile create <name>)"
+          }`,
+          "warning",
+        );
+        return;
+      }
+      activeProfileName = profile.name;
+    } else {
+      activeProfileName = null;
+    }
+    profileExplicit = opts?.explicit ?? true;
+    invalidateEffectiveRoles();
+    try {
+      persistState();
+    } catch (_e) {
+      void _e;
+    }
+    updateStatus(ctx as any);
+    if (workflowMode) {
+      try {
+        await applyModeModel(ctx as any, { quiet: opts?.quiet });
+      } catch (_e) {
+        void _e;
+      }
+    }
+    if (!opts?.quiet) {
+      ctx.ui.notify(
+        activeProfileName
+          ? profileActivationSummary(activeProfileName)
+          : "Profile deactivated — default roles flow active.",
+        "info",
+      );
+    }
+  }
+
   function activeRoleLabel(): string {
     if (roleConfig.activeRole)
       return `${roleIcon(roleConfig.activeRole)} ${roleConfig.activeRole}`;
@@ -598,16 +867,32 @@ export default function workflowExtension(pi: ExtensionAPI) {
   }
 
   function updateStatus(ctx: ExtensionContext) {
+    // Profile prefix (⚡ name) when one is active, then the role label.
+    const profileLabel = activeProfileLabel();
     const roleLabel = activeRoleLabel();
-    const suffix = roleLabel ? ` | ${roleLabel}` : "";
+    const statusParts = [profileLabel, roleLabel].filter(Boolean);
+    const suffix = statusParts.length ? ` | ${statusParts.join(" | ")}` : "";
+    // Commit-policy surfacing (workflow.commitPolicy): always visible so the
+    // user can see at a glance what the agent may do to git history. Read
+    // live so /commit-policy changes show up without a reload.
+    let commitMode: CommitPolicyMode = "never";
+    try {
+      commitMode = readCommitPolicyConfig(
+        (ctx as any).cwd ?? process.cwd(),
+        getAgentDir(),
+      ).config.mode;
+    } catch {
+      commitMode = "never";
+    }
+    const policy = ` · commits:${commitMode}`;
     const staleMarker = todoStale ? " ⚠" : "";
     const done = todoItems.filter((t) => isDone(t)).length;
     const total = todoItems.length;
     if (workflowMode === "build") {
       const label =
         total > 0
-          ? `▶ build ${done}/${total}${staleMarker}${suffix}`
-          : `▶ build${suffix}`;
+          ? `▶ build ${done}/${total}${staleMarker}${suffix}${policy}`
+          : `▶ build${suffix}${policy}`;
       ctx.ui.setStatus("workflow", ctx.ui.theme.fg("accent", label));
     } else if (workflowMode === "plan") {
       const base = plannotatorActive
@@ -615,16 +900,22 @@ export default function workflowExtension(pi: ExtensionAPI) {
         : "⏸ plan";
       const label =
         total > 0
-          ? `${base} ${done}/${total}${staleMarker}${suffix}`
-          : `${base}${suffix}`;
+          ? `${base} ${done}/${total}${staleMarker}${suffix}${policy}`
+          : `${base}${suffix}${policy}`;
       ctx.ui.setStatus("workflow", ctx.ui.theme.fg("warning", label));
     } else if (total > 0) {
       ctx.ui.setStatus(
         "workflow",
-        ctx.ui.theme.fg("muted", `◦ ${done}/${total}${staleMarker}${suffix}`),
+        ctx.ui.theme.fg(
+          "muted",
+          `◦ ${done}/${total}${staleMarker}${suffix}${policy}`,
+        ),
       );
     } else {
-      ctx.ui.setStatus("workflow", undefined);
+      ctx.ui.setStatus(
+        "workflow",
+        ctx.ui.theme.fg("muted", `◦ commits:${commitMode}`),
+      );
     }
     if (todoItems.length > 0) {
       ctx.ui.setWidget("workflow-todos", (_tui, theme) => {
@@ -675,7 +966,8 @@ export default function workflowExtension(pi: ExtensionAPI) {
   /** Reviewer model label for the mode band (best-effort). */
   function reviewModelLabel(): string {
     ensureRoleConfig(reviewCwd());
-    const r = getRole(roleConfig, REVIEW_ROLE_NAME);
+    ensureProfilesConfig(reviewCwd());
+    const r = getEffectiveRole(REVIEW_ROLE_NAME);
     return r?.model ? formatModelRef(r.model) : "unconfigured";
   }
 
@@ -843,9 +1135,11 @@ export default function workflowExtension(pi: ExtensionAPI) {
   ): Promise<string> {
     return (async () => {
       const cwd = reviewCwd();
+      ensureRoleConfig(cwd);
+      ensureProfilesConfig(cwd);
       const agents = discoverAgents(cwd);
       const base = agents.find((a) => a.name === "scout") ?? agents[0];
-      const explorerRole = getRole(roleConfig, "explorer");
+      const explorerRole = getEffectiveRole("explorer");
       const m = explorerRole?.model;
       const agent: AgentConfig = {
         name: base?.name ?? "review-scout",
@@ -883,11 +1177,12 @@ export default function workflowExtension(pi: ExtensionAPI) {
       config: () => reviewConfigNow()?.config,
       reviewerModel: () => {
         ensureRoleConfig(cwd);
-        const reviewer = getRole(roleConfig, REVIEW_ROLE_NAME);
+        ensureProfilesConfig(cwd);
+        const reviewer = getEffectiveRole(REVIEW_ROLE_NAME);
         if (reviewer?.model) return reviewer.model;
         // Graceful degradation: fall back to the planner model rather than
         // silently running no review at all.
-        const planner = getRole(roleConfig, "planner");
+        const planner = getEffectiveRole("planner");
         return planner?.model;
       },
       findModel: (provider: string, id: string) =>
@@ -1087,7 +1382,8 @@ export default function workflowExtension(pi: ExtensionAPI) {
       if (!sub || sub === "status") {
         const resolved = readReviewModeConfig(cwd, agentDir);
         const c = resolved.config;
-        const model = getRole(roleConfig, REVIEW_ROLE_NAME)?.model;
+        ensureProfilesConfig(cwd);
+        const model = getEffectiveRole(REVIEW_ROLE_NAME)?.model;
         ctx.ui.notify(
           formatReviewStatusLines({
             enabled: c.enabled,
@@ -1200,6 +1496,112 @@ export default function workflowExtension(pi: ExtensionAPI) {
     },
   });
 
+  // ── /commit-policy: view/set the commit policy (workflow.commitPolicy) ──
+  // Available in every mode: it only writes settings JSON; the gate itself
+  // lives in tool_call and plan mode keeps its own stricter rules.
+  pi.registerCommand("commit-policy", {
+    description:
+      "View or set the commit policy (what the agent may git add/commit/push): /commit-policy never|ask|allow [global|project]",
+    handler: async (args, ctx) => {
+      const cwd = (ctx as any)?.cwd ?? process.cwd();
+      const agentDir = getAgentDir();
+      const tokens = String(args || "")
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
+      const sub = (tokens[0] || "").toLowerCase();
+      const scope: "global" | "project" =
+        tokens.includes("project") && !tokens.includes("global")
+          ? "project"
+          : "global";
+
+      if (!sub || sub === "status") {
+        const resolved = readCommitPolicyConfig(cwd, agentDir);
+        const paths = commitConfigPaths(cwd, agentDir);
+        const where =
+          resolved.sources.mode === "default"
+            ? "default — no settings file supplies it"
+            : `${resolved.sources.mode} settings`;
+        ctx.ui.notify(
+          [
+            `Commit policy: ${resolved.config.mode} (${where})`,
+            `  ${describeCommitPolicyMode(resolved.config.mode)}`,
+            `Global settings: ${paths.global}`,
+            `Project settings: ${paths.project}`,
+            "Usage: /commit-policy never|ask|allow [global|project]",
+          ].join("\n"),
+          "info",
+        );
+        updateStatus(ctx as any);
+        return;
+      }
+
+      if (sub !== "never" && sub !== "ask" && sub !== "allow") {
+        ctx.ui.notify(
+          [
+            "Usage: /commit-policy never|ask|allow [global|project]",
+            "  never  agent cannot git add/commit/push — you commit (or /commit)",
+            "  ask    agent may commit; each git commit/push asks first",
+            "  allow  agent may commit freely (per-step during plan execution)",
+          ].join("\n"),
+          "info",
+        );
+        return;
+      }
+
+      const res = writeCommitPolicyConfig(scope, cwd, agentDir, {
+        mode: sub as CommitPolicyMode,
+      });
+      if (!res.ok) {
+        ctx.ui.notify(
+          `Could not write commit-policy settings: ${res.error ?? "unknown error"}`,
+          "error",
+        );
+        return;
+      }
+      ctx.ui.notify(
+        `Commit policy → ${sub} (${scope})\n${describeCommitPolicyMode(
+          sub as CommitPolicyMode,
+        )}\nSettings: ${res.path}`,
+        "info",
+      );
+      updateStatus(ctx as any);
+    },
+    getArgumentCompletions: (prefix: string) => {
+      const flags = [
+        {
+          value: "never",
+          label: "never",
+          description:
+            "agent cannot git add/commit/push — you commit (or /commit)",
+        },
+        {
+          value: "ask",
+          label: "ask",
+          description: "agent may commit; each git commit/push asks first",
+        },
+        {
+          value: "allow",
+          label: "allow",
+          description:
+            "agent may commit freely (per-step during plan execution)",
+        },
+        {
+          value: "global",
+          label: "global",
+          description: "write to ~/.pi/agent/settings.json",
+        },
+        {
+          value: "project",
+          label: "project",
+          description: "write to <cwd>/.pi/settings.json",
+        },
+      ];
+      const filtered = flags.filter((f) => f.value.startsWith(prefix));
+      return filtered.length ? filtered : null;
+    },
+  });
+
   pi.registerCommand("review-prompt", {
     description:
       "Edit the reviewer's guidance (framework alignment / best practice) used by Review Mode",
@@ -1357,13 +1759,18 @@ export default function workflowExtension(pi: ExtensionAPI) {
     if (!workflowMode) return false;
     try {
       ensureRoleConfig((ctx as any)?.cwd ?? ctx.cwd);
+      ensureProfilesConfig((ctx as any)?.cwd ?? ctx.cwd);
     } catch (_e) {
       void _e;
     }
-    const resolved = resolveModeModel(roleConfig, workflowMode);
+    // Resolution reads the EFFECTIVE roles (base roles + active profile
+    // overlay); with no profile active this is behaviourally identical to
+    // the base config.
+    const effectiveCfg: RoleConfig = { ...roleConfig, roles: effectiveRoles() };
+    const resolved = resolveModeModel(effectiveCfg, workflowMode);
     if (!resolved) {
-      const targetName = roleConfig.activeRole ?? MODE_ROLE_MAP[workflowMode];
-      const role = targetName ? getRole(roleConfig, targetName) : undefined;
+      const targetName = effectiveCfg.activeRole ?? MODE_ROLE_MAP[workflowMode];
+      const role = targetName ? getRole(effectiveCfg, targetName) : undefined;
       if (targetName && !role) {
         ctx.ui.notify(
           `Workflow ${workflowMode}: role "${targetName}" not found — staying on current model.`,
@@ -1549,6 +1956,10 @@ export default function workflowExtension(pi: ExtensionAPI) {
       awaitingDecisionAt: awaitingDecision ? lastHandoffAt : undefined,
       role: {
         activeRole: roleConfig.activeRole,
+        // Session-scoped profile activation (see setActiveProfile): explicit
+        // picks restore exactly; non-explicit entries re-derive the default.
+        activeProfile: profileExplicit ? activeProfileName : null,
+        profileExplicit,
       },
       defaultModel,
       lastModeSwitch,
@@ -1845,7 +2256,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
       };
       const firstTodo = todoItems[0];
       const feedbackBlock = feedback ? `\n\nFeedback: ${feedback}` : "";
-      const execMessage = `Execute the plan.\n\nRemaining steps:\n${remainingList}\n\nStart with: ${firstTodo ? firstTodo.text : (todoItems[0]?.text ?? "first step")}${feedbackBlock}\nAfter completing a step, include a [DONE:<ref>] tag in your response (use the numbers shown above).`;
+      const execMessage = `Execute the plan.\n\nRemaining steps:\n${remainingList}\n\nStart with: ${firstTodo ? firstTodo.text : (todoItems[0]?.text ?? "first step")}${feedbackBlock}${commitDirectiveLine(ctx)}\nAfter completing a step, include a [DONE:<ref>] tag in your response (use the numbers shown above).`;
       (pi as any).sendMessage?.(planTodoListMessage, { deliverAs: "followUp" });
       (pi as any).sendMessage?.(
         {
@@ -2121,6 +2532,10 @@ export default function workflowExtension(pi: ExtensionAPI) {
 
     // Inject a user message → triggers an agent turn that proposes + confirms + commits
     const message = buildCommitPrompt(statSummary, stageAll);
+    // Arm the commit-policy bypass for exactly this agent turn: its `git
+    // commit` must run even under policy 'never'. Disarmed on turn_end /
+    // agent_settled, so the window is one turn wide.
+    commitBypassActive = true;
     if ((pi as any).sendUserMessage) {
       (pi as any).sendUserMessage(message);
     } else {
@@ -2628,19 +3043,19 @@ export default function workflowExtension(pi: ExtensionAPI) {
           await openRolePicker(ctx as any);
           return;
         }
-        ctx.ui.notify(formatRolesForDisplay(roleConfig), "info");
+        ctx.ui.notify(formatRolesDisplayWithProfile(), "info");
         return;
       }
 
       if (sub === "list" || sub === "show") {
-        ctx.ui.notify(formatRolesForDisplay(roleConfig), "info");
+        ctx.ui.notify(formatRolesDisplayWithProfile(), "info");
         return;
       }
 
       if (sub === "config") {
         if (!(ctx as any)?.hasUI) {
           ctx.ui.notify(
-            formatRolesForDisplay(roleConfig) +
+            formatRolesDisplayWithProfile() +
               "\n\nPicker needs UI — use /role set instead.",
             "info",
           );
@@ -2820,125 +3235,1498 @@ export default function workflowExtension(pi: ExtensionAPI) {
     },
   });
 
-  // ── Role config screen (tabbed picker: one block per role) ─────────
+  // ── Model profiles command + management UI ───────────────────────
   //
-  // One overlay with a tab per role (built-ins first, then customs) plus
-  // a Submit tab. Each role tab has two phases: pick model (from the
-  // connected providers — scoped models first, Ctrl+O for all) then pick
-  // thinking level. Selections stage locally; Submit saves to roles.json.
-
-  interface StagedRoleModel {
-    provider: string;
-    id: string;
-    thinking: ThinkingLevel;
-  }
-
-  interface RoleCatalogEntry {
-    provider: string;
-    id: string;
-    inScope: boolean;
-  }
-
-  function collectRoleCatalog(ctx: ExtensionContext): {
-    scoped: RoleCatalogEntry[];
-    all: RoleCatalogEntry[];
-    truncated: boolean;
-  } {
-    const scoped: RoleCatalogEntry[] = [];
-    try {
-      const raw = ((ctx as any)?.scopedModels ?? []) as any[];
-      for (const s of raw) {
-        const m = s?.model ?? s;
-        if (m && typeof m.provider === "string" && typeof m.id === "string")
-          scoped.push({ provider: m.provider, id: m.id, inScope: true });
-      }
-    } catch (_e) {
-      void _e;
-    }
-    let available: any[] = [];
+  // A profile is a named combination of role model settings (planner /
+  // explorer / builder / reviewer). Profiles are DEFINED in profiles.json;
+  // ACTIVATION is session-scoped (setActiveProfile) so two concurrent
+  // sessions can run different profiles. /role keeps editing the base roles;
+  // an active profile only overlays models on top (see effectiveRoles()).
+
+  const PROFILE_USAGE =
+    "Usage: /profile (picker) | /profile list | /profile show <name> | " +
+    "/profile use <name|none> | /profile create <name> | /profile edit <name> | " +
+    "/profile rename <old> <new> | /profile delete <name> | " +
+    "/profile default [name|none] [global|project]";
+
+  /** Effective workflow.defaultProfile for display (never throws). */
+  function currentDefaultProfileName(cwd?: string): string | undefined {
     try {
-      const reg = (ctx as any)?.modelRegistry;
-      if (reg && typeof reg.getAvailable === "function")
-        available = [...reg.getAvailable()];
-      else if (reg && typeof reg.getAll === "function")
-        available = [...reg.getAll()];
+      return readDefaultProfileSetting(cwd ?? process.cwd(), getAgentDir())
+        .value;
     } catch (_e) {
       void _e;
+      return undefined;
     }
-    const seen = new Set(scoped.map((s) => `${s.provider}/${s.id}`));
-    const rest: RoleCatalogEntry[] = [];
-    for (const m of available) {
-      if (!m || typeof m.provider !== "string" || typeof m.id !== "string")
-        continue;
-      const key = `${m.provider}/${m.id}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-      rest.push({ provider: m.provider, id: m.id, inScope: false });
-    }
-    const CAP = 200;
-    const all = [...scoped, ...rest];
-    return {
-      scoped,
-      all: all.slice(0, CAP),
-      truncated: all.length > CAP,
-    };
   }
 
-  function orderedRoleTabs(): Role[] {
-    // Built-in roles first in their declared order, then custom roles.
-    // Driven by BUILT_IN_ROLES so adding a role never needs a second edit here.
-    const rank = (name: string) => {
-      const i = (BUILT_IN_ROLES as readonly string[]).indexOf(
-        name.toLowerCase(),
-      );
-      return i === -1 ? BUILT_IN_ROLES.length : i;
-    };
-    return [...roleConfig.roles].sort((a, b) => rank(a.name) - rank(b.name));
+  /** Seed a new profile from the CURRENT effective roles (base + active profile). */
+  function buildProfileSeed(name: string, description = ""): Profile {
+    const seed: Profile = { name, description, roles: {} };
+    for (const roleName of PROFILE_ROLES) {
+      const m = getEffectiveRole(roleName)?.model;
+      if (m) seed.roles[roleName] = { ...m };
+    }
+    return seed;
   }
 
-  async function openRolePicker(ctx: ExtensionContext): Promise<void> {
-    const tabs = orderedRoleTabs();
-    if (tabs.length === 0) {
-      ctx.ui.notify("No roles configured — /role reset to reseed.", "warning");
-      return;
-    }
-    const catalog = collectRoleCatalog(ctx);
-    if (catalog.all.length === 0) {
-      ctx.ui.notify(
-        "No models available from connected providers — connect a provider first, or use /role set <role> <provider/model> [thinking].",
-        "warning",
-      );
-      return;
-    }
-    // Stage current values so the picker opens on the active selection.
-    const staged = new Map<string, StagedRoleModel>();
-    for (const r of tabs) staged.set(r.name, { ...r.model });
+  const listThemeOf = (theme: any) => ({
+    selectedPrefix: (t: string) => theme.fg("accent", t),
+    selectedText: (t: string) => theme.fg("accent", t),
+    description: (t: string) => theme.fg("muted", t),
+    scrollInfo: (t: string) => theme.fg("dim", t),
+    noMatch: (t: string) => theme.fg("warning", t),
+  });
 
-    overlayActive = true;
-    let saved: Map<string, StagedRoleModel> | null = null;
-    try {
-      saved = await ctx.ui.custom<Map<string, StagedRoleModel> | null>(
-        (tui, theme, _kb, done) => {
-          let currentTab = 0; // tabs.length = Submit
-          let phase: "model" | "thinking" = "model";
-          let showAll = catalog.scoped.length === 0;
-          let cached: string[] | undefined;
-          // One SelectList per role tab for models + one shared for thinking,
-          // so filter text + cursor survive tab switches.
-          const listTheme = {
-            selectedPrefix: (t: string) => theme.fg("accent", t),
-            selectedText: (t: string) => theme.fg("accent", t),
-            description: (t: string) => theme.fg("muted", t),
-            scrollInfo: (t: string) => theme.fg("dim", t),
-            noMatch: (t: string) => theme.fg("warning", t),
-          };
-          const currentRef = (role: Role) =>
-            `${role.model.provider}/${role.model.id}`;
-          const buildModelItems = (role: Role): SelectItem[] => {
-            const st = staged.get(role.name)!;
-            const cur = `${st.provider}/${st.id}`;
-            const src = showAll ? catalog.all : catalog.scoped;
-            return src.map((e) => {
+  /** Small confirm overlay (used by /profile delete). True only on explicit Delete. */
+  async function confirmProfileDelete(
+    ctx: ExtensionContext,
+    profile: Profile,
+  ): Promise<boolean> {
+    const result = await ctx.ui.custom<boolean | null>(
+      (tui, theme, _kb, done) => {
+        const list = new SelectList(
+          [
+            {
+              value: "delete",
+              label: `Delete ⚡ ${profile.name}`,
+              description: "remove from profiles.json (cannot be undone)",
+            },
+            {
+              value: "cancel",
+              label: "Cancel",
+              description: "keep the profile",
+            },
+          ],
+          2,
+          listThemeOf(theme),
+        );
+        let cached: string[] | undefined;
+        return {
+          render: (width: number) => {
+            if (cached) return cached;
+            const W = Math.max(1, width);
+            const lines: string[] = [];
+            lines.push(theme.fg("accent", "─".repeat(W)));
+            lines.push(
+              ` ${theme.fg("warning", `Delete profile "${profile.name}"?`)}`,
+            );
+            lines.push("");
+            for (const l of list.render(Math.max(1, W - 2))) lines.push(` ${l}`);
+            lines.push("");
+            lines.push(
+              ` ${theme.fg("dim", "↑↓ navigate • Enter select • Esc cancel")}`,
+            );
+            lines.push(theme.fg("accent", "─".repeat(W)));
+            cached = lines;
+            return lines;
+          },
+          invalidate: () => {
+            cached = undefined;
+          },
+          handleInput: (data: string) => {
+            if (matchesKey(data, Key.escape)) {
+              done(null);
+              return;
+            }
+            if (matchesKey(data, Key.enter)) {
+              done(list.getSelectedItem()?.value === "delete");
+              return;
+            }
+            list.handleInput(data);
+            cached = undefined;
+            tui.requestRender();
+          },
+        };
+      },
+    );
+    return result === true;
+  }
+
+  /**
+   * Free-text profile name entry (Editor overlay, same input pattern as the
+   * questionnaire). Resolves the validated name, or null on cancel/invalid-Esc.
+   */
+  async function inputProfileName(
+    ctx: ExtensionContext,
+    opts: {
+      title: string;
+      initial?: string;
+      /** Names that would collide (case-insensitive), minus any being renamed. */
+      existing?: readonly string[];
+    },
+  ): Promise<string | null> {
+    return ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+      const editorTheme: EditorTheme = {
+        borderColor: (s) => theme.fg("accent", s),
+        selectList: {
+          selectedPrefix: (t: string) => theme.fg("accent", t),
+          selectedText: (t: string) => theme.fg("accent", t),
+          description: (t: string) => theme.fg("muted", t),
+          scrollInfo: (t: string) => theme.fg("dim", t),
+          noMatch: (t: string) => theme.fg("warning", t),
+        },
+      };
+      const editor = new Editor(tui, editorTheme);
+      if (opts.initial) editor.setText(opts.initial);
+      let error = "";
+      let cached: string[] | undefined;
+      editor.onSubmit = (value: string) => {
+        const check = validateProfileName(String(value ?? ""), opts.existing);
+        if (!check.ok) {
+          error = check.error;
+          cached = undefined;
+          tui.requestRender();
+          return;
+        }
+        done(check.value);
+      };
+      return {
+        render: (width: number) => {
+          if (cached) return cached;
+          const W = Math.max(1, width);
+          const lines: string[] = [];
+          lines.push(theme.fg("accent", "─".repeat(W)));
+          lines.push(
+            ...wrapTextWithAnsi(` ${theme.fg("text", opts.title)}`, W),
+          );
+          if (error)
+            lines.push(
+              ...wrapTextWithAnsi(` ${theme.fg("warning", error)}`, W),
+            );
+          lines.push("");
+          for (const l of editor.render(Math.max(1, W))) lines.push(l);
+          lines.push("");
+          lines.push(` ${theme.fg("dim", "Enter confirm • Esc cancel")}`);
+          lines.push(theme.fg("accent", "─".repeat(W)));
+          cached = lines;
+          return lines;
+        },
+        invalidate: () => {
+          cached = undefined;
+        },
+        handleInput: (data: string) => {
+          if (matchesKey(data, Key.escape)) {
+            done(null);
+            return;
+          }
+          editor.handleInput(data);
+          cached = undefined;
+          tui.requestRender();
+        },
+      };
+    });
+  }
+
+  /**
+   * Profile management picker: activate / none / new / per-profile actions
+   * (edit, rename, delete) and the default-profile entry. Loops so actions
+   * return to the list; every action handles its own persistence.
+   */
+  async function openProfilePicker(ctx: ExtensionContext): Promise<void> {
+    ensureProfilesConfig((ctx as any)?.cwd);
+    ensureRoleConfig((ctx as any)?.cwd);
+    while (true) {
+      const profiles = profilesConfig.profiles;
+      const def = currentDefaultProfileName((ctx as any)?.cwd);
+      const entries: SelectItem[] = [];
+      entries.push({
+        value: "none",
+        label: activeProfileName
+          ? "— none (default roles) —"
+          : "● — none (default roles) —",
+        description: "deactivate any profile; the roles.json flow applies",
+      });
+      for (const p of profiles) {
+        const isActive =
+          activeProfileName?.toLowerCase() === p.name.toLowerCase();
+        const isDefault = def?.toLowerCase() === p.name.toLowerCase();
+        const markers = [
+          isActive ? "● active" : "",
+          isDefault ? "★ default" : "",
+        ]
+          .filter(Boolean)
+          .join(", ");
+        const modelSummary = PROFILE_ROLES.map((r) => {
+          const m = p.roles[r];
+          return m ? `${roleIcon(r)} ${formatModelRef(m)}` : null;
+        })
+          .filter(Boolean)
+          .join(" · ");
+        entries.push({
+          value: p.name,
+          label: `⚡ ${p.name}${markers ? `  (${markers})` : ""}`,
+          description: p.description || modelSummary || undefined,
+        });
+      }
+      entries.push({
+        value: "__new",
+        label: "＋ New profile…",
+        description: "name it, then pick a model per role (like /role)",
+      });
+      entries.push({
+        value: "__default",
+        label: "Default for new sessions…",
+        description: `workflow.defaultProfile — currently: ${def ?? "(none)"}`,
+      });
+
+      const selected = await ctx.ui.custom<string | null>(
+        (tui, theme, _kb, done) => {
+          const list = new SelectList(entries, 10, listThemeOf(theme));
+          let cached: string[] | undefined;
+          return {
+            render: (width: number) => {
+              if (cached) return cached;
+              const W = Math.max(1, width);
+              const lines: string[] = [];
+              lines.push(theme.fg("accent", "─".repeat(W)));
+              lines.push(
+                ` ${theme.fg("text", "Model Profiles")} ${theme.fg(
+                  "muted",
+                  `— active: ${activeProfileName ?? "none (default roles)"}`,
+                )}`,
+              );
+              lines.push("");
+              for (const l of list.render(Math.max(1, W - 2)))
+                lines.push(` ${l}`);
+              lines.push("");
+              lines.push(
+                ` ${theme.fg("dim", "Enter: select/action • type to filter • Esc close")}`,
+              );
+              lines.push(theme.fg("accent", "─".repeat(W)));
+              cached = lines;
+              return lines;
+            },
+            invalidate: () => {
+              cached = undefined;
+            },
+            handleInput: (data: string) => {
+              if (matchesKey(data, Key.escape)) {
+                done(null);
+                return;
+              }
+              if (matchesKey(data, Key.enter)) {
+                done(list.getSelectedItem()?.value ?? null);
+                return;
+              }
+              list.handleInput(data);
+              cached = undefined;
+              tui.requestRender();
+            },
+          };
+        },
+      );
+      if (!selected) return; // Esc / closed
+      if (selected === "__new") {
+        const name = await inputProfileName(ctx, {
+          title: "New profile — name (dashes, no spaces):",
+          existing: profilesConfig.profiles.map((p) => p.name),
+        });
+        if (!name) continue;
+        await openProfileEditor(ctx, { createName: name });
+        continue;
+      }
+      if (selected === "__default") {
+        await pickDefaultProfile(ctx);
+        continue;
+      }
+      if (selected === "none") {
+        if (activeProfileName) {
+          await setActiveProfile(ctx as any, null, { explicit: true });
+        } else {
+          ctx.ui.notify("No profile active — default roles flow.", "info");
+        }
+        continue;
+      }
+      // A concrete profile → action menu
+      const profile = getProfile(profilesConfig, selected);
+      if (!profile) continue;
+      const action = await ctx.ui.custom<string | null>(
+        (tui, theme, _kb, done) => {
+          const isActive =
+            activeProfileName?.toLowerCase() === profile.name.toLowerCase();
+          const list = new SelectList(
+            [
+              isActive
+                ? {
+                    value: "deactivate",
+                    label: "Deactivate",
+                    description: "back to default roles (this session)",
+                  }
+                : {
+                    value: "activate",
+                    label: "Activate now",
+                    description:
+                      "session-scoped; plan/build re-apply immediately",
+                  },
+              {
+                value: "edit",
+                label: "Edit models",
+                description: "tabbed editor — model + thinking per role",
+              },
+              {
+                value: "rename",
+                label: "Rename",
+                description: "change the profile name",
+              },
+              {
+                value: "delete",
+                label: "Delete",
+                description: "remove from profiles.json",
+              },
+              { value: "back", label: "Back", description: "return to the profile list" },
+            ],
+            5,
+            listThemeOf(theme),
+          );
+          let cached: string[] | undefined;
+          return {
+            render: (width: number) => {
+              if (cached) return cached;
+              const W = Math.max(1, width);
+              const lines: string[] = [];
+              lines.push(theme.fg("accent", "─".repeat(W)));
+              lines.push(
+                ` ${theme.fg("text", `⚡ ${profile.name}`)}${
+                  profile.description
+                    ? theme.fg("muted", ` — ${profile.description}`)
+                    : ""
+                }`,
+              );
+              lines.push("");
+              for (const l of list.render(Math.max(1, W - 2)))
+                lines.push(` ${l}`);
+              lines.push("");
+              lines.push(` ${theme.fg("dim", "Enter select • Esc back")}`);
+              lines.push(theme.fg("accent", "─".repeat(W)));
+              cached = lines;
+              return lines;
+            },
+            invalidate: () => {
+              cached = undefined;
+            },
+            handleInput: (data: string) => {
+              if (matchesKey(data, Key.escape)) {
+                done(null);
+                return;
+              }
+              if (matchesKey(data, Key.enter)) {
+                done(list.getSelectedItem()?.value ?? null);
+                return;
+              }
+              list.handleInput(data);
+              cached = undefined;
+              tui.requestRender();
+            },
+          };
+        },
+      );
+      if (!action || action === "back") continue;
+      if (action === "activate") {
+        await setActiveProfile(ctx as any, profile.name, { explicit: true });
+        continue;
+      }
+      if (action === "deactivate") {
+        await setActiveProfile(ctx as any, null, { explicit: true });
+        continue;
+      }
+      if (action === "edit") {
+        await openProfileEditor(ctx, { name: profile.name });
+        continue;
+      }
+      if (action === "rename") {
+        const newName = await inputProfileName(ctx, {
+          title: `Rename profile "${profile.name}" to:`,
+          initial: profile.name,
+          existing: profilesConfig.profiles
+            .filter((p) => p !== profile)
+            .map((p) => p.name),
+        });
+        if (newName && newName !== profile.name) {
+          const wasActive =
+            activeProfileName?.toLowerCase() === profile.name.toLowerCase();
+          profile.name = newName;
+          if (wasActive) activeProfileName = profile.name;
+          invalidateEffectiveRoles();
+          try {
+            saveProfiles(profilesConfig, "user");
+            ctx.ui.notify(`Profile renamed → ⚡ ${profile.name}.`, "info");
+          } catch (e: any) {
+            ctx.ui.notify(
+              `Renamed in memory but file save failed: ${String(e?.message || e)}`,
+              "warning",
+            );
+          }
+          updateStatus(ctx as any);
+        }
+        continue;
+      }
+      if (action === "delete") {
+        const confirmed = await confirmProfileDelete(ctx, profile);
+        if (!confirmed) continue;
+        const wasActive =
+          activeProfileName?.toLowerCase() === profile.name.toLowerCase();
+        profilesConfig.profiles = profilesConfig.profiles.filter(
+          (p) => p !== profile,
+        );
+        if (wasActive) {
+          activeProfileName = null;
+          invalidateEffectiveRoles();
+        }
+        try {
+          saveProfiles(profilesConfig, "user");
+          ctx.ui.notify(
+            `Profile ⚡ ${profile.name} deleted.${
+              wasActive
+                ? " It was active — default roles flow restored."
+                : ""
+            }`,
+            "info",
+          );
+        } catch (e: any) {
+          ctx.ui.notify(
+            `Deleted in memory but file save failed: ${String(e?.message || e)}`,
+            "warning",
+          );
+        }
+        if (wasActive && workflowMode) {
+          try {
+            await applyModeModel(ctx as any);
+          } catch (_e) {
+            void _e;
+          }
+        }
+        updateStatus(ctx as any);
+        continue;
+      }
+    }
+  }
+
+  /** Picker for the default profile (workflow.defaultProfile) + its scope. */
+  async function pickDefaultProfile(ctx: ExtensionContext): Promise<void> {
+    const cwd = (ctx as any)?.cwd as string | undefined;
+    const current = currentDefaultProfileName(cwd);
+    const entries: SelectItem[] = [
+      {
+        value: "__none",
+        label: "— none —",
+        description: "new sessions start without a profile",
+      },
+      ...profilesConfig.profiles.map((p) => ({
+        value: p.name,
+        label: `⚡ ${p.name}`,
+        description: p.description || undefined,
+      })),
+    ];
+    const name = await ctx.ui.custom<string | null>(
+      (tui, theme, _kb, done) => {
+        const list = new SelectList(entries, 8, listThemeOf(theme));
+        let cached: string[] | undefined;
+        return {
+          render: (width: number) => {
+            if (cached) return cached;
+            const W = Math.max(1, width);
+            const lines: string[] = [];
+            lines.push(theme.fg("accent", "─".repeat(W)));
+            lines.push(
+              ` ${theme.fg("text", "Default profile for new sessions")} ${theme.fg(
+                "muted",
+                `— currently: ${current ?? "(none)"}`,
+              )}`,
+            );
+            lines.push("");
+            for (const l of list.render(Math.max(1, W - 2)))
+              lines.push(` ${l}`);
+            lines.push("");
+            lines.push(` ${theme.fg("dim", "Enter select • Esc cancel")}`);
+            lines.push(theme.fg("accent", "─".repeat(W)));
+            cached = lines;
+            return lines;
+          },
+          invalidate: () => {
+            cached = undefined;
+          },
+          handleInput: (data: string) => {
+            if (matchesKey(data, Key.escape)) {
+              done(null);
+              return;
+            }
+            if (matchesKey(data, Key.enter)) {
+              done(list.getSelectedItem()?.value ?? null);
+              return;
+            }
+            list.handleInput(data);
+            cached = undefined;
+            tui.requestRender();
+          },
+        };
+      },
+    );
+    if (name === null) return;
+    // Keep the scope where the setting currently lives (else global).
+    const resolved = readDefaultProfileSetting(
+      cwd ?? process.cwd(),
+      getAgentDir(),
+    );
+    const scope: "global" | "project" =
+      resolved.sources.effective === "project" ? "project" : "global";
+    const value = name === "__none" ? null : name;
+    const res = writeDefaultProfileSetting(
+      scope,
+      cwd ?? process.cwd(),
+      getAgentDir(),
+      value,
+    );
+    if (!res.ok) {
+      ctx.ui.notify(
+        `Could not write default profile: ${res.error ?? "unknown error"}`,
+        "error",
+      );
+      return;
+    }
+    ctx.ui.notify(
+      value
+        ? `Default profile → ⚡ ${value} (${scope} settings)\nNew sessions without an explicit /profile use start on it.`
+        : `Default profile cleared (${scope} settings).`,
+      "info",
+    );
+    updateStatus(ctx as any);
+  }
+
+  interface StagedProfileModel {
+    provider: string;
+    id: string;
+    thinking: ThinkingLevel;
+  }
+
+  /**
+   * Tabbed profile editor — one tab per built-in role (planner / explorer /
+   * builder / reviewer, mirroring /role) plus two submit tabs: Save &
+   * activate and Save only. Selections stage locally; saving writes
+   * profiles.json (user scope). `createName` creates a new profile seeded
+   * from the current effective roles; `name` edits an existing one.
+   */
+  async function openProfileEditor(
+    ctx: ExtensionContext,
+    opts: { createName?: string; name?: string },
+  ): Promise<void> {
+    ensureProfilesConfig((ctx as any)?.cwd);
+    ensureRoleConfig((ctx as any)?.cwd);
+    const catalog = collectRoleCatalog(ctx);
+    if (catalog.all.length === 0) {
+      ctx.ui.notify(
+        "No models available from connected providers — connect a provider first.",
+        "warning",
+      );
+      return;
+    }
+    const existing = opts.name
+      ? getProfile(profilesConfig, opts.name)
+      : undefined;
+    if (opts.name && !existing) {
+      ctx.ui.notify(`Profile "${opts.name}" no longer exists.`, "warning");
+      return;
+    }
+    const isNew = !existing;
+    const profileName = existing
+      ? existing.name
+      : (opts.createName ?? "").trim();
+    if (!profileName) {
+      ctx.ui.notify("Profile name required.", "warning");
+      return;
+    }
+    const roleMeta = new Map<string, { name: string; description: string }>();
+    for (const roleName of PROFILE_ROLES) {
+      const base = getRole(roleConfig, roleName);
+      roleMeta.set(roleName, {
+        name: roleName,
+        description: base?.description ?? `Role ${roleName}`,
+      });
+    }
+    // Keep the narrow tuple type so profile.roles[roleName] typechecks.
+    const tabIds = [...PROFILE_ROLES];
+    // Stage from the profile (edit) or the current effective roles (create).
+    const staged = new Map<string, StagedProfileModel>();
+    for (const roleName of PROFILE_ROLES) {
+      const src =
+        existing?.roles[roleName] ?? getEffectiveRole(roleName)?.model;
+      staged.set(roleName, {
+        provider: src?.provider ?? "",
+        id: src?.id ?? "",
+        thinking: src?.thinking ?? "medium",
+      });
+    }
+
+    overlayActive = true;
+    let saved: {
+      activate: boolean;
+      staged: Map<string, StagedProfileModel>;
+    } | null = null;
+    try {
+      saved = await ctx.ui.custom<
+        { activate: boolean; staged: Map<string, StagedProfileModel> } | null
+      >((tui, theme, _kb, done) => {
+        let currentTab = 0;
+        let phase: "model" | "thinking" = "model";
+        let showAll = catalog.scoped.length === 0;
+        let cached: string[] | undefined;
+        const themeList = listThemeOf(theme);
+        const isSubmitTab = () => currentTab >= tabIds.length;
+        const isSaveActivate = () => currentTab === tabIds.length;
+        const buildModelItems = (roleName: string): SelectItem[] => {
+          const st = staged.get(roleName)!;
+          const cur = `${st.provider}/${st.id}`;
+          const src = showAll ? catalog.all : catalog.scoped;
+          return src.map((e) => {
+            const ref = `${e.provider}/${e.id}`;
+            const description: string | undefined =
+              ref === cur
+                ? "● selected"
+                : showAll && !e.inScope
+                  ? "all"
+                  : undefined;
+            return { value: ref, label: ref, description };
+          });
+        };
+        const modelLists = new Map<string, SelectList>();
+        const thinkingList = new SelectList(
+          VALID_THINKING_LEVELS.map((t) => ({ value: t, label: t })),
+          Math.min(VALID_THINKING_LEVELS.length, 8),
+          themeList,
+        );
+        const getModelList = (roleName: string): SelectList => {
+          let list = modelLists.get(roleName);
+          if (!list) {
+            list = new SelectList(buildModelItems(roleName), 10, themeList);
+            const st = staged.get(roleName)!;
+            const idx = (showAll ? catalog.all : catalog.scoped).findIndex(
+              (e) => `${e.provider}/${e.id}` === `${st.provider}/${st.id}`,
+            );
+            if (idx > 0) list.setSelectedIndex(idx);
+            modelLists.set(roleName, list);
+          }
+          return list;
+        };
+        const rebuildModelLists = () => modelLists.clear();
+        const syncThinkingCursor = (roleName: string) => {
+          const st = staged.get(roleName)!;
+          const idx = VALID_THINKING_LEVELS.indexOf(st.thinking);
+          if (idx >= 0) thinkingList.setSelectedIndex(idx);
+        };
+        const commitModelSelection = (roleName: string) => {
+          const sel = getModelList(roleName).getSelectedItem();
+          if (!sel) return false;
+          const { provider, id } = parseModelRef(sel.value);
+          if (!provider || !id) return false;
+          const st = staged.get(roleName)!;
+          staged.set(roleName, { ...st, provider, id });
+          return true;
+        };
+        const commitThinkingSelection = (roleName: string) => {
+          const sel = thinkingList.getSelectedItem();
+          if (!sel || !isValidThinkingLevel(sel.value)) return false;
+          const st = staged.get(roleName)!;
+          staged.set(roleName, { ...st, thinking: sel.value });
+          return true;
+        };
+        const advanceFromThinking = () => {
+          if (currentTab < tabIds.length) currentTab++;
+          phase = "model";
+          cached = undefined;
+          tui.requestRender();
+        };
+
+        const handleInput = (data: string) => {
+          if (matchesKey(data, Key.escape)) {
+            if (phase === "thinking" && !isSubmitTab()) {
+              phase = "model";
+              cached = undefined;
+              tui.requestRender();
+              return;
+            }
+            done(null);
+            return;
+          }
+          if (
+            matchesKey(data, Key.tab) ||
+            matchesKey(data, Key.right) ||
+            matchesKey(data, Key.shift("tab")) ||
+            matchesKey(data, Key.left)
+          ) {
+            const fwd =
+              matchesKey(data, Key.tab) || matchesKey(data, Key.right);
+            const n = tabIds.length + 2;
+            currentTab = fwd
+              ? (currentTab + 1) % n
+              : (currentTab - 1 + n) % n;
+            phase = "model";
+            cached = undefined;
+            tui.requestRender();
+            return;
+          }
+          // Ctrl+O toggles scoped ↔ all models
+          try {
+            if (matchesKey(data, Key.ctrl("o"))) {
+              showAll = !showAll;
+              rebuildModelLists();
+              cached = undefined;
+              tui.requestRender();
+              return;
+            }
+          } catch (_e) {
+            void _e;
+          }
+          if (isSubmitTab()) {
+            if (matchesKey(data, Key.enter)) {
+              done({ activate: isSaveActivate(), staged: new Map(staged) });
+            }
+            return;
+          }
+          const roleName = tabIds[currentTab];
+          if (matchesKey(data, Key.enter)) {
+            if (phase === "model") {
+              if (!commitModelSelection(roleName)) return;
+              phase = "thinking";
+              syncThinkingCursor(roleName);
+              cached = undefined;
+              tui.requestRender();
+              return;
+            }
+            if (!commitThinkingSelection(roleName)) return;
+            advanceFromThinking();
+            return;
+          }
+          if (phase === "model") getModelList(roleName).handleInput(data);
+          else thinkingList.handleInput(data);
+          cached = undefined;
+          tui.requestRender();
+        };
+
+        const render = (width: number): string[] => {
+          if (cached) return cached;
+          const lines: string[] = [];
+          const W = Math.max(1, width);
+          const wrap = (s: string) => {
+            const out: string[] = [];
+            for (const line of s.split("\n"))
+              out.push(...wrapTextWithAnsi(line, W));
+            return out;
+          };
+          lines.push(theme.fg("accent", "─".repeat(W)));
+          lines.push(
+            ` ${theme.fg(
+              "text",
+              `${isNew ? "New profile" : "Edit profile"} ⚡ ${profileName}`,
+            )}`,
+          );
+          lines.push("");
+          // Tabs row: one block per role + two submit tabs
+          const chips: string[] = [];
+          for (let i = 0; i < tabIds.length; i++) {
+            const roleName = tabIds[i];
+            const st = staged.get(roleName)!;
+            const base = existing?.roles[roleName];
+            const dirty =
+              !base ||
+              `${st.provider}/${st.id}` !== `${base.provider}/${base.id}` ||
+              st.thinking !== base.thinking;
+            const box = dirty ? "■" : "□";
+            const lbl = ` ${box} ${roleIcon(roleName)} ${roleName} `;
+            chips.push(
+              i === currentTab
+                ? theme.bg("selectedBg", theme.fg("text", lbl))
+                : theme.fg(dirty ? "success" : "muted", lbl),
+            );
+          }
+          const saveActivateLbl = " ✓ Save & activate ";
+          const saveOnlyLbl = " 💾 Save only ";
+          chips.push(
+            isSaveActivate()
+              ? theme.bg("selectedBg", theme.fg("text", saveActivateLbl))
+              : theme.fg("success", saveActivateLbl),
+          );
+          chips.push(
+            currentTab === tabIds.length + 1
+              ? theme.bg("selectedBg", theme.fg("text", saveOnlyLbl))
+              : theme.fg("success", saveOnlyLbl),
+          );
+          lines.push(` ${chips.join("")}`);
+          lines.push("");
+          if (isSubmitTab()) {
+            lines.push(
+              ...wrap(
+                ` ${theme.fg(
+                  "text",
+                  isSaveActivate()
+                    ? "Save & activate — Enter saves and switches this session to the profile; Esc cancels"
+                    : "Save only — Enter saves without activating; Esc cancels",
+                )}`,
+              ),
+            );
+            lines.push("");
+            for (const roleName of tabIds) {
+              const st = staged.get(roleName)!;
+              lines.push(
+                ...wrap(
+                  `  ${theme.fg("muted", `${roleIcon(roleName)} ${roleName}: `)}${theme.fg(
+                    "text",
+                    st.provider
+                      ? `${st.provider}/${st.id} (${st.thinking})`
+                      : "(unset)",
+                  )}`,
+                ),
+              );
+            }
+          } else {
+            const roleName = tabIds[currentTab];
+            const st = staged.get(roleName)!;
+            const meta = roleMeta.get(roleName)!;
+            lines.push(
+              ...wrap(
+                ` ${theme.fg("text", `${roleIcon(roleName)} ${roleName} — ${meta.description}`)}`,
+              ),
+            );
+            lines.push(
+              ...wrap(
+                ` ${theme.fg(
+                  "muted",
+                  `staged: ${
+                    st.provider
+                      ? `${st.provider}/${st.id} (${st.thinking})`
+                      : "(unset)"
+                  }`,
+                )}`,
+              ),
+            );
+            lines.push("");
+            if (phase === "model") {
+              const scopeLabel = showAll
+                ? `all ${String(catalog.all.length)}${catalog.truncated ? "+" : ""}`
+                : `scoped ${String(catalog.scoped.length)}`;
+              const toggleHint =
+                catalog.scoped.length > 0 && !showAll
+                  ? " — Ctrl+O for all"
+                  : "";
+              lines.push(
+                ...wrap(
+                  ` ${theme.fg(
+                    "accent",
+                    `Model (${scopeLabel}${toggleHint}) — type to filter:`,
+                  )}`,
+                ),
+              );
+              for (const l of getModelList(roleName).render(Math.max(1, W - 2)))
+                lines.push(` ${l}`);
+            } else {
+              lines.push(
+                ...wrap(` ${theme.fg("accent", "Thinking level:")}`),
+              );
+              for (const l of thinkingList.render(Math.max(1, W - 2)))
+                lines.push(` ${l}`);
+            }
+          }
+          lines.push("");
+          lines.push(
+            ...wrap(
+              ` ${theme.fg(
+                "dim",
+                "Tab/←→ roles • ↑↓ navigate • type to filter • Enter select • Esc back/cancel • Ctrl+O scoped/all",
+              )}`,
+            ),
+          );
+          lines.push(theme.fg("accent", "─".repeat(W)));
+          cached = lines;
+          return lines;
+        };
+
+        return {
+          render,
+          invalidate: () => {
+            cached = undefined;
+          },
+          handleInput,
+        };
+      });
+    } finally {
+      overlayActive = false;
+    }
+    if (!saved) {
+      ctx.ui.notify(
+        isNew ? "Profile creation cancelled." : "Profile editor cancelled.",
+        "info",
+      );
+      return;
+    }
+    // Validate against registry (warn-only, matching /role set).
+    try {
+      const reg = (ctx as any)?.modelRegistry;
+      if (reg && typeof reg.find === "function") {
+        for (const [roleName, st] of saved.staged) {
+          if (
+            st.provider &&
+            st.id &&
+            typeof reg.find === "function" &&
+            !reg.find(st.provider, st.id)
+          )
+            ctx.ui.notify(
+              `Warning: ${st.provider}/${st.id} (${roleName}) not in model registry — saved anyway.`,
+              "warning",
+            );
+        }
+      }
+    } catch (_e) {
+      void _e;
+    }
+    // Materialize: create or update the profile, then persist.
+    let profile = existing;
+    if (!profile) {
+      profile = { name: profileName, description: "", roles: {} };
+      profilesConfig.profiles.push(profile);
+    }
+    profile.roles = {};
+    for (const roleName of PROFILE_ROLES) {
+      const st = saved.staged.get(roleName);
+      if (st && st.provider && st.id)
+        profile.roles[roleName] = {
+          provider: st.provider,
+          id: st.id,
+          thinking: st.thinking,
+        };
+    }
+    try {
+      saveProfiles(profilesConfig, "user");
+    } catch (e: any) {
+      ctx.ui.notify(
+        `Profile updated but file save failed: ${String(e?.message || e)}`,
+        "warning",
+      );
+      return;
+    }
+    invalidateEffectiveRoles();
+    updateStatus(ctx as any);
+    if (saved.activate) {
+      await setActiveProfile(ctx as any, profile.name, { explicit: true });
+    } else {
+      ctx.ui.notify(
+        `Profile ⚡ ${profile.name} saved. Activate with /profile use ${profile.name}.`,
+        "info",
+      );
+    }
+  }
+
+  // ── Model profiles command ───────────────────────────────────────
+
+  pi.registerCommand("profile", {
+    description:
+      "Switch or manage model profiles (named role-model combinations) — opens picker UI",
+    handler: async (args, ctx) => {
+      const cwd = (ctx as any)?.cwd as string | undefined;
+      ensureRoleConfig(cwd);
+      ensureProfilesConfig(cwd);
+      const parts = String(args || "")
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
+      const sub = (parts[0] || "").toLowerCase();
+      const rest = parts.slice(1);
+
+      const persistAndNotify = (msg: string): boolean => {
+        try {
+          saveProfiles(profilesConfig, "user");
+        } catch (e: any) {
+          ctx.ui.notify(
+            `Profile updated but file save failed: ${String(e?.message || e)}`,
+            "warning",
+          );
+          return false;
+        }
+        invalidateEffectiveRoles();
+        updateStatus(ctx as any);
+        ctx.ui.notify(msg, "info");
+        return true;
+      };
+
+      // Bare /profile → picker UI (headless → text summary).
+      if (!sub) {
+        if ((ctx as any)?.hasUI) {
+          await openProfilePicker(ctx as any);
+          return;
+        }
+        ctx.ui.notify(
+          formatProfilesForDisplay(
+            profilesConfig,
+            activeProfileName,
+            currentDefaultProfileName(cwd),
+          ),
+          "info",
+        );
+        return;
+      }
+
+      if (sub === "list" || (sub === "show" && !rest[0])) {
+        ctx.ui.notify(
+          formatProfilesForDisplay(
+            profilesConfig,
+            activeProfileName,
+            currentDefaultProfileName(cwd),
+          ),
+          "info",
+        );
+        return;
+      }
+
+      if (sub === "show") {
+        const p = getProfile(profilesConfig, rest[0]);
+        if (!p) {
+          ctx.ui.notify(`Unknown profile "${rest[0]}".`, "warning");
+          return;
+        }
+        ctx.ui.notify(describeProfile(p), "info");
+        return;
+      }
+
+      if (sub === "use" || sub === "activate") {
+        const name = rest[0];
+        if (
+          !name ||
+          (name.toLowerCase() !== "none" &&
+            name.toLowerCase() !== "off" &&
+            !getProfile(profilesConfig, name))
+        ) {
+          ctx.ui.notify(
+            `Usage: /profile use <name|none>. Available: ${
+              profilesConfig.profiles.map((p) => p.name).join(", ") ||
+              "(none — /profile create <name>)"
+            }`,
+            "info",
+          );
+          return;
+        }
+        await setActiveProfile(
+          ctx as any,
+          name.toLowerCase() === "none" || name.toLowerCase() === "off"
+            ? null
+            : name,
+          { explicit: true },
+        );
+        return;
+      }
+
+      if (sub === "create" || sub === "new" || sub === "add") {
+        const rawName = rest[0];
+        if (!rawName) {
+          ctx.ui.notify("Usage: /profile create <name>", "info");
+          return;
+        }
+        const check = validateProfileName(
+          rawName,
+          profilesConfig.profiles.map((p) => p.name),
+        );
+        if (!check.ok) {
+          ctx.ui.notify(`Cannot create profile: ${check.error}`, "warning");
+          return;
+        }
+        if ((ctx as any)?.hasUI) {
+          await openProfileEditor(ctx as any, { createName: check.value });
+          return;
+        }
+        // Headless: create seeded from the current effective roles.
+        const seed = buildProfileSeed(check.value);
+        profilesConfig.profiles.push(seed);
+        persistAndNotify(
+          `Profile ⚡ ${seed.name} created (seeded from the current effective models). Activate with /profile use ${seed.name}.`,
+        );
+        return;
+      }
+
+      if (sub === "edit" || sub === "config") {
+        const name = rest[0];
+        if (!name) {
+          ctx.ui.notify("Usage: /profile edit <name>", "info");
+          return;
+        }
+        const p = getProfile(profilesConfig, name);
+        if (!p) {
+          ctx.ui.notify(
+            `Unknown profile "${name}". Available: ${
+              profilesConfig.profiles.map((q) => q.name).join(", ") || "(none)"
+            }`,
+            "warning",
+          );
+          return;
+        }
+        if (!(ctx as any)?.hasUI) {
+          ctx.ui.notify(describeProfile(p) + "\n\nEditor needs UI.", "info");
+          return;
+        }
+        await openProfileEditor(ctx as any, { name: p.name });
+        return;
+      }
+
+      if (sub === "rename" || sub === "mv") {
+        const [oldName, newName] = rest;
+        if (!oldName || !newName) {
+          ctx.ui.notify("Usage: /profile rename <old> <new>", "info");
+          return;
+        }
+        const p = getProfile(profilesConfig, oldName);
+        if (!p) {
+          ctx.ui.notify(`Unknown profile "${oldName}".`, "warning");
+          return;
+        }
+        const check = validateProfileName(
+          newName,
+          profilesConfig.profiles
+            .filter((q) => q !== p)
+            .map((q) => q.name),
+        );
+        if (!check.ok) {
+          ctx.ui.notify(`Cannot rename: ${check.error}`, "warning");
+          return;
+        }
+        const wasActive =
+          activeProfileName?.toLowerCase() === p.name.toLowerCase();
+        p.name = check.value;
+        if (wasActive) activeProfileName = p.name;
+        invalidateEffectiveRoles();
+        persistAndNotify(
+          `Profile renamed → ⚡ ${p.name}${
+            wasActive ? " (still active in this session)" : ""
+          }`,
+        );
+        const def = readDefaultProfileSetting(
+          cwd ?? process.cwd(),
+          getAgentDir(),
+        );
+        if (def.value && def.value.toLowerCase() === oldName.toLowerCase()) {
+          ctx.ui.notify(
+            `workflow.defaultProfile still points at "${def.value}" — update with /profile default ${p.name}${
+              def.sources.effective === "project" ? " project" : ""
+            }`,
+            "warning",
+          );
+        }
+        return;
+      }
+
+      if (sub === "delete" || sub === "remove" || sub === "rm") {
+        const name = rest[0];
+        if (!name) {
+          ctx.ui.notify("Usage: /profile delete <name>", "info");
+          return;
+        }
+        const p = getProfile(profilesConfig, name);
+        if (!p) {
+          ctx.ui.notify(`Unknown profile "${name}".`, "warning");
+          return;
+        }
+        if ((ctx as any)?.hasUI) {
+          const confirmed = await confirmProfileDelete(ctx as any, p);
+          if (!confirmed) {
+            ctx.ui.notify("Deletion cancelled.", "info");
+            return;
+          }
+        }
+        const wasActive =
+          activeProfileName?.toLowerCase() === p.name.toLowerCase();
+        profilesConfig.profiles = profilesConfig.profiles.filter(
+          (q) => q !== p,
+        );
+        if (wasActive) {
+          activeProfileName = null;
+          invalidateEffectiveRoles();
+        }
+        const savedOk = persistAndNotify(
+          `Profile ⚡ ${p.name} deleted.${
+            wasActive ? " It was active — default roles flow restored." : ""
+          }`,
+        );
+        if (savedOk && wasActive && workflowMode) {
+          try {
+            await applyModeModel(ctx as any);
+            updateStatus(ctx as any);
+          } catch (_e) {
+            void _e;
+          }
+        }
+        return;
+      }
+
+      if (sub === "default") {
+        // /profile default [name|none] [global|project]
+        const target = rest.find(
+          (t) => t.toLowerCase() !== "global" && t.toLowerCase() !== "project",
+        );
+        const scope: "global" | "project" = rest
+          .map((t) => t.toLowerCase())
+          .includes("project")
+          ? "project"
+          : "global";
+        const paths = defaultProfileSettingPaths(
+          cwd ?? process.cwd(),
+          getAgentDir(),
+        );
+        if (!target) {
+          const resolved = readDefaultProfileSetting(
+            cwd ?? process.cwd(),
+            getAgentDir(),
+          );
+          ctx.ui.notify(
+            [
+              `Default profile (workflow.defaultProfile): ${
+                resolved.value ?? "(none)"
+              } (${resolved.sources.effective})`,
+              `Global settings: ${paths.global}`,
+              `Project settings: ${paths.project}`,
+              "New sessions without an explicit /profile use start on the default profile.",
+              "Usage: /profile default <name|none> [global|project]",
+            ].join("\n"),
+            "info",
+          );
+          return;
+        }
+        const value =
+          target.toLowerCase() === "none" || target.toLowerCase() === "off"
+            ? null
+            : target;
+        if (value && !getProfile(profilesConfig, value)) {
+          ctx.ui.notify(
+            `Unknown profile "${value}". Available: ${
+              profilesConfig.profiles.map((q) => q.name).join(", ") || "(none)"
+            }`,
+            "warning",
+          );
+          return;
+        }
+        const res = writeDefaultProfileSetting(
+          scope,
+          cwd ?? process.cwd(),
+          getAgentDir(),
+          value,
+        );
+        if (!res.ok) {
+          ctx.ui.notify(
+            `Could not write default profile: ${res.error ?? "unknown error"}`,
+            "error",
+          );
+          return;
+        }
+        ctx.ui.notify(
+          value
+            ? `Default profile → ⚡ ${value} (${scope} settings)\nNew sessions without an explicit /profile use start on it.`
+            : `Default profile cleared (${scope} settings).`,
+          "info",
+        );
+        updateStatus(ctx as any);
+        return;
+      }
+
+      // Bare profile name → show detail (mirrors /role <name>).
+      const named = getProfile(profilesConfig, sub);
+      if (named) {
+        ctx.ui.notify(describeProfile(named), "info");
+        return;
+      }
+      ctx.ui.notify(PROFILE_USAGE, "info");
+    },
+    getArgumentCompletions: (prefix: string) => {
+      ensureProfilesConfig();
+      const subs = [
+        { value: "list", label: "list", description: "show all profiles" },
+        {
+          value: "use",
+          label: "use <name|none>",
+          description: "activate/deactivate for this session",
+        },
+        {
+          value: "create",
+          label: "create <name>",
+          description: "create a profile (seeded from current models)",
+        },
+        {
+          value: "edit",
+          label: "edit <name>",
+          description: "open the tabbed model editor",
+        },
+        {
+          value: "rename",
+          label: "rename <old> <new>",
+          description: "rename a profile",
+        },
+        {
+          value: "delete",
+          label: "delete <name>",
+          description: "delete a profile",
+        },
+        {
+          value: "default",
+          label: "default [name|none] [global|project]",
+          description: "default profile for new sessions",
+        },
+        {
+          value: "show",
+          label: "show <name>",
+          description: "show one profile's models",
+        },
+      ];
+      const lower = String(prefix || "").toLowerCase();
+      if (lower.includes(" ")) {
+        // Completing an argument after a subcommand → profile names where relevant.
+        const cmd = lower.trim().split(/\s+/)[0];
+        const wantsNames =
+          cmd === "use" ||
+          cmd === "edit" ||
+          cmd === "delete" ||
+          cmd === "show" ||
+          cmd === "default";
+        if (!wantsNames) return null;
+        const last = lower.trim().split(/\s+/).pop() ?? "";
+        const names = profilesConfig.profiles
+          .filter((p) => p.name.toLowerCase().startsWith(last))
+          .map((p) => ({
+            value: p.name,
+            label: p.name,
+            description: p.description || undefined,
+          }));
+        return cmd === "use" || cmd === "default"
+          ? [
+              ...names,
+              { value: "none", label: "none", description: "no profile" },
+            ]
+          : names;
+      }
+      const matching = subs.filter((s) => s.value.startsWith(lower));
+      if (matching.length > 0) return matching;
+      const names = profilesConfig.profiles
+        .filter((p) => p.name.toLowerCase().startsWith(lower))
+        .map((p) => ({
+          value: p.name,
+          label: p.name,
+          description: p.description || undefined,
+        }));
+      return names.length ? names : null;
+    },
+  });
+
+  // ── Role config screen (tabbed picker: one block per role) ─────────
+  //
+  // One overlay with a tab per role (built-ins first, then customs) plus
+  // a Submit tab. Each role tab has two phases: pick model (from the
+  // connected providers — scoped models first, Ctrl+O for all) then pick
+  // thinking level. Selections stage locally; Submit saves to roles.json.
+
+  interface StagedRoleModel {
+    provider: string;
+    id: string;
+    thinking: ThinkingLevel;
+  }
+
+  interface RoleCatalogEntry {
+    provider: string;
+    id: string;
+    inScope: boolean;
+  }
+
+  function collectRoleCatalog(ctx: ExtensionContext): {
+    scoped: RoleCatalogEntry[];
+    all: RoleCatalogEntry[];
+    truncated: boolean;
+  } {
+    const scoped: RoleCatalogEntry[] = [];
+    try {
+      const raw = ((ctx as any)?.scopedModels ?? []) as any[];
+      for (const s of raw) {
+        const m = s?.model ?? s;
+        if (m && typeof m.provider === "string" && typeof m.id === "string")
+          scoped.push({ provider: m.provider, id: m.id, inScope: true });
+      }
+    } catch (_e) {
+      void _e;
+    }
+    let available: any[] = [];
+    try {
+      const reg = (ctx as any)?.modelRegistry;
+      if (reg && typeof reg.getAvailable === "function")
+        available = [...reg.getAvailable()];
+      else if (reg && typeof reg.getAll === "function")
+        available = [...reg.getAll()];
+    } catch (_e) {
+      void _e;
+    }
+    const seen = new Set(scoped.map((s) => `${s.provider}/${s.id}`));
+    const rest: RoleCatalogEntry[] = [];
+    for (const m of available) {
+      if (!m || typeof m.provider !== "string" || typeof m.id !== "string")
+        continue;
+      const key = `${m.provider}/${m.id}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      rest.push({ provider: m.provider, id: m.id, inScope: false });
+    }
+    const CAP = 200;
+    const all = [...scoped, ...rest];
+    return {
+      scoped,
+      all: all.slice(0, CAP),
+      truncated: all.length > CAP,
+    };
+  }
+
+  function orderedRoleTabs(): Role[] {
+    // Built-in roles first in their declared order, then custom roles.
+    // Driven by BUILT_IN_ROLES so adding a role never needs a second edit here.
+    const rank = (name: string) => {
+      const i = (BUILT_IN_ROLES as readonly string[]).indexOf(
+        name.toLowerCase(),
+      );
+      return i === -1 ? BUILT_IN_ROLES.length : i;
+    };
+    return [...roleConfig.roles].sort((a, b) => rank(a.name) - rank(b.name));
+  }
+
+  async function openRolePicker(ctx: ExtensionContext): Promise<void> {
+    const tabs = orderedRoleTabs();
+    if (tabs.length === 0) {
+      ctx.ui.notify("No roles configured — /role reset to reseed.", "warning");
+      return;
+    }
+    const catalog = collectRoleCatalog(ctx);
+    if (catalog.all.length === 0) {
+      ctx.ui.notify(
+        "No models available from connected providers — connect a provider first, or use /role set <role> <provider/model> [thinking].",
+        "warning",
+      );
+      return;
+    }
+    // Stage current values so the picker opens on the active selection.
+    const staged = new Map<string, StagedRoleModel>();
+    for (const r of tabs) staged.set(r.name, { ...r.model });
+
+    overlayActive = true;
+    let saved: Map<string, StagedRoleModel> | null = null;
+    try {
+      saved = await ctx.ui.custom<Map<string, StagedRoleModel> | null>(
+        (tui, theme, _kb, done) => {
+          let currentTab = 0; // tabs.length = Submit
+          let phase: "model" | "thinking" = "model";
+          let showAll = catalog.scoped.length === 0;
+          let cached: string[] | undefined;
+          // One SelectList per role tab for models + one shared for thinking,
+          // so filter text + cursor survive tab switches.
+          const listTheme = {
+            selectedPrefix: (t: string) => theme.fg("accent", t),
+            selectedText: (t: string) => theme.fg("accent", t),
+            description: (t: string) => theme.fg("muted", t),
+            scrollInfo: (t: string) => theme.fg("dim", t),
+            noMatch: (t: string) => theme.fg("warning", t),
+          };
+          const currentRef = (role: Role) =>
+            `${role.model.provider}/${role.model.id}`;
+          const buildModelItems = (role: Role): SelectItem[] => {
+            const st = staged.get(role.name)!;
+            const cur = `${st.provider}/${st.id}`;
+            const src = showAll ? catalog.all : catalog.scoped;
+            return src.map((e) => {
               const ref = `${e.provider}/${e.id}`;
               let description: string | undefined;
               if (ref === cur) {
@@ -3086,6 +4874,16 @@ export default function workflowExtension(pi: ExtensionAPI) {
               return out;
             };
             lines.push(theme.fg("accent", "─".repeat(W)));
+            // Profile notice: /role edits the BASE roles; an active profile
+            // overlays models on top (see effectiveRoles).
+            if (activeProfileName) {
+              lines.push(
+                ...wrap(
+                  ` ${theme.fg("warning", `Profile ⚡ ${activeProfileName} active — editing BASE roles; profile overrides apply on top. /profile edit ${activeProfileName} to change the profile.`)}`,
+                ),
+              );
+              lines.push("");
+            }
             // Tabs row: one block per role + Submit
             const chips: string[] = [];
             for (let i = 0; i < tabs.length; i++) {
@@ -3321,7 +5119,9 @@ export default function workflowExtension(pi: ExtensionAPI) {
       // Tasks whose agent has no explicit model use the explorer role's
       // single model. Telemetry lands in details.
       ensureRoleConfig(cwd);
-      const explorerRole = getRole(roleConfig, "explorer");
+      ensureProfilesConfig(cwd);
+      // Active profile's explorer model when a profile is active.
+      const explorerRole = getEffectiveRole("explorer");
       const routedMeta: { role: string; model: string; reason: string }[] =
         new Array(jobs.length);
       const routedAgents: (AgentConfig | undefined)[] = new Array(jobs.length);
@@ -4353,10 +6153,12 @@ export default function workflowExtension(pi: ExtensionAPI) {
   pi.on("session_start", async (event, ctx) => {
     // Roles are file-backed; load them up-front so every read path (status,
     // band label, reviewer runtime) sees the real config even in a fresh
-    // session that has no persisted workflow entry yet.
+    // session that has no persisted workflow entry yet. Profiles likewise.
     try {
       ensureRoleConfig((ctx as any)?.cwd);
       notifyRoleConfigFallback(ctx as ExtensionContext);
+      ensureProfilesConfig((ctx as any)?.cwd);
+      notifyProfilesFallback(ctx as ExtensionContext);
     } catch (_e) {
       void _e;
     }
@@ -4386,13 +6188,42 @@ export default function workflowExtension(pi: ExtensionAPI) {
             toolsBeforePlanMode = d.toolsBeforePlanMode;
             currentPlanFile = d.planFile;
             // restore role state (file config is source of truth for roles;
-            // session entry carries the latest activeRole)
+            // session entry carries the latest activeRole) and the session's
+            // own profile activation
             try {
               ensureRoleConfig((ctx as any)?.cwd);
+              ensureProfilesConfig((ctx as any)?.cwd);
               const rd = (d as any).role;
               if (rd && typeof rd === "object") {
                 if (typeof rd.activeRole === "string" || rd.activeRole === null)
                   roleConfig.activeRole = rd.activeRole;
+                // Profiles: an explicit pick restores exactly (name or none);
+                // entries without an explicit choice (fresh / pre-profile /
+                // default-seeded) re-derive workflow.defaultProfile below so
+                // a changed default still applies on resume.
+                profileExplicit = rd.profileExplicit === true;
+                if (profileExplicit) {
+                  activeProfileName =
+                    typeof rd.activeProfile === "string"
+                      ? rd.activeProfile
+                      : null;
+                  if (
+                    activeProfileName &&
+                    !getProfile(profilesConfig, activeProfileName)
+                  ) {
+                    try {
+                      (ctx as any).ui?.notify?.(
+                        `Profiles: "${activeProfileName}" no longer exists — default roles flow active.`,
+                        "warning",
+                      );
+                    } catch (_e) {
+                      void _e;
+                    }
+                    activeProfileName = null;
+                  }
+                } else {
+                  activeProfileName = null;
+                }
               }
             } catch (_e) {
               void _e;
@@ -4474,6 +6305,39 @@ export default function workflowExtension(pi: ExtensionAPI) {
     } catch (_e) {
       void _e;
     }
+    // Default-profile seeding: sessions without an explicit choice follow
+    // workflow.defaultProfile, re-read at every start/resume so a changed
+    // default applies. Sessions that picked explicitly (or explicitly chose
+    // none) never see the default.
+    if (!profileExplicit) {
+      try {
+        const def = readDefaultProfileSetting(
+          (ctx as any).cwd ?? process.cwd(),
+          getAgentDir(),
+        ).value;
+        if (def) {
+          ensureProfilesConfig((ctx as any)?.cwd);
+          const p = getProfile(profilesConfig, def);
+          if (p) {
+            if (activeProfileName !== p.name) {
+              activeProfileName = p.name;
+              invalidateEffectiveRoles();
+            }
+          } else {
+            try {
+              (ctx as any).ui?.notify?.(
+                `Profiles: default profile "${def}" not found in profiles.json — skipping.`,
+                "warning",
+              );
+            } catch (_e) {
+              void _e;
+            }
+          }
+        }
+      } catch (_e) {
+        void _e;
+      }
+    }
     // auto-enable plan mode if flag set at startup (support both --plan and --workflow-plan)
     const flagPlan =
       (pi as any).getFlagValue?.("plan") ??
@@ -4594,6 +6458,118 @@ export default function workflowExtension(pi: ExtensionAPI) {
     updateStatus(ctx as any);
   });
 
+  // ── Commit policy gate (workflow.commitPolicy) ──────────────────
+
+  /**
+   * Deterministic enforcement of the user's commit policy. Returns a block
+   * result for `git add` / `git commit` / `git push` per the active mode, or
+   * undefined when the command may proceed:
+   *   never → block; ask → confirmation overlay (headless: fail closed);
+   *   allow → automatic per-step commits while a plan todo list is active
+   * (the extension owns commit timing — model-initiated git add/commit/push
+   * are blocked); outside a plan the model may commit as before. The
+   * user-invoked /commit flow arms `commitBypassActive` so its own `git
+   * commit` runs (staging is extension-side; `push` and `add` are never
+   * bypassed).
+   */
+  async function commitPolicyGate(
+    event: any,
+    ctx: any,
+    cwd: string,
+  ): Promise<{ block: true; reason: string } | undefined> {
+    const policy = readCommitPolicyConfig(cwd, getAgentDir()).config.mode;
+    // allow outside a plan: no per-step automation to own commit timing, so
+    // the model keeps its previous freedom.
+    if (policy === "allow" && todoItems.length === 0) return undefined;
+    const cmd = String(event?.input?.command ?? "");
+    const hit = gitCommitPolicyHit(cmd);
+    if (!hit) return undefined;
+    // `add` is only gated in `never` mode; `ask` prompts on commit/push only
+    // (staging alone pollutes nothing).
+    if (policy === "ask" && hit === "add") return undefined;
+    // /commit bypass: only the flow's own `git commit` is exempt — `add` and
+    // `push` are not.
+    if (commitBypassActive && hit === "commit") {
+      return undefined;
+    }
+
+    if (policy === "never" || policy === "allow") {
+      return {
+        block: true,
+        reason:
+          policy === "never"
+            ? `Commit policy is 'never' (workflow.commitPolicy): \`git ${hit}\` is blocked. ` +
+              "Finish your steps and leave changes uncommitted for user review — the user commits manually or runs /commit. " +
+              `Change the policy with /commit-policy allow.\nCommand: ${cmd}`
+            : `Commit policy is 'allow' with an active plan: a commit is made AUTOMATICALLY after each completed step — do not run \`git ${hit}\` yourself. ` +
+              "Finish the step, mark it done via workflow_todo, and continue; the extension commits it (exactly one commit per step). " +
+              "/commit always works for user-invoked commits.\nCommand: " +
+              cmd,
+      };
+    }
+    // policy === "ask" → confirmation overlay. Headless has no one to ask →
+    // fail closed rather than commit unbidden.
+    const ui = ctx?.ui;
+    if (!ui || !ctx.hasUI) {
+      return {
+        block: true,
+        reason:
+          `Commit policy is 'ask' (workflow.commitPolicy): \`git ${hit}\` needs user approval, ` +
+          "but no interactive UI is available. Leave the change uncommitted and let the user decide.",
+      };
+    }
+    let sel: unknown;
+    try {
+      sel = await ui.select(
+        `Commit policy 'ask': allow \`git ${hit}\`?`,
+        ["Allow once", "Deny"],
+      );
+    } catch {
+      sel = undefined;
+    }
+    if (String(sel ?? "").startsWith("Allow")) return undefined;
+    return {
+      block: true,
+      reason:
+        `Commit policy 'ask': the user declined \`git ${hit}\`. Do not retry — ` +
+        "leave the changes uncommitted for the user.",
+    };
+  }
+
+  /**
+   * Policy-aware commit directive appended to the plan-execute handoff
+   * message. Empty string when the policy cannot be read (a config hiccup
+   * never blocks the handoff itself).
+   */
+  function commitDirectiveLine(ctx: any): string {
+    try {
+      const cwd = ctx?.cwd ?? process.cwd();
+      const mode = readCommitPolicyConfig(cwd, getAgentDir()).config.mode;
+      switch (mode) {
+        case "never":
+          return (
+            "\n\nCommit policy is 'never' (workflow.commitPolicy): do NOT run `git add`, `git commit`, or `git push`. " +
+            "Complete all steps and leave every change uncommitted for user review — the user commits manually or via /commit."
+          );
+        case "ask":
+          return (
+            "\n\nCommit policy is 'ask' (workflow.commitPolicy): you may commit after each completed step " +
+            "(`git add` + `git commit` with a concise conventional message); each `git commit`/`git push` will prompt the user for approval."
+          );
+        case "allow":
+          return (
+            "\n\nCommit policy is 'allow' (workflow.commitPolicy): do NOT run `git add`, `git commit`, or `git push` yourself — " +
+            "after each completed step the extension automatically makes exactly ONE commit containing the changes so far. " +
+            "Just finish a step, mark it done via workflow_todo, and move to the next step."
+          );
+        default:
+          return "";
+      }
+    } catch {
+      return "";
+    }
+  }
+
   // Block edits/writes + bash gating
   pi.on("tool_call", async (event, ctx) => {
     const cwd = (ctx as ExtensionContext).cwd;
@@ -4652,6 +6628,18 @@ export default function workflowExtension(pi: ExtensionAPI) {
         } as any;
       }
     }
+    // ── Commit policy gate ── Independent of the role gate: it also governs
+    // the unrestricted builder role — that is the point (user-controlled
+    // commit behavior). Plan mode is excluded: planner gating already blocks
+    // every mutating git command. Covers bash and powershell so a powershell
+    // wrapper cannot bypass the policy.
+    if (
+      (event.toolName === "bash" || event.toolName === "powershell") &&
+      workflowMode !== "plan"
+    ) {
+      const policyBlock = await commitPolicyGate(event, ctx, cwd);
+      if (policyBlock) return policyBlock as any;
+    }
     if (
       (event.toolName === "edit" || event.toolName === "write") &&
       workflowMode === "plan"
@@ -4735,6 +6723,104 @@ export default function workflowExtension(pi: ExtensionAPI) {
   });
 
   // ── Checkpoint lifecycle: track leaf entryId and prompt header ─
+  // ── Deterministic per-step commit executor (allow mode) ──────────
+
+  /** Mark pre-existing done steps (session resume, re-executed plan) as already accounted for. Called once per session. */
+  function seedCommittedStepRefs(): void {
+    if (stepCommitsSeeded) return;
+    stepCommitsSeeded = true;
+    for (const t of todoItems) {
+      if (!isDone(t) || itemStatus(t) === "cancelled") continue;
+      committedStepRefs.add(todoRef(t));
+    }
+  }
+
+  /** Done steps that have not been committed yet (in canonical order). */
+  function uncommittedDoneSteps(): StepCommitCandidate[] {
+    const out: StepCommitCandidate[] = [];
+    for (const t of todoItems) {
+      if (!isDone(t) || itemStatus(t) === "cancelled") continue;
+      const ref = todoRef(t);
+      if (committedStepRefs.has(ref)) continue;
+      out.push({ ref, step: t.step, label: t.label, text: t.text });
+    }
+    return out;
+  }
+
+  /**
+   * Make the automatic per-step commit when the policy calls for it.
+   * Deterministic: driven by the step-completion signal (workflow_todo
+   * tool_result / [DONE:ref] tags), never by model whimsy; the committed
+   * ref set makes it exactly-once per step. Never throws — a commit hiccup
+   * must not break the run.
+   */
+  async function autoCommitCompletedSteps(
+    ctx: any,
+    trigger: string,
+  ): Promise<void> {
+    try {
+      const cwd = ctx?.cwd ?? process.cwd();
+      if (!isGitRepoSync(cwd)) return;
+      seedCommittedStepRefs();
+      const completed = uncommittedDoneSteps();
+      const dirty = await isDirty(pi as any, cwd);
+      const mode = readCommitPolicyConfig(cwd, getAgentDir()).config.mode;
+      const decision = stepCommitDecision({
+        mode,
+        hasTodos: todoItems.length > 0,
+        dirty,
+        isInRepo: true,
+        completed,
+      });
+      if (!decision.commit) return;
+      const addRes = await piExecGit(["add", "-A"], cwd);
+      if (addRes.exitCode !== 0) {
+        try {
+          ctx?.ui?.notify?.(
+            `Per-step commit failed (git add): ${addRes.stderr.trim()}`,
+            "error",
+          );
+        } catch (_e) {
+          void _e;
+        }
+        return;
+      }
+      const commitRes = await piExecGit(["commit", "-m", decision.message], cwd);
+      if (commitRes.exitCode !== 0) {
+        try {
+          ctx?.ui?.notify?.(
+            `Per-step commit failed: ${commitRes.stderr.trim()}`,
+            "error",
+          );
+        } catch (_e) {
+          void _e;
+        }
+        return;
+      }
+      for (const ref of decision.refs) committedStepRefs.add(ref);
+      try {
+        ctx?.ui?.notify?.(
+          `Committed ${decision.refs.join(", ")} — ${decision.message}`,
+          "info",
+        );
+      } catch (_e) {
+        void _e;
+      }
+      try {
+        pi.appendEntry("workflow-step-commit", {
+          refs: decision.refs,
+          message: decision.message,
+          trigger,
+          at: Date.now(),
+        });
+      } catch (_e) {
+        void _e;
+      }
+    } catch {
+      // never break the agent run on a commit hiccup
+    }
+  }
+
   pi.on("tool_result", async (_event, ctx) => {
     try {
       const leaf =
@@ -4746,8 +6832,30 @@ export default function workflowExtension(pi: ExtensionAPI) {
     }
   });
 
+  // Per-step commit trigger: the runner AWAITS tool_result handlers, so the
+  // commit lands after the step is marked done and BEFORE the model starts
+  // the next step — exactly one commit per step, at the moment of completion.
+  pi.on("tool_result", async (event, ctx) => {
+    try {
+      const ev = event as any;
+      if (ev?.toolName !== "workflow_todo") return;
+      const action = String(ev?.input?.action ?? ev?.details?.action ?? "");
+      if (!action || action === "list" || action === "clear") return;
+      await autoCommitCompletedSteps(ctx, `workflow_todo:${action}`);
+    } catch (_e) {
+      void _e;
+    }
+  });
+
   pi.on("turn_start", async (_event, ctx) => {
     footerInjectedThisTurn = false;
+    // Seed the per-step commit ledger once per session: steps already done
+    // (restored sessions, re-executed plans) never trigger a spurious commit.
+    try {
+      seedCommittedStepRefs();
+    } catch (_e) {
+      void _e;
+    }
     if (!currentEntryId) return;
     const cwd = (ctx as any).cwd as string;
     try {
@@ -4778,6 +6886,9 @@ export default function workflowExtension(pi: ExtensionAPI) {
   });
 
   pi.on("agent_settled", async () => {
+    // Belt-and-braces: the run is over (completed, aborted or errored) — the
+    // /commit bypass must not leak into whatever runs next.
+    commitBypassActive = false;
     // keep persisted CustomEntry for reload, clear in-memory tombstone only on explicit prune; for now no clear to survive fork
   });
 
@@ -4956,10 +7067,24 @@ export default function workflowExtension(pi: ExtensionAPI) {
 
   // Track progress (all modes, whenever todos exist)
   pi.on("turn_end", async (event, ctx) => {
+    // Disarm the /commit bypass as soon as any turn ends: the /commit flow's
+    // `git commit` runs as a tool call WITHIN its turn, so this never disarms
+    // too early — and nothing after the turn inherits the exemption.
+    commitBypassActive = false;
     if (todoItems.length === 0) return;
     if (!isAssistantMessage(event.message as AgentMessage)) return;
     const text = getTextContent(event.message as AssistantMessage);
     const result = markCompletedRefs(text, todoItems);
+    // Fallback per-step commit for steps completed via [DONE:ref] tags in the
+    // response text (the workflow_todo path already committed at its
+    // tool_result; the committed-ref set makes this a no-op then).
+    if (result.marked > 0) {
+      try {
+        await autoCommitCompletedSteps(ctx, "turn_end:done-tags");
+      } catch (_e) {
+        void _e;
+      }
+    }
     if (result.unknown.length > 0 || result.ambiguous.length > 0) {
       lastRefMisses = { refs: [...result.unknown, ...result.ambiguous] };
       try {
@@ -5516,7 +7641,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
           const list = formatTodoNumberedList(todoItems);
           const content = plannotatorActive
             ? `**Plan ready** (${todoItems.length} steps)\\n\\nTo review in browser, ensure SSH port forwarding is active:\\n\`\`\`\\nLocalForward 9999 localhost:9999\\n\`\`\`\\nThen set \`PLANNOTATOR_REMOTE=1\` and \`PLANNOTATOR_PORT=9999\`.\\n\\nOr type "Execute the plan" to build directly.\\n\\nRemaining:\\n${list}`
-            : `**Plan ready** (${todoItems.length} steps)\\n\\n${preview.slice(0, 500)}...\\n\\nRemaining:\\n${list}\\n\\nType "Execute the plan" to build, or tell me what to refine.`;
+            : `**Plan ready** (${todoItems.length} steps)\\n\\n${preview.slice(0, 500)}...\\n\\nRemaining:\\n${list}\\n\\nType "Execute the plan" to build, or tell me what to refine.${commitDirectiveLine(ctx)}`;
           (pi as any).sendMessage?.(
             {
               customType: "workflow-handoff-fallback",
@@ -5932,7 +8057,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
                 display: true,
               };
               const firstTodo = todoItems[0];
-              const execMessage = `Execute the plan.\n\nRemaining steps:\n${remainingList}\n\nStart with: ${firstTodo ? firstTodo.text : todoItems[0].text}\nAfter completing a step, include a [DONE:<ref>] tag in your response (use the numbers shown above).`;
+              const execMessage = `Execute the plan.\n\nRemaining steps:\n${remainingList}\n\nStart with: ${firstTodo ? firstTodo.text : todoItems[0].text}${commitDirectiveLine(ctx)}\nAfter completing a step, include a [DONE:<ref>] tag in your response (use the numbers shown above).`;
               (pi as any).sendMessage?.(planTodoListMessage, {
                 deliverAs: "followUp",
               });