stagent 0.9.5 → 0.10.0

package/docs/superpowers/specs/2026-04-08-swarm-visibility-design.md

@@ -0,0 +1,213 @@
+# Spec C — Swarm Visibility
+
+**Status:** Approved
+**Created:** 2026-04-08
+**Scope mode:** REDUCE
+**Related:** [Schedule Orchestration (Spec A)](./2026-04-08-schedule-orchestration-design.md), [Chat SSE Resilience Hotfix (Spec B)](./2026-04-08-chat-sse-resilience-hotfix-design.md)
+
+## Context
+
+Spec A introduces a global concurrency cap on scheduled agents. Power users running many schedules will observe queueing delays that they previously did not. Without a visible signal for "how busy is the swarm right now," they'll experience unexplained schedule lateness and file tickets.
+
+This spec adds minimal, always-visible swarm-load signal to the app chrome, a saturation-only pre-chat banner, and small enhancements to the schedule list. It is deliberately small — REDUCE mode — to avoid overbuilding visibility infrastructure before we know what users actually need.
+
+## Goals
+
+1. Give users a passive, always-visible signal of swarm load state (quiet / working / saturated).
+2. Warn users *before* they send a chat message if the swarm is at capacity and their chat will queue behind running agents.
+3. Make the new concurrency-driven queueing visible on the schedule list.
+4. Rename "turns" to "agent steps" everywhere user-facing, to close the semantic gap between prompt-level "MAX N turns" hints and runtime-counted turns.
+
+## Non-goals (NOT in scope)
+
+- **Activity feed route** (`/swarm/activity`) with event log, filters, pagination — future spec "Swarm Activity Feed"
+- **`swarm_snapshots` time-series table** — future spec "Swarm Activity Feed"
+- **Proactive push notifications for overload** — the indicator is always visible, no push needed
+- **Bulk "pause all schedules" action** — users can pause individual schedules from existing pages
+- **Efficiency scoring rings** / turn drift detection alerts — future spec "Schedule Observability"
+- **New `busyness` StatusChip family** — rejected by design review; use custom primitive
+- **Pre-chat banner in `working` state** — only render in `saturated` state to avoid anxiety copy
+- **Traffic-light turn-budget badge** (`lastTurnCount / maxTurns` with color gradient) — leaks policy as warning on normal operation
+- **Popover / Sheet for running schedules list** — hover tooltip + deep link to existing route is sufficient
+
+## Design
+
+### C.1 `GET /api/swarm-status` endpoint
+
+New route at `src/app/api/swarm-status/route.ts`. Reads:
+
+- `getAllExecutions()` from `src/lib/agents/execution-manager.ts:60` — filters to `sourceType === 'scheduled'` for running count and schedule metadata
+- A count query on `tasks` table for `status='queued' AND source_type='scheduled'` — queued count
+- `activeChatStreams.size` from Spec A's `src/lib/chat/active-streams.ts`
+
+**Response shape:**
+
+```json
+{
+  "runningScheduled": [
+    {
+      "scheduleId": "abc",
+      "name": "Portfolio Coach",
+      "startedAt": "2026-04-08T21:00:03Z",
+      "elapsedSec": 42,
+      "maxTurns": 500,
+      "currentTurns": 127
+    }
+  ],
+  "queuedScheduled": [
+    { "scheduleId": "def", "name": "News Sentinel", "queuedAt": "2026-04-08T21:00:14Z", "position": 1 }
+  ],
+  "chatStreamsActive": 0,
+  "loadState": "working"
+}
+```
+
+`loadState` is computed server-side:
+- `quiet` — `runningScheduled.length === 0`
+- `working` — `runningScheduled.length >= 1 && queuedScheduled.length === 0`
+- `saturated` — `queuedScheduled.length > 0` (at-or-above cap)
+
+No new DB state — the endpoint reads from in-memory execution map + one SQL count.
+
+### C.2 `<SwarmLoadIndicator />` component
+
+**Placement:** top of `<SidebarContent>` in `src/components/shared/app-sidebar.tsx`, above the first NavGroup. Not the footer — per design review, the footer is already dense (UpgradeBadge, WorkspaceIndicator, AuthStatusDot, TrustTierBadge, theme toggle) and the sidebar-as-chrome pattern means aggregate system state belongs at the top, where nav groups live.
+
+**Visual:** custom primitive (NOT a StatusChip family — semantic mismatch; StatusChip is "one entity, one state", swarm load is "aggregate cardinality"). Reuses badge tokens and the pulse animation pattern but renders as a thin one-line row.
+
+**Three states** (not four — red is reserved for actual failures, not backpressure):
+
+| State | Condition | Token | Label |
+|---|---|---|---|
+| Quiet | `loadState === 'quiet'` | `text-muted-foreground` | `Swarm quiet` |
+| Working | `loadState === 'working'` | `text-status-running` (indigo, pulse) | `● 2 running` |
+| Saturated | `loadState === 'saturated'` | `text-status-warning` (amber, pulse) | `● 3 running · 1 queued` |
+
+**Hover tooltip:** lists up to 3 running schedules inline with elapsed time. Delivers ~80% of the "activity feed" value with zero new overlay state:
+
+```
+Swarm · 2 running
+─────────────────
+• portfolio-coach    2m
+• launch-copy-chief  41s
+```
+
+If there are more than 3 running, append `• +N more`.
+
+**Click behavior:** the indicator is a `<Link>` to `/schedules?status=running` — deep-link to the existing schedules page with a filter. No popover, no sheet, no new overlay pattern.
+
+**Polling:** every 8s via new `usePolling(url, intervalMs)` hook (C.5). Shared state is used by both the indicator and the pre-chat banner so there is no double-fetch.
+
+**Accessibility:** `aria-live="polite"`, tooltip keyboard-focusable, text contrast meets Calm Ops baseline.
+
+### C.3 `<ChatOverloadBanner />` component
+
+**Placement:** above `<ChatInput />` in `src/components/chat/chat-shell.tsx`.
+
+**Render condition:** ONLY when `loadState === 'saturated'` (queue depth > 0). Not `working`. Anxiety copy on normal operation violates Calm Ops tone — "responses may be slower" with zero agency tells users a bad thing might happen and gives them no action.
+
+**Visual:** surface-2 bordered banner, `rounded-lg`, amber accent matching the indicator's saturated state.
+
+**Copy:** `"Swarm at capacity — your chat will queue behind {N} running agents."` where N is `runningScheduled.length`. One action: `[View Activity]` links to `/schedules?status=running`.
+
+**Dismissal:** per conversation, stored in `sessionStorage` keyed by conversation ID. Re-appears if load state flips back to `saturated` after being `working`.
+
+### C.4 Schedule list row enhancements
+
+Modify `src/components/schedules/schedule-list.tsx` (or equivalent):
+
+1. **Queue-depth badge (PR2a):** if a schedule has queued firings waiting for a slot, render `+{N} queued` as an `outline` Badge next to the schedule name. Almost free — reuses existing badge component. Addresses the power-user scenario where 10 schedules fire in a 5-min window and #4-10 queue silently.
+
+2. **"Near turn cap" outline badge:** rendered ONLY when `lastTurnCount / maxTurns >= 0.9`. No traffic-light gradient. Progressive disclosure — normal operation shows nothing. At ≥90%, shows a subtle outline badge: `Near step cap`.
+
+### C.5 `usePolling(url, intervalMs)` shared hook
+
+New file `src/hooks/use-polling.ts`. Extracted from the pattern at `src/components/notifications/inbox-list.tsx:40-43`. Signature:
+
+```typescript
+export function usePolling<T>(url: string, intervalMs: number): {
+  data: T | null;
+  error: Error | null;
+  loading: boolean;
+};
+```
+
+Fetches on mount, re-fetches every `intervalMs`. Handles unmount cleanup. Stable query key (URL) so multiple consumers of the same URL share state via module-level cache.
+
+Used by: `<SwarmLoadIndicator />`, `<ChatOverloadBanner />`. Can be adopted by other components (inbox list, schedule detail sheet) in future cleanups.
+
+### C.6 UI rename: "turns" → "agent steps"
+
+User-facing strings only. Keep `maxTurns` as the code/API identifier.
+
+- `schedule-form.tsx` field label: "Max turns per firing" → "Max agent steps per run"
+- Tooltip on field: "One step = one agent action (message, tool call, or sub-response). Most schedules use 50–500 steps; heavy research runs 2,000+."
+- Tooltip on prompt field: "Note: writing 'MAX N turns' in your prompt is a hint to the model, not a runtime limit. Use Max agent steps below to enforce a budget."
+- Inline calibration hint after prompt entry: "Schedules like this average ~{N} steps" (derived from `avgTurnsPerFiring` on similar schedules).
+- Schedule list "Near step cap" badge (C.4)
+- Notifications: "Schedule X used 812 / 800 agent steps" (formerly "turns")
+
+## Calm Ops compliance checklist
+
+- [x] No backdrop-filter, rgba, glass, gradient
+- [x] Running state uses `status-running` (indigo), NOT green (green is `status-completed`)
+- [x] Saturated state uses `status-warning` (amber), NOT red (red is `status-failed`)
+- [x] No new StatusChip family added (use custom `SwarmLoadIndicator`)
+- [x] No popover/sheet overlay — tooltip + deep link only
+- [x] Banner only renders when actionable (saturated state), not `working`
+- [x] All radii ≤ `rounded-xl`
+- [x] Polling pattern reuses existing template (`inbox-list.tsx`)
+- [x] Any Sheet usage (N/A here) would need `px-6 pb-6` body padding
+
+## Tests
+
+### Unit / component
+1. `<SwarmLoadIndicator />` renders correct state (Quiet / Working / Saturated) for each input
+2. Tooltip shows running schedules; click navigates to `/schedules?status=running`
+3. `<ChatOverloadBanner />` renders ONLY in `saturated` state
+4. Dismissal persists in sessionStorage across re-mounts
+5. Queue-depth badge renders when schedule has queued firings
+6. "Near step cap" badge renders only at ≥90% ratio
+7. `usePolling` hook fetches on mount, re-fetches on interval, cleans up on unmount
+8. Multiple consumers of same URL share state (no duplicate fetches)
+
+### API
+9. `GET /api/swarm-status` returns correct shape with running/queued/chat counts
+10. `loadState` computed correctly at boundary conditions (0 running, cap-1 running, cap running, queue>0)
+
+### Accessibility
+11. Indicator has `aria-live="polite"`
+12. Tooltip is keyboard-focusable
+13. Contrast meets Calm Ops baseline (manual check)
+
+### Visual regression
+14. Screenshot sidebar in all 3 states; compare to Calm Ops tokens
+
+## Files touched
+
+### New
+- `src/app/api/swarm-status/route.ts`
+- `src/hooks/use-polling.ts`
+- `src/components/shared/swarm-load-indicator.tsx`
+- `src/components/chat/chat-overload-banner.tsx`
+
+### Modify
+- `src/components/shared/app-sidebar.tsx` — mount `<SwarmLoadIndicator />` at top of SidebarContent
+- `src/components/chat/chat-shell.tsx` — mount `<ChatOverloadBanner />` above ChatInput
+- `src/components/schedules/schedule-list.tsx` (or equivalent) — queue-depth badge + near-cap badge
+- `src/components/schedules/schedule-form.tsx` — rename + tooltips + calibration hint
+
+### Not modified (avoiding pollution)
+- `src/lib/constants/status-families.ts` — NO new `busyness` family per design review
+
+## Dependencies on Spec A
+
+- `<SwarmLoadIndicator />` reads `chatStreamsActive` from the in-memory `activeChatStreams` set created by Spec A (`src/lib/chat/active-streams.ts`). C can scaffold mid-A after A's interface is pinned.
+- Queue-depth badge reads `tasks.status='queued' AND source_type='scheduled'` which exists today but is populated meaningfully only after Spec A's concurrency limiter lands.
+- "Near step cap" badge reads `schedules.max_turns` column added by Spec A.
+
+## Ship plan
+
+- No feature flag — UI is additive and safe.
+- Scaffolding (API endpoint, hook, indicator component) can begin mid-A.
+- Full ship after Spec A stabilizes and A's data-model migrations have landed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stagent",
-  "version": "0.9.5",
+  "version": "0.10.0",
   "description": "AI Business Operating System — run your business with AI agents. Local-first, multi-provider, governed.",
   "keywords": [
     "ai",
@@ -67,7 +67,6 @@
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
     "@hookform/resolvers": "^5.2.2",
-    "@supabase/supabase-js": "^2.101.1",
     "@tailwindcss/postcss": "^4",
     "@tailwindcss/typography": "^0.5",
     "@tanstack/react-table": "^8.21.3",
@@ -97,6 +96,7 @@
     "react-markdown": "^10.1.0",
     "recharts": "^3.8.1",
     "remark-gfm": "^4.0.1",
+    "semver": "^7.7.4",
     "sharp": "^0.34.5",
     "smol-toml": "^1.6.1",
     "sonner": "^2.0.7",
@@ -116,6 +116,7 @@
     "@types/js-yaml": "^4.0.9",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "@types/semver": "^7.7.1",
     "@types/sharp": "^0.31.1",
     "@vitejs/plugin-react": "^5.1.4",
     "@vitest/coverage-v8": "^4.0.18",

package/src/__tests__/instrumentation-smoke.test.ts

@@ -0,0 +1,15 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+describe("instrumentation register()", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("ensureInstance is importable from the bootstrap module and returns a skipped result in dev mode", async () => {
+    vi.stubEnv("STAGENT_DEV_MODE", "true");
+    const { ensureInstance } = await import("@/lib/instance/bootstrap");
+    const result = await ensureInstance();
+    expect(result.skipped).toBe("dev_mode_env");
+    expect(result.steps).toEqual([]);
+  });
+});

