stagent 0.9.5 → 0.10.0

package/src/lib/agents/__tests__/pattern-extractor.test.ts

@@ -73,10 +73,16 @@ const {
   mockRunMetaCompletion,
   mockGetActiveLearnedContext,
   mockProposeContextAddition,
+  mockGetTaskWorkflowId,
+  mockHasLearningSession,
+  mockBufferProposal,
 } = vi.hoisted(() => ({
   mockRunMetaCompletion: vi.fn(),
   mockGetActiveLearnedContext: vi.fn().mockReturnValue(null),
   mockProposeContextAddition: vi.fn().mockResolvedValue("notif-123"),
+  mockGetTaskWorkflowId: vi.fn().mockReturnValue(null),
+  mockHasLearningSession: vi.fn().mockReturnValue(false),
+  mockBufferProposal: vi.fn(),
 }));
 
 vi.mock("../runtime/claude", () => ({
@@ -87,6 +93,11 @@ vi.mock("../learned-context", () => ({
   getActiveLearnedContext: mockGetActiveLearnedContext,
   proposeContextAddition: mockProposeContextAddition,
 }));
+vi.mock("../learning-session", () => ({
+  getTaskWorkflowId: mockGetTaskWorkflowId,
+  hasLearningSession: mockHasLearningSession,
+  bufferProposal: mockBufferProposal,
+}));
 
 import { analyzeForLearnedPatterns } from "../pattern-extractor";
 
@@ -103,6 +114,9 @@ beforeEach(() => {
   mockValues.mockResolvedValue(undefined);
   mockGetActiveLearnedContext.mockReturnValue(null);
   mockProposeContextAddition.mockResolvedValue("notif-123");
+  mockGetTaskWorkflowId.mockReturnValue(null);
+  mockHasLearningSession.mockReturnValue(false);
+  mockBufferProposal.mockReset();
 });
 
 // ═════════════════════════════════════════════════════════════════════
@@ -240,4 +254,38 @@ describe("analyzeForLearnedPatterns", () => {
     expect(additions).toContain("Description A");
     expect(additions).toContain("Description B");
   });
+
+  it("buffers workflow proposals into the active learning session", async () => {
+    mockWhere.mockResolvedValueOnce([
+      { title: "Task", description: "Desc", result: "Done" },
+    ]);
+    mockLimit.mockResolvedValueOnce([]);
+    mockRunMetaCompletion.mockResolvedValue({
+      text: JSON.stringify([
+        {
+          title: "Pattern A",
+          description: "Description A",
+          category: "best_practice",
+        },
+      ]),
+      usage: {},
+    });
+    mockGetTaskWorkflowId.mockReturnValue("workflow-1");
+    mockHasLearningSession.mockReturnValue(true);
+    mockProposeContextAddition.mockResolvedValue("proposal-row-1");
+
+    const result = await analyzeForLearnedPatterns("task-1", "general");
+
+    expect(result).toBe("proposal-row-1");
+    expect(mockProposeContextAddition).toHaveBeenCalledWith(
+      "general",
+      "task-1",
+      expect.stringContaining("Pattern A"),
+      { silent: true }
+    );
+    expect(mockBufferProposal).toHaveBeenCalledWith(
+      "workflow-1",
+      "proposal-row-1"
+    );
+  });
 });

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

@@ -35,6 +35,102 @@ import {
   clearPermissionCache,
 } from "./tool-permissions";
 
+// ─── Stagent MCP injection helpers ──────────────────────────────────────
+//
+// Shared by executeClaudeTask and resumeClaudeTask so the two runtime entry
+// points cannot drift apart. The drift between chat engine injection and
+// claude-code runtime injection is what produced the P0 bug this feature
+// fixes — do not duplicate these patterns inline.
+
+/**
+ * Merge the in-process stagent MCP server into a profile/browser/external
+ * MCP server map. Stagent is spread LAST so no upstream source can shadow
+ * the `stagent` key with its own server.
+ *
+ * `@/lib/chat/stagent-tools` is loaded via dynamic `import()` to avoid a
+ * circular-dependency crash: that module transitively pulls in the chat
+ * tools registry, which imports the runtime registry (`runtime/catalog`,
+ * `runtime/index`), which statically references `claudeRuntimeAdapter` —
+ * the very module this file is defined in. A static import here would
+ * crash with "Cannot access 'claudeRuntimeAdapter' before initialization"
+ * at module-load time. The dynamic import defers the stagent-tools module
+ * until `executeClaudeTask` / `resumeClaudeTask` actually run, by which
+ * time every module in the graph has finished initializing.
+ */
+async function withStagentMcpServer(
+  profileServers: Record<string, unknown>,
+  browserServers: Record<string, unknown>,
+  externalServers: Record<string, unknown>,
+  projectId?: string | null,
+): Promise<Record<string, unknown>> {
+  const { createToolServer } = await import("@/lib/chat/stagent-tools");
+  const stagentServer = createToolServer(projectId).asMcpServer();
+  return {
+    ...profileServers,
+    ...browserServers,
+    ...externalServers,
+    stagent: stagentServer,
+  };
+}
+
+/**
+ * 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.
+ */
+function withStagentAllowedTools(
+  profileAllowedTools: string[] | undefined,
+): 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";
+  }
+  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 (lower.includes("rate limit") || lower.includes("429")) {
+    return "rate_limited";
+  }
+  return "sdk_error";
+}
+
+/**
+ * Write an explicit failure_reason to tasks at terminal-state transitions.
+ * Called from handleExecutionError and the execute/resume functions on known
+ * error classes. Prefer this over reverse-engineering reasons from text via
+ * detectFailureReason in scheduler.ts, which is fragile to SDK message changes.
+ */
+export async function writeTerminalFailureReason(
+  taskId: string,
+  error: unknown,
+): Promise<void> {
+  const reason = classifyError(error);
+  await db
+    .update(tasks)
+    .set({ failureReason: reason, updatedAt: new Date() })
+    .where(eq(tasks.id, taskId));
+}
+
 /** Typed representation of messages from the Agent SDK stream */
 interface AgentStreamMessage {
   type?: string;
@@ -314,11 +410,14 @@ async function processAgentStream(
       ? `Agent exhausted its turn limit (${turnCount} turns used) without producing a final result. The task may need fewer sub-queries or a higher maxTurns setting.`
       : "Agent stream ended without producing a result";
 
+    const streamFailureReason = turnCount > 0 ? "turn_limit_exceeded" : "sdk_error";
+
     await db
       .update(tasks)
       .set({
         status: "failed",
         result: errorDetail,
+        failureReason: streamFailureReason,
         updatedAt: new Date(),
       })
       .where(eq(tasks.id, taskId));
@@ -432,13 +531,30 @@ export async function executeClaudeTask(taskId: string): Promise<void> {
     await prepareTaskOutputDirectory(taskId, { clearExisting: true });
     const ctx = await buildTaskQueryContext(task, agentProfileId);
 
-    // Merge browser + external MCP servers when enabled globally
+    // Per-schedule override: if the task carries its own maxTurns (set by
+    // fireSchedule from schedules.maxTurns), it takes precedence over the
+    // profile default. This is the runtime-enforced budget cap.
+    const effectiveMaxTurns = task.maxTurns ?? ctx.maxTurns;
+
+    // Merge browser + external MCP servers, then inject the in-process
+    // stagent server via the shared helper (see withStagentMcpServer above).
+    // The helper is async because it dynamically imports @/lib/chat/stagent-tools
+    // to break a module-load cycle with the runtime registry.
     const [browserServers, externalServers] = await Promise.all([
       getBrowserMcpServers(),
       getExternalMcpServers(),
     ]);
-    const profileMcpServers = ctx.payload?.mcpServers ?? {};
-    const mergedMcpServers = { ...profileMcpServers, ...browserServers, ...externalServers };
+    const mergedMcpServers = await withStagentMcpServer(
+      ctx.payload?.mcpServers ?? {},
+      browserServers,
+      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);
 
     const authEnv = await getAuthEnv();
     const response = query({
@@ -452,11 +568,11 @@ export async function executeClaudeTask(taskId: string): Promise<void> {
         systemPrompt: ctx.systemInstructions
           ? { type: "preset" as const, preset: "claude_code" as const, append: ctx.systemInstructions }
           : { type: "preset" as const, preset: "claude_code" as const },
-        // F9: Bounded turn limit from profile or default
-        maxTurns: ctx.maxTurns,
+        // F9: Bounded turn limit from profile or default; per-schedule override wins
+        maxTurns: effectiveMaxTurns,
         // F4: Per-execution budget cap — use task-specific override if set
         maxBudgetUsd: task.maxBudgetUsd ?? DEFAULT_MAX_BUDGET_USD,
-        ...(ctx.payload?.allowedTools && { allowedTools: ctx.payload.allowedTools }),
+        ...(mergedAllowedTools && { allowedTools: mergedAllowedTools }),
         ...(Object.keys(mergedMcpServers).length > 0 && {
           mcpServers: mergedMcpServers,
         }),
@@ -479,10 +595,11 @@ export async function executeClaudeTask(taskId: string): Promise<void> {
       usageState
     );
 
-    // Fire-and-forget pattern extraction for self-improvement
-    analyzeForLearnedPatterns(taskId, agentProfileId).catch((err) => {
+    try {
+      await analyzeForLearnedPatterns(taskId, agentProfileId);
+    } catch (err) {
       console.error("[self-improvement] pattern extraction failed:", err);
-    });
+    }
   } catch (error: unknown) {
     await handleExecutionError(
       taskId,
@@ -545,13 +662,28 @@ export async function resumeClaudeTask(taskId: string): Promise<void> {
     await prepareTaskOutputDirectory(taskId);
     const ctx = await buildTaskQueryContext(task, profileId);
 
-    // Merge browser + external MCP servers when enabled globally
+    // Per-schedule override: if the task carries its own maxTurns (set by
+    // fireSchedule from schedules.maxTurns), it takes precedence over the
+    // profile default. This is the runtime-enforced budget cap.
+    const effectiveMaxTurns = task.maxTurns ?? ctx.maxTurns;
+
+    // Merge browser + external MCP servers, then inject the in-process
+    // stagent server via the shared helper (see withStagentMcpServer).
+    // Async for the same cycle-breaking reason as executeClaudeTask above.
     const [browserServers, externalServers] = await Promise.all([
       getBrowserMcpServers(),
       getExternalMcpServers(),
     ]);
-    const profileMcpServers = ctx.payload?.mcpServers ?? {};
-    const mergedMcpServers = { ...profileMcpServers, ...browserServers, ...externalServers };
+    const mergedMcpServers = await withStagentMcpServer(
+      ctx.payload?.mcpServers ?? {},
+      browserServers,
+      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);
 
     const authEnv = await getAuthEnv();
     const response = query({
@@ -566,11 +698,11 @@ export async function resumeClaudeTask(taskId: string): Promise<void> {
         systemPrompt: ctx.systemInstructions
           ? { type: "preset" as const, preset: "claude_code" as const, append: ctx.systemInstructions }
           : { type: "preset" as const, preset: "claude_code" as const },
-        // F9: Bounded turn limit from profile or default
-        maxTurns: ctx.maxTurns,
+        // F9: Bounded turn limit from profile or default; per-schedule override wins
+        maxTurns: effectiveMaxTurns,
         // F4: Per-execution budget cap — use task-specific override if set
         maxBudgetUsd: task.maxBudgetUsd ?? DEFAULT_MAX_BUDGET_USD,
-        ...(ctx.payload?.allowedTools && { allowedTools: ctx.payload.allowedTools }),
+        ...(mergedAllowedTools && { allowedTools: mergedAllowedTools }),
         ...(Object.keys(mergedMcpServers).length > 0 && {
           mcpServers: mergedMcpServers,
         }),
@@ -593,10 +725,11 @@ export async function resumeClaudeTask(taskId: string): Promise<void> {
       usageState
     );
 
-    // Fire-and-forget pattern extraction for self-improvement
-    analyzeForLearnedPatterns(taskId, profileId).catch((err) => {
+    try {
+      await analyzeForLearnedPatterns(taskId, profileId);
+    } catch (err) {
       console.error("[self-improvement] pattern extraction failed:", err);
-    });
+    }
   } catch (error: unknown) {
     const errorMessage =
       error instanceof Error ? error.message : String(error);
@@ -612,6 +745,7 @@ export async function resumeClaudeTask(taskId: string): Promise<void> {
           status: "failed",
           result: "Session expired — re-queue for fresh start",
           sessionId: null,
+          failureReason: "auth_failed",
           updatedAt: new Date(),
         })
         .where(eq(tasks.id, taskId));
@@ -667,11 +801,14 @@ async function handleExecutionError(
     return;
   }
 
+  const failureReason = classifyError(error);
+
   await db
     .update(tasks)
     .set({
       status: "failed",
       result: errorMessage,
+      failureReason,
       updatedAt: new Date(),
     })
     .where(eq(tasks.id, taskId));

package/src/lib/agents/execution-manager.ts

@@ -1,6 +1,3 @@
-import { licenseManager } from "@/lib/license/manager";
-import { createTierLimitNotification } from "@/lib/license/notifications";
-
 interface RunningExecution {
   abortController: AbortController;
   sessionId: string | null;
@@ -17,42 +14,10 @@ export function getExecution(taskId: string): RunningExecution | undefined {
   return executions.get(taskId);
 }
 
-/**
- * Register a running execution. Checks the parallel workflow limit
- * for the current tier before allowing the execution to proceed.
- *
- * @throws {ParallelLimitError} if the concurrent execution limit is reached
- */
 export function setExecution(taskId: string, execution: RunningExecution): void {
-  const limit = licenseManager.getLimit("parallelWorkflows");
-  const currentCount = executions.size;
-
-  if (Number.isFinite(limit) && currentCount >= limit) {
-    const tier = licenseManager.getTier();
-    // Fire-and-forget notification
-    createTierLimitNotification("parallelWorkflows", currentCount, limit, taskId).catch(() => {});
-    throw new ParallelLimitError(currentCount, limit, tier);
-  }
-
   executions.set(taskId, execution);
 }
 
-export class ParallelLimitError extends Error {
-  public readonly current: number;
-  public readonly limit: number;
-  public readonly tier: string;
-
-  constructor(current: number, limit: number, tier: string) {
-    super(
-      `Parallel workflow limit reached (${current}/${limit}) on ${tier} tier. Wait for a running task to complete or upgrade.`
-    );
-    this.name = "ParallelLimitError";
-    this.current = current;
-    this.limit = limit;
-    this.tier = tier;
-  }
-}
-
 export function removeExecution(taskId: string): void {
   executions.delete(taskId);
 }

package/src/lib/agents/learned-context.ts

@@ -5,9 +5,6 @@ import type { LearnedContextRow } from "@/lib/db/schema";
 import { runMetaCompletion } from "./runtime/claude";
 import { getSettingSync } from "@/lib/settings/helpers";
 import { SETTINGS_KEYS } from "@/lib/constants/settings";
-import { checkLimit } from "@/lib/license/limit-check";
-import { getContextVersionCount } from "@/lib/license/limit-queries";
-import { createTierLimitNotification } from "@/lib/license/notifications";
 
 const DEFAULT_CONTEXT_CHAR_LIMIT = 8_000;
 const SUMMARIZATION_RATIO = 0.75;
@@ -95,15 +92,6 @@ export async function proposeContextAddition(
   additions: string,
   options?: { silent?: boolean }
 ): Promise<string> {
-  // Tier limit check — context version cap per profile
-  const versionCount = getContextVersionCount(profileId);
-  const limitResult = checkLimit("contextVersions", versionCount);
-  if (!limitResult.allowed) {
-    createTierLimitNotification("contextVersions", versionCount, limitResult.limit, taskId).catch(() => {});
-    throw new Error(
-      `Context version limit reached (${versionCount}/${limitResult.limit}). Upgrade to unlock more capacity.`
-    );
-  }
 
   const version = getNextVersion(profileId);
   const notificationId = options?.silent ? null : crypto.randomUUID();

package/src/lib/agents/learning-session.ts

@@ -181,6 +181,7 @@ export async function batchApproveProposals(
     await import("./learned-context");
 
   let approved = 0;
+  const touchedProfileIds = new Set<string>();
   for (const rowId of proposalRowIds) {
     const [row] = db
       .select()
@@ -229,16 +230,28 @@ export async function batchApproveProposals(
     }
 
     approved++;
-
-    const sizeInfo = checkContextSize(row.profileId);
-    if (sizeInfo.needsSummarization) {
-      await summarizeContext(row.profileId);
-    }
+    touchedProfileIds.add(row.profileId);
   }
 
   // Mark the batch notification as responded
   await markBatchNotificationResponded(proposalRowIds, "approved");
 
+  const profilesNeedingSummarization = [...touchedProfileIds].filter(
+    (profileId) => checkContextSize(profileId).needsSummarization
+  );
+  void Promise.allSettled(
+    profilesNeedingSummarization.map(async (profileId) => {
+      try {
+        await summarizeContext(profileId);
+      } catch (error) {
+        console.error(
+          "[learning-session] Failed to summarize approved context batch:",
+          error
+        );
+      }
+    })
+  );
+
   return approved;
 }
 

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

@@ -49,7 +49,7 @@ describe("profile registry", () => {
     expect(general!.domain).toBe("work");
   });
 
-  it("returns all 20 builtin profiles", () => {
+  it("returns all 21 builtin profiles", () => {
     const profiles = listProfiles().filter((p) => isBuiltin(p.id));
     const ids = profiles.map((p) => p.id);
 
@@ -68,14 +68,16 @@ describe("profile registry", () => {
     expect(ids).toContain("shopping-assistant");
     expect(ids).toContain("learning-coach");
     expect(ids).toContain("sweep");
-    // 6 new business function profiles
+    // 6 business function profiles
     expect(ids).toContain("marketing-strategist");
     expect(ids).toContain("sales-researcher");
     expect(ids).toContain("customer-support-agent");
     expect(ids).toContain("financial-analyst");
     expect(ids).toContain("content-creator");
     expect(ids).toContain("operations-coordinator");
-    expect(profiles.length).toBe(20);
+    // Clone lifecycle profile
+    expect(ids).toContain("upgrade-assistant");
+    expect(profiles.length).toBe(21);
   });
 
   it("getProfile returns undefined for unknown id", () => {
@@ -129,7 +131,7 @@ describe("profile registry", () => {
       (p) => p.domain === "personal"
     );
 
-    expect(workProfiles.length).toBe(15); // general, code-reviewer, researcher, document-writer, project-manager, data-analyst, technical-writer, devops-engineer, sweep + 6 business profiles
+    expect(workProfiles.length).toBe(16); // general, code-reviewer, researcher, document-writer, project-manager, data-analyst, technical-writer, devops-engineer, sweep + 6 business profiles + upgrade-assistant
     expect(personalProfiles.length).toBe(5); // wealth-manager, travel-planner, health-fitness-coach, shopping-assistant, learning-coach
   });
 

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

@@ -0,0 +1,70 @@
+---
+name: upgrade-assistant
+description: Guided interactive git merge of upstream stagent commits into the user's local instance branch
+---
+
+You are the Upgrade Assistant for a stagent clone. Your job is to pull upstream commits from `origin/main` into the user's instance branch safely and interactively, surfacing merge conflicts in plain language so the user can decide how to resolve them.
+
+## Context for this upgrade
+
+- **Instance branch:** `{{INSTANCE_BRANCH}}`
+- **Upstream commits behind:** `{{COMMITS_BEHIND}}`
+- **Data directory:** `{{DATA_DIR}}`
+- **Working directory:** the current repo root
+
+## 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.
+
+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.
+
+3. **If any step fails, roll back.** On any error after the merge has begun, run `git merge --abort` and `git stash pop` (if you stashed earlier) before reporting the failure. Leave the working tree in the state the user started in.
+
+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:
+   - **"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
+   After all conflicts are resolved, `git add` the files and continue the merge.
+
+## Standard merge flow
+
+Execute these steps in order. Report progress as you go so the live log view shows the user what's happening.
+
+1. **Pre-flight check.** Run `git status` to confirm the working tree state. If there's uncommitted work, tell the user you'll stash it first.
+
+2. **Stash any work-in-progress.** If the working tree is dirty, run `git stash push -m "upgrade-session auto-stash"`. Record that you stashed — you need to pop it at the end.
+
+3. **Fetch origin.** Run `git fetch origin main`. This is the only network operation. If it fails, report the error and stop.
+
+4. **Fast-forward main.** Run `git checkout main` then `git merge --ff-only origin/main`. If `--ff-only` fails, stop and ask the user (see Rule 1).
+
+5. **Return to the instance branch.** Run `git checkout {{INSTANCE_BRANCH}}`.
+
+6. **Merge main into the instance branch.** Run `git merge main`. If there are conflicts, git will report them. For each conflicted file, use the three-choice flow (Rule 5).
+
+7. **Complete the merge commit.** After conflicts are resolved (or if there were none), run `git commit` to finalize the merge if git hasn't already done so automatically.
+
+8. **Reinstall dependencies if package-lock.json changed.** Check `git diff HEAD~1 HEAD -- package-lock.json`. If there are changes, run `npm install`.
+
+9. **Pop the stash.** If you stashed in step 2, run `git stash pop`. Then immediately run `git status` to check for conflicts. If any file shows "both modified" or "Unmerged", the stash pop conflicted — resolve each file using the same three-choice flow (Rule 5), then `git add` the resolved files. After all stash conflicts are resolved, run `git stash drop` to remove the stash entry (a conflicted pop does NOT auto-drop the stash). Finally, run `grep -rn "<<<<<<< \|>>>>>>>" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.json" .` to verify no conflict markers remain in the working tree.
+
+10. **Report completion.** Tell the user the merge is complete, how many new commits landed, whether dependencies were reinstalled, and that they should restart the dev server to apply changes.
+
+## Aborting
+
+If the user clicks "Abort" during the session, or if any step fails irrecoverably, run:
+- `git merge --abort` (safe to run even if no merge is in progress — it'll just exit 0)
+- `git checkout {{INSTANCE_BRANCH}}` (return the user to where they started)
+- If you stashed in step 2: run `git stash pop`. Then run `git status` — if there are conflicts from the pop, resolve them using the three-choice flow (Rule 5), `git add` the files, and `git stash drop`. Run `grep -rn "<<<<<<< \|>>>>>>>" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.json" .` to verify no markers remain
+
+Then report the abort and what state the repo is in.
+
+## Guidelines
+
+- Be concise but explanatory. The user is watching a live log — they need enough context to understand what's happening, not a novel.
+- Always name the file path when asking about a conflict.
+- If the user sends a natural-language question mid-merge ("what do these changes do?"), answer it based on the diff before proceeding.
+- Never use `git push`. Never use `git rebase`. Never use `git reset --hard`. Never delete branches. Never touch the remote.
+- If `git status` shows files you didn't touch and the user didn't mention, bring them up before assuming they're safe to stash.

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

@@ -0,0 +1,32 @@
+id: upgrade-assistant
+name: Upgrade Assistant
+version: "1.0.0"
+domain: work
+tags: [upgrade, git, merge, maintenance, instance]
+supportedRuntimes: [claude-code, anthropic-direct]
+preferredRuntime: anthropic-direct
+
+maxTurns: 40
+
+author: stagent
+
+# Bash tool allowlist — tight scope.
+# The upgrade assistant should only ever run git and npm install, nothing else.
+# Cross-reference: TDR-028 "self-upgrade via task pipeline, not chat tools"
+# explains why this profile is the only safe surface for git shell access.
+allowedTools:
+  - Bash(git fetch *)
+  - Bash(git status)
+  - Bash(git status *)
+  - Bash(git stash *)
+  - Bash(git checkout *)
+  - Bash(git merge *)
+  - Bash(git merge --abort)
+  - Bash(git commit *)
+  - Bash(git diff *)
+  - Bash(git rev-parse *)
+  - Bash(git log *)
+  - Bash(git branch *)
+  - Bash(npm install)
+  - Read
+  - Write