stagent 0.10.0 → 0.11.1

package/src/lib/agents/claude-agent.ts

@@ -15,7 +15,12 @@ import {
 import { getProfile } from "./profiles/registry";
 import { resolveProfileRuntimePayload, type ResolvedProfileRuntimePayload } from "./profiles/compatibility";
 import type { CanUseToolPolicy } from "./profiles/types";
-import { buildClaudeSdkEnv } from "./runtime/claude-sdk";
+import {
+  buildClaudeSdkEnv,
+  CLAUDE_SDK_ALLOWED_TOOLS,
+  CLAUDE_SDK_SETTING_SOURCES,
+} from "./runtime/claude-sdk";
+import { getFeaturesForModel } from "@/lib/chat/types";
 import { getActiveLearnedContext } from "./learned-context";
 import { getLaunchCwd, getWorkspaceContext } from "@/lib/environment/workspace-context";
 import { analyzeForLearnedPatterns } from "./pattern-extractor";
@@ -34,6 +39,11 @@ import {
   handleToolPermission,
   clearPermissionCache,
 } from "./tool-permissions";
+import {
+  classifyTaskFailureReason,
+  toRetryableRuntimeLaunchError,
+  type RuntimeLaunchProgress,
+} from "@/lib/agents/runtime/launch-failure";
 
 // ─── Stagent MCP injection helpers ──────────────────────────────────────
 //
@@ -75,43 +85,33 @@ async function withStagentMcpServer(
 
 /**
  * Prepend `mcp__stagent__*` to a profile's explicit allowedTools so the
- * stagent tool registration survives the SDK preset filter. Returns
- * `undefined` when the profile has no allowedTools — callers should spread
- * the result conditionally so the SDK falls through to preset defaults in
- * that case.
+ * stagent tool registration survives the SDK preset filter. When the
+ * profile has no explicit allowlist and `includeSdkTools` is true, fall
+ * back to Phase 1a's CLAUDE_SDK_ALLOWED_TOOLS (Skill, Read/Grep/Glob,
+ * Edit/Write/Bash, TodoWrite) so task execution gets the same toolset as
+ * chat. Returns `undefined` only when the profile has no allowlist AND
+ * the caller does not want SDK tools added — letting the SDK fall
+ * through to claude_code preset defaults.
  */
 function withStagentAllowedTools(
   profileAllowedTools: string[] | undefined,
+  includeSdkTools: boolean,
 ): string[] | undefined {
-  if (!profileAllowedTools) return undefined;
-  return Array.from(new Set(["mcp__stagent__*", ...profileAllowedTools]));
-}
-
-/**
- * Classify an error into a machine-readable failure reason string.
- * Used by writeTerminalFailureReason and handleExecutionError.
- */
-function classifyError(error: unknown): string {
-  if (!(error instanceof Error)) return "sdk_error";
-  if (error.name === "AbortError" || error.message.includes("aborted")) {
-    return "aborted";
-  }
-  const lower = error.message.toLowerCase();
-  if (
-    lower.includes("turn") &&
-    (lower.includes("limit") || lower.includes("exhausted") || lower.includes("max"))
-  ) {
-    return "turn_limit_exceeded";
+  // An empty `allowedTools: []` is treated the same as `undefined` — an
+  // empty array is almost never the profile author's intent (they'd get
+  // only `mcp__stagent__*` and nothing else). Require at least one tool
+  // name for the "profile has explicit list" branch.
+  if (profileAllowedTools && profileAllowedTools.length > 0) {
+    // Profile has explicit list — respect it. Only prepend stagent.
+    return Array.from(new Set(["mcp__stagent__*", ...profileAllowedTools]));
   }
-  if (lower.includes("timeout") || lower.includes("timed out")) return "timeout";
-  if (lower.includes("budget")) return "budget_exceeded";
-  if (lower.includes("authentication") || lower.includes("oauth")) {
-    return "auth_failed";
+  if (includeSdkTools) {
+    // No profile allowlist but runtime has native skills — pass the
+    // Phase 1a tool set alongside mcp__stagent__* + browser/external
+    // (callers merge their own browser/external patterns into this list).
+    return ["mcp__stagent__*", ...CLAUDE_SDK_ALLOWED_TOOLS];
   }
-  if (lower.includes("rate limit") || lower.includes("429")) {
-    return "rate_limited";
-  }
-  return "sdk_error";
+  return undefined;
 }
 
 /**
@@ -124,7 +124,7 @@ export async function writeTerminalFailureReason(
   taskId: string,
   error: unknown,
 ): Promise<void> {
-  const reason = classifyError(error);
+  const reason = classifyTaskFailureReason(error);
   await db
     .update(tasks)
     .set({ failureReason: reason, updatedAt: new Date() })
@@ -200,6 +200,14 @@ export async function finalizeTaskUsage(
     startedAt: state.startedAt,
     finishedAt: new Date(),
   });
+
+  await db
+    .update(tasks)
+    .set({
+      effectiveModelId: state.modelId ?? null,
+      updatedAt: new Date(),
+    })
+    .where(eq(tasks.id, state.taskId));
 }
 
 /**
@@ -212,7 +220,8 @@ async function processAgentStream(
   response: AsyncIterable<Record<string, unknown>>,
   abortController: AbortController,
   agentProfileId = "general",
-  usageState: TaskUsageState
+  usageState: TaskUsageState,
+  launchProgress?: RuntimeLaunchProgress
 ): Promise<void> {
   let sessionId: string | null = null;
   let receivedResult = false;
@@ -275,8 +284,14 @@ async function processAgentStream(
     // Handle assistant messages (tool use starts)
     if (message.type === "assistant" && message.message?.content) {
       turnCount++;
+      if (launchProgress) {
+        launchProgress.hasTurnStarted = true;
+      }
       for (const block of message.message.content) {
         if (block.type === "tool_use") {
+          if (launchProgress) {
+            launchProgress.hasToolUse = true;
+          }
           // Track screenshot tool_use IDs for result interception
           const toolBlock = block as { type: string; id?: string; name?: string; input?: unknown };
           if (typeof toolBlock.name === "string" && SCREENSHOT_TOOL_NAMES.has(toolBlock.name) && typeof toolBlock.id === "string") {
@@ -345,6 +360,9 @@ async function processAgentStream(
         return;
       }
       receivedResult = true;
+      if (launchProgress) {
+        launchProgress.hasResult = true;
+      }
       const resultText =
         typeof message.result === "string"
           ? message.result
@@ -516,6 +534,7 @@ export async function executeClaudeTask(taskId: string): Promise<void> {
   const [task] = await db.select().from(tasks).where(eq(tasks.id, taskId));
   if (!task) throw new Error(`Task ${taskId} not found`);
   const usageState = createTaskUsageState(task);
+  const launchProgress: RuntimeLaunchProgress = {};
 
   const abortController = new AbortController();
   const agentProfileId = task.agentProfile ?? "general";
@@ -550,11 +569,25 @@ export async function executeClaudeTask(taskId: string): Promise<void> {
       externalServers,
       task.projectId,
     );
-    // allowedTools prepended via shared helper (see withStagentAllowedTools).
-    // Computed once so the conditional spread below does not invoke the
-    // helper twice. Returns undefined when the profile has no allowlist so
-    // the SDK falls through to claude_code preset defaults.
-    const mergedAllowedTools = withStagentAllowedTools(ctx.payload?.allowedTools);
+    // Capability gate: only pass settingSources + CLAUDE_SDK tools when the
+    // runtime is claude-code (or a future runtime with hasNativeSkills).
+    // Anthropic-direct and OpenAI-direct task runtimes don't understand
+    // these SDK-specific options. Tasks do not carry a model field yet —
+    // an empty string falls through to the claude-code default in
+    // getFeaturesForModel, so the gate opens by default for the primary
+    // claude-code use case. Task 4's resume path follows the same pattern.
+    const runtimeFeatures = getFeaturesForModel("");
+    const includeSdkNativeTools = runtimeFeatures.hasNativeSkills;
+
+    // allowedTools merged via shared helper. When the profile has no explicit
+    // allowlist AND the runtime has native skills, we fall back to Phase 1a's
+    // CLAUDE_SDK_ALLOWED_TOOLS (Skill, Read/Grep/Glob, Edit/Write/Bash,
+    // TodoWrite) so task execution matches chat. Computed once so the
+    // conditional spread below does not invoke the helper twice.
+    const mergedAllowedTools = withStagentAllowedTools(
+      ctx.payload?.allowedTools,
+      includeSdkNativeTools,
+    );
 
     const authEnv = await getAuthEnv();
     const response = query({
@@ -573,6 +606,11 @@ export async function executeClaudeTask(taskId: string): Promise<void> {
         // F4: Per-execution budget cap — use task-specific override if set
         maxBudgetUsd: task.maxBudgetUsd ?? DEFAULT_MAX_BUDGET_USD,
         ...(mergedAllowedTools && { allowedTools: mergedAllowedTools }),
+        // Phase 1a parity: load user + project settings (.claude/skills,
+        // CLAUDE.md, .claude/rules/*.md) when the runtime supports it.
+        ...(includeSdkNativeTools && {
+          settingSources: [...CLAUDE_SDK_SETTING_SOURCES],
+        }),
         ...(Object.keys(mergedMcpServers).length > 0 && {
           mcpServers: mergedMcpServers,
         }),
@@ -592,7 +630,8 @@ export async function executeClaudeTask(taskId: string): Promise<void> {
       response as AsyncIterable<Record<string, unknown>>,
       abortController,
       agentProfileId,
-      usageState
+      usageState,
+      launchProgress
     );
 
     try {
@@ -601,6 +640,14 @@ export async function executeClaudeTask(taskId: string): Promise<void> {
       console.error("[self-improvement] pattern extraction failed:", err);
     }
   } catch (error: unknown) {
+    const retryableLaunchError = toRetryableRuntimeLaunchError({
+      runtimeId: "claude-code",
+      error,
+      progress: launchProgress,
+    });
+    if (retryableLaunchError) {
+      throw retryableLaunchError;
+    }
     await handleExecutionError(
       taskId,
       task.title,
@@ -680,10 +727,19 @@ export async function resumeClaudeTask(taskId: string): Promise<void> {
       externalServers,
       task.projectId,
     );
-    // allowedTools prepended via shared helper (see withStagentAllowedTools).
-    // Computed once so the conditional spread below does not invoke the
-    // helper twice.
-    const mergedAllowedTools = withStagentAllowedTools(ctx.payload?.allowedTools);
+    // Capability gate: same logic as executeClaudeTask. Resumed tasks must
+    // get the same SDK options as their original run so skills that were
+    // visible on first execution remain visible after a resume. `task.model`
+    // does not exist on the tasks schema — pass "" which resolves to the
+    // claude-code default (hasNativeSkills: true) for every current task
+    // flow. See features/task-runtime-skill-parity.md Task 4.
+    const runtimeFeatures = getFeaturesForModel("");
+    const includeSdkNativeTools = runtimeFeatures.hasNativeSkills;
+
+    const mergedAllowedTools = withStagentAllowedTools(
+      ctx.payload?.allowedTools,
+      includeSdkNativeTools,
+    );
 
     const authEnv = await getAuthEnv();
     const response = query({
@@ -703,6 +759,10 @@ export async function resumeClaudeTask(taskId: string): Promise<void> {
         // F4: Per-execution budget cap — use task-specific override if set
         maxBudgetUsd: task.maxBudgetUsd ?? DEFAULT_MAX_BUDGET_USD,
         ...(mergedAllowedTools && { allowedTools: mergedAllowedTools }),
+        // Phase 1a parity: match executeClaudeTask — see Task 3 rationale.
+        ...(includeSdkNativeTools && {
+          settingSources: [...CLAUDE_SDK_SETTING_SOURCES],
+        }),
         ...(Object.keys(mergedMcpServers).length > 0 && {
           mcpServers: mergedMcpServers,
         }),
@@ -801,8 +861,7 @@ async function handleExecutionError(
     return;
   }
 
-  const failureReason = classifyError(error);
-
+  const failureReason = classifyTaskFailureReason(error);
   await db
     .update(tasks)
     .set({

package/src/lib/agents/handoff/bus.ts

@@ -125,8 +125,8 @@ export async function processHandoffs(): Promise<void> {
 
     // Fire-and-forget task execution
     try {
-      const { executeTaskWithRuntime } = await import("@/lib/agents/runtime");
-      executeTaskWithRuntime(taskId).catch((err) => {
+      const { startTaskExecution } = await import("@/lib/agents/task-dispatch");
+      startTaskExecution(taskId).catch((err) => {
         console.error(`[handoff] task execution failed for message ${msg.id}:`, err);
       });
     } catch (err) {

package/src/lib/agents/profiles/__tests__/list-fused-profiles.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { listFusedProfiles } from "@/lib/agents/profiles/list-fused-profiles";
+
+describe("listFusedProfiles", () => {
+  let projectDir: string;
+  let userSkillsDir: string;
+
+  beforeEach(() => {
+    projectDir = mkdtempSync(join(tmpdir(), "stagent-skills-"));
+    userSkillsDir = mkdtempSync(join(tmpdir(), "stagent-user-skills-"));
+    mkdirSync(join(projectDir, ".claude", "skills"), { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(projectDir, { recursive: true, force: true });
+    rmSync(userSkillsDir, { recursive: true, force: true });
+  });
+
+  function writeSkill(baseDir: string, name: string, frontmatter: string) {
+    mkdirSync(join(baseDir, name), { recursive: true });
+    writeFileSync(
+      join(baseDir, name, "SKILL.md"),
+      `---\n${frontmatter}\n---\n\nbody for ${name}\n`
+    );
+  }
+
+  it("returns registry profiles when no filesystem skills exist", async () => {
+    const result = await listFusedProfiles(projectDir, userSkillsDir);
+    // Should contain at least one registry profile (builtin)
+    expect(result.length).toBeGreaterThan(0);
+    expect(result.every((p) => typeof p.id === "string")).toBe(true);
+  });
+
+  it("surfaces a project .claude/skills/<name> entry", async () => {
+    writeSkill(
+      join(projectDir, ".claude", "skills"),
+      "my-project-skill",
+      `name: my-project-skill\ndescription: Test project skill`
+    );
+    const result = await listFusedProfiles(projectDir, userSkillsDir);
+    expect(result.some((p) => p.id === "my-project-skill")).toBe(true);
+    const skill = result.find((p) => p.id === "my-project-skill")!;
+    expect(skill.name).toBe("my-project-skill");
+    expect(skill.description).toBe("Test project skill");
+    expect(skill.origin).toBe("filesystem-project");
+  });
+
+  it("sets projectDir to the project root (not the skills subdirectory) on filesystem-project entries", async () => {
+    writeSkill(
+      join(projectDir, ".claude", "skills"),
+      "my-scoped-skill",
+      `name: my-scoped-skill\ndescription: Scoped`
+    );
+    const result = await listFusedProfiles(projectDir, userSkillsDir);
+    const skill = result.find((p) => p.id === "my-scoped-skill")!;
+    expect(skill.projectDir).toBe(projectDir);
+    // Negative: must not be the .claude/skills subdirectory
+    expect(skill.projectDir).not.toContain(".claude/skills");
+  });
+
+  it("surfaces a user ~/.claude/skills/<name> entry", async () => {
+    writeSkill(
+      userSkillsDir,
+      "my-user-skill",
+      `name: my-user-skill\ndescription: Test user skill`
+    );
+    const result = await listFusedProfiles(projectDir, userSkillsDir);
+    expect(result.some((p) => p.id === "my-user-skill")).toBe(true);
+    expect(
+      result.find((p) => p.id === "my-user-skill")!.origin
+    ).toBe("filesystem-user");
+  });
+
+  it("dedupes by id — registry profile wins over filesystem skill with same id", async () => {
+    // "general" is a known builtin registry profile id; write a filesystem
+    // skill with the same id to force a collision.
+    writeSkill(
+      join(projectDir, ".claude", "skills"),
+      "general",
+      `name: general\ndescription: This should be overridden by registry`
+    );
+    const result = await listFusedProfiles(projectDir, userSkillsDir);
+    const entries = result.filter((p) => p.id === "general");
+    expect(entries).toHaveLength(1);
+    // Registry description should win (not the filesystem-overridden one)
+    expect(entries[0].description).not.toBe("This should be overridden by registry");
+  });
+
+  it("logs and skips a malformed SKILL.md (no name field in frontmatter)", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    writeSkill(
+      join(projectDir, ".claude", "skills"),
+      "broken-skill",
+      `description: Missing name field — broken`
+    );
+    const result = await listFusedProfiles(projectDir, userSkillsDir);
+    expect(result.some((p) => p.id === "broken-skill")).toBe(false);
+    expect(warnSpy).toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+
+  it("returns an empty-safe result when projectDir does not exist", async () => {
+    const result = await listFusedProfiles("/nonexistent/path", userSkillsDir);
+    // Should still return registry + user skills, no throw
+    expect(Array.isArray(result)).toBe(true);
+  });
+});

package/src/lib/agents/profiles/__tests__/registry.test.ts

@@ -98,6 +98,53 @@ describe("profile registry", () => {
     expect(codeReviewer!.canUseToolPolicy!.autoApprove).toContain("Grep");
   });
 
+  it("preserves preferredRuntime from profile.yaml", async () => {
+    const originalHome = process.env.HOME;
+    const tempHome = fs.mkdtempSync(
+      path.join(os.tmpdir(), "registry-preferred-runtime-")
+    );
+
+    try {
+      process.env.HOME = tempHome;
+      vi.resetModules();
+
+      const profileId = `preferred-runtime-${Date.now()}`;
+      const profileDir = path.join(tempHome, ".claude", "skills", profileId);
+      fs.mkdirSync(profileDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(profileDir, "profile.yaml"),
+        yaml.dump({
+          id: profileId,
+          name: "Preferred Runtime Test",
+          version: "1.0.0",
+          domain: "work",
+          tags: ["runtime"],
+          preferredRuntime: "openai-direct",
+        })
+      );
+      fs.writeFileSync(
+        path.join(profileDir, "SKILL.md"),
+        `---
+name: ${profileId}
+description: Preferred runtime test profile.
+---
+
+Testing preferred runtime loading.
+`
+      );
+
+      const registry = await import("../registry");
+      const loaded = registry.getProfile(profileId);
+
+      expect(loaded).toBeDefined();
+      expect(loaded?.preferredRuntime).toBe("openai-direct");
+    } finally {
+      process.env.HOME = originalHome;
+      fs.rmSync(tempHome, { recursive: true, force: true });
+      vi.resetModules();
+    }
+  });
+
   it("getProfileTags returns tag map", () => {
     const tagMap = getProfileTags();
     expect(tagMap.get("researcher")).toContain("research");

package/src/lib/agents/profiles/builtins/upgrade-assistant/SKILL.md

@@ -12,9 +12,36 @@ You are the Upgrade Assistant for a stagent clone. Your job is to pull upstream
 - **Data directory:** `{{DATA_DIR}}`
 - **Working directory:** the current repo root
 
+## How to ask the user a question
+
+**Never emit a question as plain text in the log.** The session UI cannot turn text into a reply input. Always invoke the `AskUserQuestion` tool — the user sees a structured prompt in the task view and the tool call returns with their answer so you can continue.
+
+Two canonical shapes:
+
+- **Free-form answer** (for "should I…" questions that don't have a fixed choice set):
+  ```
+  AskUserQuestion({ question: "Your main branch has 3 commits not in origin/main. Move them to `local` and reset main, or abort so you can review?" })
+  ```
+  The user types a reply and the tool returns `{ answer: "..."}`. Act on it.
+
+- **Choice-based answer** (for merge-conflict resolution — always three canonical choices):
+  ```
+  AskUserQuestion({
+    question: "Conflict in src/app/page.tsx — which version do you want?",
+    options: [
+      { label: "Keep my version",     description: "Use your changes; discard main's version" },
+      { label: "Take main's version", description: "Use main's changes; discard yours" },
+      { label: "Show me the diff",    description: "Output the full conflict diff for manual review" }
+    ]
+  })
+  ```
+  The tool returns `{ answer: "Keep my version" }` (or one of the other labels). Run the matching `git checkout --ours` / `--theirs` / `git diff` command and continue.
+
+If the answer is free-form prose, read it literally. Do not second-guess the user.
+
 ## Crucial rules — read these before doing anything
 
-1. **Never modify `main` except by fast-forward.** After fetching, merge `origin/main` into local `main` with `--ff-only`. If that fast-forward fails, it means the user has local commits on `main` that aren't in `origin/main` — **stop and ask the user** whether to move them to `{{INSTANCE_BRANCH}}` or abort so they can review. Do not auto-resolve.
+1. **Never modify `main` except by fast-forward.** After fetching, merge `origin/main` into local `main` with `--ff-only`. If that fast-forward fails, the user has local commits on `main` that aren't in `origin/main` — **invoke `AskUserQuestion`** asking whether to move them to `{{INSTANCE_BRANCH}}` or abort so they can review. Do not auto-resolve.
 
 2. **Never push any branch.** The pre-push hook blocks `{{INSTANCE_BRANCH}}` pushes, but you should not even attempt one. Your job ends at a local commit.
 
@@ -22,10 +49,10 @@ You are the Upgrade Assistant for a stagent clone. Your job is to pull upstream
 
 4. **Treat `local` identically to any named instance branch.** Users with a default single-clone setup have `{{INSTANCE_BRANCH}}=local`. Users running private domain clones have names like `wealth-mgr` or `investor-mgr`. The merge flow is identical in both cases.
 
-5. **Stop and ask the user on merge conflicts.** Do not guess. For each conflict, use the three canonical choices:
+5. **Stop and ask on merge conflicts — always via `AskUserQuestion`.** Do not guess and do not emit the question as plain text. For each conflicted file, invoke `AskUserQuestion` with the three-choice payload shown above in "How to ask the user a question". Map the returned `answer` to the git command:
    - **"Keep my version"** → `git checkout --ours <file>`
    - **"Take main's version"** → `git checkout --theirs <file>`
-   - **"Show me the diff"** → `git diff <file>` and output the full conflict for manual review
+   - **"Show me the diff"** → `git diff <file>` and output the full conflict; then re-invoke `AskUserQuestion` so the user can pick one of the first two options after reviewing.
    After all conflicts are resolved, `git add` the files and continue the merge.
 
 ## Standard merge flow

package/src/lib/agents/profiles/builtins/upgrade-assistant/profile.yaml

@@ -3,8 +3,8 @@ name: Upgrade Assistant
 version: "1.0.0"
 domain: work
 tags: [upgrade, git, merge, maintenance, instance]
-supportedRuntimes: [claude-code, anthropic-direct]
-preferredRuntime: anthropic-direct
+supportedRuntimes: [claude-code, openai-codex-app-server]
+preferredRuntime: claude-code
 
 maxTurns: 40
 
@@ -30,3 +30,7 @@ allowedTools:
   - Bash(npm install)
   - Read
   - Write
+  # Used for every decision point (merge conflicts, drifted main, etc.) —
+  # the agent must NEVER emit a question as plain text; always invoke this
+  # tool so the user can answer through the session UI.
+  - AskUserQuestion

package/src/lib/agents/profiles/list-fused-profiles.ts

@@ -0,0 +1,104 @@
+import { readdirSync, readFileSync, statSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { listProfiles } from "./registry";
+import type { AgentProfile } from "./types";
+
+/**
+ * Minimal YAML frontmatter parser — handles the `---\nkey: value\n---\n...`
+ * pattern used by SKILL.md files. Returns null if no frontmatter or no `name`.
+ */
+function parseFrontmatter(content: string): Record<string, string> | null {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  const result: Record<string, string> = {};
+  for (const line of match[1].split("\n")) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const value = line.slice(colonIdx + 1).trim();
+    if (key) result[key] = value;
+  }
+  return result;
+}
+
+function loadFilesystemSkills(
+  skillsDir: string,
+  origin: "filesystem-project" | "filesystem-user",
+  projectRootDir: string | undefined
+): AgentProfile[] {
+  if (!existsSync(skillsDir)) return [];
+  const profiles: AgentProfile[] = [];
+  for (const entry of readdirSync(skillsDir)) {
+    const skillPath = join(skillsDir, entry);
+    try {
+      if (!statSync(skillPath).isDirectory()) continue;
+      const skillMdPath = join(skillPath, "SKILL.md");
+      if (!existsSync(skillMdPath)) continue;
+      const content = readFileSync(skillMdPath, "utf8");
+      const fm = parseFrontmatter(content);
+      if (!fm || !fm.name) {
+        console.warn(
+          `[listFusedProfiles] skipping ${skillMdPath}: missing name in frontmatter`
+        );
+        continue;
+      }
+      profiles.push({
+        id: fm.name,
+        name: fm.name,
+        description: fm.description ?? "",
+        domain: "skill",
+        tags: [],
+        systemPrompt: content,
+        skillMd: content,
+        allowedTools: [],
+        mcpServers: {},
+        supportedRuntimes: ["claude-code"],
+        origin,
+        scope: origin === "filesystem-project" ? "project" : "user",
+        readOnly: true,
+        projectDir: origin === "filesystem-project" ? projectRootDir : undefined,
+      } as AgentProfile);
+    } catch (err) {
+      console.warn(
+        `[listFusedProfiles] failed to load skill at ${skillPath}:`,
+        (err as Error).message
+      );
+    }
+  }
+  return profiles;
+}
+
+/**
+ * Lists every agent profile reachable from this Stagent instance, merging
+ * registry profiles with filesystem skills ("fused" view):
+ *   1. Registry profiles (builtins + user registry)
+ *   2. User filesystem skills at `~/.claude/skills/*\/SKILL.md` (or `userSkillsDir` override)
+ *   3. Project filesystem skills at `<projectDir>/.claude/skills/*\/SKILL.md`
+ * Dedupes by id — registry profiles win on collision (they're curated), then
+ * user skills win over project skills.
+ *
+ * @param projectDir Absolute path to the active project's working directory (project root)
+ * @param userSkillsDir Override for user skills dir (tests); defaults to `~/.claude/skills`
+ */
+export async function listFusedProfiles(
+  projectDir: string | null | undefined,
+  userSkillsDir: string = join(homedir(), ".claude", "skills")
+): Promise<AgentProfile[]> {
+  const registry = listProfiles();
+  const registryIds = new Set(registry.map((p) => p.id));
+
+  const userSkills = loadFilesystemSkills(userSkillsDir, "filesystem-user", undefined).filter(
+    (p) => !registryIds.has(p.id)
+  );
+
+  const projectSkills = projectDir
+    ? loadFilesystemSkills(
+        join(projectDir, ".claude", "skills"),
+        "filesystem-project",
+        projectDir
+      ).filter((p) => !registryIds.has(p.id) && !userSkills.some((u) => u.id === p.id))
+    : [];
+
+  return [...registry, ...userSkills, ...projectSkills];
+}