package/src/app/analytics/page.tsx

@@ -1,8 +1,6 @@
 import { Suspense } from "react";
 import { PageShell } from "@/components/shared/page-shell";
 import { AnalyticsDashboard } from "@/components/analytics/analytics-dashboard";
-import { AnalyticsGateCard } from "@/components/analytics/analytics-gate-card";
-import { licenseManager } from "@/lib/license/manager";
 import {
   getOutcomeCounts,
   getSuccessRateTrend,
@@ -14,16 +12,13 @@ import {
 export const dynamic = "force-dynamic";
 
 function AnalyticsContent() {
-  const tier = licenseManager.getTierFromDb();
-  const isAllowed = tier !== "community";
-
   const outcomes = getOutcomeCounts(30);
   const successTrend = getSuccessRateTrend(30);
   const costTrend = getCostPerOutcomeTrend(30);
   const leaderboard = getProfileLeaderboard(30);
   const hoursSaved = getEstimatedHoursSaved(30);
 
-  const dashboard = (
+  return (
     <AnalyticsDashboard
       outcomes={outcomes}
       successTrend={successTrend}
@@ -32,21 +27,6 @@ function AnalyticsContent() {
       hoursSaved={hoursSaved}
     />
   );
-
-  if (isAllowed) return dashboard;
-
-  return (
-    <div className="relative">
-      {/* Blurred dashboard preview */}
-      <div className="opacity-20 pointer-events-none select-none blur-[2px]" aria-hidden>
-        {dashboard}
-      </div>
-      {/* Upgrade CTA */}
-      <div className="absolute inset-0 flex items-start justify-center pt-16">
-        <AnalyticsGateCard />
-      </div>
-    </div>
-  );
 }
 
 export default function AnalyticsPage() {

package/src/app/api/chat/conversations/[id]/messages/route.ts

@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from "next/server";
 import { getConversation, getMessages } from "@/lib/data/chat";
 import { sendMessage } from "@/lib/chat/engine";
+import { recordTermination } from "@/lib/chat/stream-telemetry";
 
 /**
  * GET /api/chat/conversations/[id]/messages?after=xxx&limit=100
@@ -58,6 +59,7 @@ export async function POST(
 
   // Bridge the async generator to an SSE ReadableStream
   const encoder = new TextEncoder();
+  const streamStartedAt = Date.now();
   const stream = new ReadableStream({
     async start(controller) {
       const keepalive = setInterval(() => {
@@ -94,9 +96,28 @@ export async function POST(
         );
       } finally {
         clearInterval(keepalive);
-        controller.close();
+        try {
+          controller.close();
+        } catch {
+          // Stream may already be closed by peer; safe to ignore
+        }
       }
     },
+    // Fires when the client disconnects mid-stream (browser tab closed,
+    // user navigated away, AbortController.abort() fired on the fetch).
+    // The engine's own `req.signal` abort already records
+    // `stream.aborted.signal` in its catch path — this cancel callback
+    // only fires when the ReadableStream is torn down independently,
+    // so record it as a distinct `stream.aborted.client` code.
+    cancel(reason) {
+      recordTermination({
+        reason: "stream.aborted.client",
+        conversationId: id,
+        messageId: null,
+        durationMs: Date.now() - streamStartedAt,
+        error: reason ? String(reason).slice(0, 200) : undefined,
+      });
+    },
   });
 
   return new Response(stream, {

package/src/app/api/diagnostics/chat-streams/route.ts

@@ -0,0 +1,65 @@
+import { NextRequest, NextResponse } from "next/server";
+import {
+  readTerminations,
+  countTerminations,
+} from "@/lib/chat/stream-telemetry";
+
+/**
+ * GET /api/diagnostics/chat-streams
+ *
+ * Dev-only diagnostics endpoint that reports how chat SSE streams have
+ * terminated in the current server process. Returns counts by reason code
+ * plus the most recent N events.
+ *
+ * Query params:
+ *   ?windowMinutes=N  — restrict counts to the last N minutes (default: all)
+ *   ?limit=N          — cap on recent events returned (default: 50, max: 500)
+ *
+ * Response shape:
+ *   {
+ *     windowMinutes: number | null,
+ *     totalEvents: number,
+ *     counts: Record<TerminationReason, number>,
+ *     recent: TerminationEvent[]
+ *   }
+ *
+ * Gated behind NODE_ENV !== production to match the data/clear and
+ * data/seed routes. This is for maintainer inspection, not end users.
+ *
+ * See src/lib/chat/stream-telemetry.ts for the ring buffer + reason code
+ * definitions. See features/chat-stream-resilience-telemetry.md for the
+ * motivation (verify-before-building telemetry for a mid-stream refresh
+ * bug reported by a sibling repo that doesn't reproduce here).
+ */
+export async function GET(req: NextRequest) {
+  if (process.env.NODE_ENV === "production") {
+    return NextResponse.json(
+      { error: "Diagnostics disabled in production" },
+      { status: 403 }
+    );
+  }
+
+  const { searchParams } = req.nextUrl;
+  const windowMinutesRaw = searchParams.get("windowMinutes");
+  const limitRaw = searchParams.get("limit");
+
+  const windowMinutes =
+    windowMinutesRaw !== null ? Math.max(0, parseInt(windowMinutesRaw, 10) || 0) : null;
+  const windowMs = windowMinutes !== null ? windowMinutes * 60 * 1000 : 0;
+
+  const limit = Math.min(
+    500,
+    limitRaw !== null ? Math.max(1, parseInt(limitRaw, 10) || 50) : 50
+  );
+
+  const all = readTerminations();
+  const recent = all.slice(-limit).reverse(); // newest first
+  const counts = countTerminations(windowMs);
+
+  return NextResponse.json({
+    windowMinutes,
+    totalEvents: all.length,
+    counts,
+    recent,
+  });
+}

package/src/app/api/instance/config/route.ts

@@ -0,0 +1,41 @@
+import { NextResponse } from "next/server";
+import {
+  getInstanceConfig,
+  getGuardrails,
+  getUpgradeState,
+} from "@/lib/instance/settings";
+import { isDevMode } from "@/lib/instance/detect";
+
+/**
+ * GET /api/instance/config
+ *
+ * Returns the full instance state: config, guardrails, and upgrade state
+ * in a single response. Used by the Settings → Instance section and by
+ * the upgrade pre-flight modal.
+ *
+ * When running on the canonical dev repo (STAGENT_DEV_MODE=true or the
+ * .git/stagent-dev-mode sentinel), returns `{ devMode: true }` with null
+ * payloads. This prevents stale instance rows written during prior testing
+ * from surfacing in the UI as if the dev repo were a real instance.
+ */
+export async function GET() {
+  try {
+    if (isDevMode()) {
+      return NextResponse.json({
+        devMode: true,
+        config: null,
+        guardrails: null,
+        upgrade: null,
+      });
+    }
+    return NextResponse.json({
+      devMode: false,
+      config: getInstanceConfig(),
+      guardrails: getGuardrails(),
+      upgrade: getUpgradeState(),
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}

package/src/app/api/instance/init/route.ts

@@ -0,0 +1,34 @@
+import { NextResponse } from "next/server";
+import { ensureInstance } from "@/lib/instance/bootstrap";
+import {
+  getInstanceConfig,
+  getGuardrails,
+  getUpgradeState,
+} from "@/lib/instance/settings";
+
+/**
+ * POST /api/instance/init
+ *
+ * Idempotent manual re-run of the instance bootstrap. Useful when the
+ * initial boot-time run failed (permission error, git not installed),
+ * or when the user wants to re-apply guardrails after changing consent
+ * via the Settings → Instance UI.
+ *
+ * Returns the current instance config + guardrails + upgrade state after
+ * the re-run so the Settings → Instance section can refresh its display
+ * without a second request.
+ */
+export async function POST() {
+  try {
+    const result = await ensureInstance();
+    return NextResponse.json({
+      ensureResult: result,
+      config: getInstanceConfig(),
+      guardrails: getGuardrails(),
+      upgrade: getUpgradeState(),
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}

package/src/app/api/instance/upgrade/check/route.ts

@@ -0,0 +1,26 @@
+import { NextResponse } from "next/server";
+import { tick } from "@/lib/instance/upgrade-poller";
+
+/**
+ * POST /api/instance/upgrade/check
+ *
+ * Force-run the upgrade availability poller. Rate-limited to one call per
+ * ~5 minutes via the same lock file the scheduled poller uses. Returns the
+ * new UpgradeState on success, or a skipped reason if the lock was held or
+ * dev-mode was active.
+ */
+export async function POST() {
+  try {
+    const result = await tick();
+    if (result.updated) {
+      return NextResponse.json({ ok: true, state: result.updated });
+    }
+    return NextResponse.json(
+      { ok: false, skipped: result.skipped, error: result.error },
+      { status: 202 }
+    );
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}

package/src/app/api/instance/upgrade/route.ts

@@ -0,0 +1,96 @@
+import { NextResponse } from "next/server";
+import { randomUUID } from "crypto";
+import { db } from "@/lib/db";
+import { tasks } from "@/lib/db/schema";
+import {
+  getInstanceConfig,
+  getUpgradeState,
+  setUpgradeState,
+} from "@/lib/instance/settings";
+
+/**
+ * POST /api/instance/upgrade
+ *
+ * Spawns an upgrade task with the `upgrade-assistant` agent profile. Returns
+ * 202 Accepted with the task id; the client then navigates to the upgrade
+ * session view to watch streaming progress and respond to conflict prompts.
+ *
+ * The task description includes the instance context (branch name, commits
+ * behind, data directory) as template variables that the profile's SKILL.md
+ * references. The claude-agent runtime interpolates them when building the
+ * system prompt.
+ *
+ * Fire-and-forget per TDR-001: the route returns immediately; task execution
+ * runs in the background through the existing execution-manager pipeline.
+ */
+export async function POST() {
+  try {
+    const config = getInstanceConfig();
+    if (!config) {
+      return NextResponse.json(
+        { error: "Instance not yet initialized — run POST /api/instance/init first" },
+        { status: 409 }
+      );
+    }
+
+    const upgrade = getUpgradeState();
+    if (!upgrade.upgradeAvailable) {
+      return NextResponse.json(
+        { error: "No upgrade available", upgradeState: upgrade },
+        { status: 409 }
+      );
+    }
+
+    const branchName = config.branchName;
+    const commitsBehind = upgrade.commitsBehind;
+    const dataDir = process.env.STAGENT_DATA_DIR ?? "~/.stagent";
+
+    const description = [
+      `Upgrade instance branch \`${branchName}\` with ${commitsBehind} upstream commit(s) from origin/main.`,
+      "",
+      "Context for the upgrade-assistant profile:",
+      `- INSTANCE_BRANCH=${branchName}`,
+      `- COMMITS_BEHIND=${commitsBehind}`,
+      `- DATA_DIR=${dataDir}`,
+      "",
+      "Follow the standard merge flow defined in SKILL.md. Stop and ask the user on any merge conflict. Abort and roll back on any failure. Do not push any branch.",
+    ].join("\n");
+
+    const id = randomUUID();
+    const now = new Date();
+
+    db.insert(tasks)
+      .values({
+        id,
+        title: `Upgrade ${branchName} — ${commitsBehind} upstream commit${commitsBehind === 1 ? "" : "s"}`,
+        description,
+        projectId: null,
+        priority: 1,
+        assignedAgent: null,
+        agentProfile: "upgrade-assistant",
+        sourceType: "manual",
+        status: "planned",
+        createdAt: now,
+        updatedAt: now,
+      })
+      .run();
+
+    // Record which task id owns this upgrade so the UI can deep-link to it,
+    // and optimistically clear the pending-count so the sidebar badge and
+    // settings card reflect the user's intent immediately. If the merge task
+    // fails or is cancelled, the next scheduled poll (or a manual "Check for
+    // upgrades") will restore the real count by re-running git rev-list.
+    await setUpgradeState({
+      ...upgrade,
+      lastUpgradeTaskId: id,
+      commitsBehind: 0,
+      upgradeAvailable: false,
+      lastSuccessfulUpgradeAt: Math.floor(Date.now() / 1000),
+    });
+
+    return NextResponse.json({ taskId: id }, { status: 202 });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}

package/src/app/api/instance/upgrade/status/route.ts

@@ -0,0 +1,35 @@
+import { NextResponse } from "next/server";
+import { getUpgradeState } from "@/lib/instance/settings";
+import { isDevMode } from "@/lib/instance/detect";
+
+/**
+ * GET /api/instance/upgrade/status
+ *
+ * Returns the current UpgradeState for client components that need to poll
+ * (e.g. the upgrade modal pre-flight). Server Components should read directly
+ * from settings per TDR-004 rather than calling this route.
+ *
+ * When running on the canonical dev repo, returns a synthetic state with
+ * `devMode: true` and `upgradeAvailable: false` so the sidebar upgrade
+ * button never renders on main.
+ */
+export async function GET() {
+  try {
+    if (isDevMode()) {
+      return NextResponse.json({
+        devMode: true,
+        lastPolledAt: null,
+        upgradeAvailable: false,
+        commitsBehind: 0,
+        lastSuccessfulUpgradeAt: null,
+        pollFailureCount: 0,
+        lastPollError: null,
+      });
+    }
+    const state = getUpgradeState();
+    return NextResponse.json({ devMode: false, ...state });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}