@pinagent/react-native 0.1.0

package/dist/server.js

@@ -0,0 +1,4681 @@
+import { Buffer as Buffer$1 } from "node:buffer";
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { delimiter, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { mkdir, open, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { and, and as and$1, asc, asc as asc$1, count, eq, eq as eq$1, gt, gte, lt, notInArray, sql } from "drizzle-orm";
+import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { z } from "zod";
+import { nanoid } from "nanoid";
+import { createHash } from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+import { fileURLToPath } from "node:url";
+import { drizzle } from "drizzle-orm/sqlite-proxy";
+import { createSdkMcpServer, query, tool } from "@anthropic-ai/claude-agent-sdk";
+import { createInterface } from "node:readline";
+import { WebSocket, WebSocketServer } from "ws";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+//#region ../db/dist/schema.js
+var schema_exports = /* @__PURE__ */ __exportAll({
+	activeRuns: () => activeRuns,
+	auditEvents: () => auditEvents,
+	conversations: () => conversations,
+	messages: () => messages,
+	pullRequests: () => pullRequests,
+	widgetAnchors: () => widgetAnchors
+});
+/**
+* Pinagent persistent state. Shared between the dev-side server
+* (Node's built-in `node:sqlite` via `@pinagent/agent-runner`'s
+* `src/db/client.ts`) and the browser cache (`@sqlite.org/sqlite-wasm` via
+* `@pinagent/widget/db/client`).
+*
+* Server-side is the source of truth: it owns the agent runs, log
+* files, and worktrees. The browser store mirrors only the
+* conversations the current page cares about and is rebuilt from
+* server state if it ever diverges.
+*
+* Naming follows the v2 plan (`pinagent-v2-plan.md` §4.2). When you
+* change a column here, run `pnpm --filter @pinagent/db drizzle:gen`
+* to produce a new migration; the server applies migrations on
+* connect.
+*/
+/**
+* One row per pinagent comment a developer submits. id is the nanoid
+* (matches the existing flat-file feedback id) so we can migrate
+* piecemeal without rewriting IDs.
+*
+* `status` mirrors what the MCP server writes today via `Storage.patch`
+* (`pending` / `fixed` / `wontfix` / `deferred`). `agentSessionId` is
+* the Claude Agent SDK session id we resume on follow-up turns.
+*/
+const conversations = sqliteTable("conversations", {
+	id: text("id").primaryKey(),
+	/**
+	* Comment text the developer wrote when submitting. Kept here in
+	* addition to the original feedback JSON so SQLite-only readers
+	* (browser cache) have it without a round-trip.
+	*/
+	comment: text("comment").notNull(),
+	/** SDK session id, set after the first agent run. */
+	agentSessionId: text("agent_session_id"),
+	status: text("status", { enum: [
+		"pending",
+		"fixed",
+		"wontfix",
+		"deferred"
+	] }).notNull().default("pending"),
+	/** Optional note left by the agent on resolve. */
+	note: text("note"),
+	/** Optional commit sha if the agent committed its fix. */
+	commitSha: text("commit_sha"),
+	/** When spawn mode is `worktree`, the git branch the agent ran in. */
+	branch: text("branch"),
+	/** When spawn mode is `worktree`, the absolute worktree path. */
+	worktreePath: text("worktree_path"),
+	/**
+	* Lifecycle of the worktree itself, orthogonal to `status` (which
+	* tracks the developer's intent toward the feedback). `none` for
+	* inline-mode rows that never created a worktree; `active` while the
+	* worktree exists on disk; `landed` after a successful merge into
+	* the project's HEAD branch; `discarded` after the developer threw
+	* the work away. Once non-`active`, Land/Discard controls are hidden.
+	*/
+	worktreeState: text("worktree_state", { enum: [
+		"none",
+		"active",
+		"landed",
+		"discarded"
+	] }).notNull().default("none"),
+	/**
+	* User-supplied title override. NULL means the dock falls back to a
+	* title derived from `comment` (first non-empty line, ≤80 chars).
+	* Renaming clears to NULL on empty input so the user can revert to
+	* the agent-derived title without remembering what it was.
+	*/
+	title: text("title"),
+	/**
+	* Soft-archive flag. Archived conversations are hidden from the
+	* default Conversations list and excluded from the FAB pending count.
+	* Orthogonal to status + worktreeState — you can archive an active
+	* worktree (the worktree stays on disk) or a landed one (just hides
+	* it from the active surface).
+	*/
+	archived: integer("archived", { mode: "boolean" }).notNull().default(false),
+	createdAt: integer("created_at", { mode: "timestamp_ms" }).notNull().default(sql`(unixepoch() * 1000)`),
+	updatedAt: integer("updated_at", { mode: "timestamp_ms" }).notNull().default(sql`(unixepoch() * 1000)`),
+	resolvedAt: integer("resolved_at", { mode: "timestamp_ms" })
+});
+/**
+* DOM anchor metadata captured at pick time so the widget can
+* re-anchor itself across HMR / reloads (v2 plan Phase G). One row per
+* conversation.
+*
+* `clickX` / `clickY` are the cursor position relative to the target
+* element's top-left — preserved through scrolls and layout shifts the
+* same way the live widget does it.
+*/
+const widgetAnchors = sqliteTable("widget_anchors", {
+	conversationId: text("conversation_id").primaryKey().references(() => conversations.id, { onDelete: "cascade" }),
+	url: text("url").notNull(),
+	/** From the `data-pa-loc` build-time attribute. */
+	file: text("file"),
+	line: integer("line"),
+	col: integer("col"),
+	/** CSS-selector fallback for when `data-pa-loc` isn't available. */
+	selector: text("selector").notNull(),
+	clickX: integer("click_x"),
+	clickY: integer("click_y"),
+	viewportW: integer("viewport_w"),
+	viewportH: integer("viewport_h"),
+	/** From `navigator.userAgent` at pick time. Mostly for debugging. */
+	userAgent: text("user_agent"),
+	/**
+	* Enclosing component name, from the `data-pa-comp` attribute the
+	* Babel plugin stamps next to `data-pa-loc`. Lets the agent prompt say
+	* "you clicked inside `<PriceCard>`" rather than a bare file:line. Null
+	* in uninstrumented apps or when the element sits outside any
+	* PascalCase component.
+	*/
+	component: text("component"),
+	/**
+	* Outer→inner chain of distinct enclosing component names, e.g.
+	* `["App", "PriceList", "PriceCard"]`. Gives the agent structural
+	* context about where in the component tree the target lives. Null
+	* when nothing is instrumented.
+	*/
+	componentPath: text("component_path", { mode: "json" }).$type(),
+	/**
+	* Loop-instance disambiguation. When the same JSX literal is rendered
+	* more than once (a `.map()`), `data-pa-loc` is ambiguous: many DOM
+	* nodes share one file:line. These capture *which* instance the user
+	* clicked — `instanceIndex` is the 0-based position among siblings
+	* sharing the loc and `instanceTotal` the count. Both null for the
+	* common unique-loc case so single-pick rows are unchanged.
+	*/
+	instanceIndex: integer("instance_index"),
+	instanceTotal: integer("instance_total"),
+	/**
+	* A short content fingerprint (text snippet + identity-ish attributes)
+	* of the clicked instance, so the agent can locate the right `.map()`
+	* item from the screenshot + source even though the file:line points
+	* at the shared JSX literal. Null unless the loc was ambiguous.
+	*/
+	instanceFingerprint: text("instance_fingerprint"),
+	/**
+	* Secondary elements picked via Cmd/Ctrl-click before the committing
+	* click. Same shape as the primary anchor's location columns, minus
+	* the viewport/userAgent context (those are shared at the conversation
+	* level). Null when the user picked exactly one element — the common
+	* case — so the column adds no cost to single-pick conversations.
+	*/
+	additionalAnchors: text("additional_anchors", { mode: "json" }).$type()
+});
+/**
+* Append-only transcript of agent events. One row per AgentEvent
+* (init / text / tool_use / tool_result / ask_user / error / result)
+* plus user messages typed in the widget (`role: 'user'`).
+*
+* `turn` increments per agent turn so we can group events for replay
+* and for the "Turn N" sections in the markdown log file.
+*
+* This table IS the source of truth for the event stream. The bus
+* (`packages/agent-runner/src/bus.ts`) writes every publish straight
+* to this table and subscribers poll it — so cross-process delivery
+* works even when Vite-style dual-context module loading would
+* otherwise split an in-memory bus into separate instances. A `role`
+* of `__finished` is the bus's end-of-run sentinel (excluded from
+* external reads).
+*/
+const messages = sqliteTable("messages", {
+	id: integer("id").primaryKey({ autoIncrement: true }),
+	conversationId: text("conversation_id").notNull().references(() => conversations.id, { onDelete: "cascade" }),
+	turn: integer("turn").notNull(),
+	/**
+	* Discriminator. Matches AgentEvent.type plus `'user'` for typed
+	* follow-ups. Keep as text (not an enum) so adding new event types
+	* doesn't require a migration.
+	*/
+	role: text("role").notNull(),
+	/** Full event payload as JSON — kept opaque so schema evolves freely. */
+	content: text("content", { mode: "json" }).notNull(),
+	createdAt: integer("created_at", { mode: "timestamp_ms" }).notNull().default(sql`(unixepoch() * 1000)`)
+});
+/**
+* One row per in-flight SDK run. Server-only — the browser doesn't
+* need to know which runs are active, only their event stream.
+*
+* `awaitingAskId` is set whenever the `ask_user` tool is blocking on a
+* human response; lets the widget render the pending question
+* authoritatively even on a fresh page load.
+*/
+const activeRuns = sqliteTable("active_runs", {
+	conversationId: text("conversation_id").primaryKey().references(() => conversations.id, { onDelete: "cascade" }),
+	startedAt: integer("started_at", { mode: "timestamp_ms" }).notNull(),
+	currentTurn: integer("current_turn").notNull(),
+	awaitingAskId: text("awaiting_ask_id"),
+	lastError: text("last_error")
+});
+/**
+* One row per GitHub PR the dock's compose flow has opened. Populated
+* by `composePullRequest` on the success path and read by the dock's
+* PRs route. The `state` column starts as `open` and is intended to be
+* reconciled against the GitHub API by a future refresh job — the
+* write path here only knows about creation.
+*
+* `conversationIds` is stored as a JSON array of the feedback ids the
+* compose flow bundled into the PR, mirroring what
+* `ComposeOpts.feedbackIds` carried in.
+*/
+const pullRequests = sqliteTable("pull_requests", {
+	id: integer("id").primaryKey({ autoIncrement: true }),
+	/** GitHub PR number (unique within the repo). */
+	number: integer("number").notNull(),
+	/** Octokit's `html_url` — what the dock links out to. */
+	url: text("url").notNull(),
+	/** Compose branch name pushed for this PR. */
+	branch: text("branch").notNull(),
+	/** Target branch the PR merges into. */
+	baseBranch: text("base_branch").notNull(),
+	title: text("title").notNull(),
+	/**
+	* PR body (markdown). Kept so the dock can show a preview without
+	* round-tripping GitHub.
+	*/
+	body: text("body").notNull().default(""),
+	state: text("state", { enum: [
+		"open",
+		"merged",
+		"closed",
+		"draft"
+	] }).notNull().default("open"),
+	/** Feedback/conversation ids bundled into this PR. */
+	conversationIds: text("conversation_ids", { mode: "json" }).$type().notNull().default(sql`('[]')`),
+	createdAt: integer("created_at", { mode: "timestamp_ms" }).notNull().default(sql`(unixepoch() * 1000)`),
+	updatedAt: integer("updated_at", { mode: "timestamp_ms" }).notNull().default(sql`(unixepoch() * 1000)`)
+});
+/**
+* Append-only audit trail of meaningful project actions. Backs the
+* History route's Activity tab. Rows are derived from explicit emit
+* sites (Storage.create, mergeWorktree, discardWorktree,
+* composePullRequest); the table isn't a generic event sink and isn't
+* trying to mirror every WS event.
+*
+* `conversationId` is nullable so project-wide events (e.g. future
+* settings changes) can live here too, but every action emitted today
+* has one. `action` is kept as text — not an enum — so new actions can
+* land without a migration. `payload` is opaque JSON, shaped per-action
+* (e.g. `{ branch, commitSha }` for `conversation_landed`).
+*/
+const auditEvents = sqliteTable("audit_events", {
+	id: integer("id").primaryKey({ autoIncrement: true }),
+	conversationId: text("conversation_id"),
+	actor: text("actor", { enum: [
+		"agent",
+		"user",
+		"system"
+	] }).notNull(),
+	action: text("action").notNull(),
+	payload: text("payload", { mode: "json" }).$type().notNull().default(sql`('{}')`),
+	createdAt: integer("created_at", { mode: "timestamp_ms" }).notNull().default(sql`(unixepoch() * 1000)`)
+});
+//#endregion
+//#region ../shared/dist/index.js
+/**
+* Zod schemas for the dock's HTTP boundary. The widget-dock package's
+* LocalTransport uses these to parse responses before handing them to
+* React; the server side (agent-runner via vite-plugin / next-plugin)
+* is free to use the same schemas to typecheck its return values.
+*
+* Phase 7b expanded the coverage to every read endpoint the dock hits.
+* Write endpoints (mutations) reuse the same response schemas.
+*
+* `.loose()` everywhere — unknown fields survive the parse so
+* additions to a payload don't break old dock builds.
+*/
+/** Dock-rendered status. Mirrors @pinagent/ui's StatusKey. */
+const StatusKeySchema = z.enum([
+	"pending",
+	"working",
+	"awaitingClarification",
+	"readyToLand",
+	"landed",
+	"discarded",
+	"error",
+	"anchorLost"
+]);
+const AnchorSchema = z.object({
+	loc: z.string(),
+	selector: z.string(),
+	snippet: z.string()
+}).loose();
+z.object({
+	id: z.string(),
+	shortId: z.string(),
+	title: z.string(),
+	status: StatusKeySchema,
+	page: z.string(),
+	anchor: AnchorSchema,
+	branch: z.string(),
+	updatedAt: z.string(),
+	lastMessage: z.string(),
+	messageCount: z.number().int().nonnegative()
+}).loose().extend({
+	comment: z.string(),
+	screenshot: z.string().nullable()
+}).loose();
+z.object({
+	id: z.string(),
+	conversationId: z.string(),
+	conversationTitle: z.string(),
+	status: z.enum([
+		"readyToLand",
+		"pending",
+		"landed",
+		"error"
+	]),
+	branch: z.string(),
+	filesChanged: z.number().int().nonnegative(),
+	additions: z.number().int().nonnegative(),
+	deletions: z.number().int().nonnegative(),
+	preview: z.string(),
+	updatedAt: z.string()
+}).loose();
+z.object({
+	diff: z.string(),
+	truncated: z.boolean(),
+	/**
+	* Absolute path of the conversation's worktree, so the dock can open a
+	* changed file at the agent's edited version. Optional for older servers.
+	*/
+	worktreePath: z.string().optional()
+}).loose();
+z.object({
+	id: z.string(),
+	name: z.string(),
+	conversationId: z.string().nullable(),
+	conversationTitle: z.string().nullable(),
+	createdAt: z.string(),
+	lastActivity: z.string(),
+	state: z.enum([
+		"clean",
+		"uncommitted",
+		"behind-base"
+	]),
+	diskMb: z.number().nullable()
+}).loose();
+z.object({
+	id: z.string(),
+	number: z.number().int(),
+	title: z.string(),
+	state: z.enum([
+		"open",
+		"merged",
+		"closed",
+		"draft"
+	]),
+	branch: z.string(),
+	baseBranch: z.string(),
+	url: z.string(),
+	updatedAt: z.string(),
+	conversationIds: z.array(z.string())
+}).loose();
+const WorkingCopyFileSchema = z.object({
+	path: z.string(),
+	added: z.number().int().nonnegative(),
+	deleted: z.number().int().nonnegative(),
+	status: z.enum([
+		"modified",
+		"added",
+		"deleted",
+		"renamed"
+	])
+}).loose();
+z.object({
+	branch: z.string(),
+	baseBranch: z.string(),
+	isDefaultBranch: z.boolean(),
+	filesChanged: z.number().int().nonnegative(),
+	additions: z.number().int().nonnegative(),
+	deletions: z.number().int().nonnegative(),
+	files: z.array(WorkingCopyFileSchema),
+	ahead: z.number().int().nonnegative(),
+	behind: z.number().int().nonnegative(),
+	hasUpstream: z.boolean(),
+	dirty: z.boolean(),
+	pr: z.object({
+		number: z.number().int(),
+		url: z.string(),
+		state: z.enum([
+			"open",
+			"merged",
+			"closed",
+			"draft"
+		])
+	}).nullable()
+}).loose();
+z.object({
+	github: z.object({
+		connected: z.boolean(),
+		login: z.string().nullable()
+	}).loose(),
+	anthropic: z.object({ keySet: z.boolean() }).loose()
+}).loose();
+/**
+* The three permission-mode options the dock's Settings picker exposes,
+* pinned alongside their SDK-mode equivalents and all human-facing
+* label text. Single source of truth — adding a fourth mode = one
+* append to this list, no scattered edits across the dock UI, the
+* detail-header chip, and the server-side translator.
+*
+* Consumers:
+*   - `PermissionModeSchema` below (zod enum derived from `projectMode`)
+*   - `agent-runner/settings-store` re-exports the schema/type
+*   - `agent-runner/agent.toSdkPermissionMode` looks up `sdkMode`
+*   - `widget-dock/routes/Settings.tsx` iterates this list for the
+*     picker (uses `label` + `description`)
+*   - `widget-dock/lib/permissionMode.ts` looks up the SDK→display
+*     mapping for the detail-header chip (uses `shortLabel` + `tooltip`)
+*
+* `as const` so consumers can derive literal-string types.
+*/
+const PROJECT_PERMISSION_MODES = [
+	{
+		projectMode: "auto",
+		sdkMode: "acceptEdits",
+		label: "Auto-accept edits",
+		shortLabel: "Auto-accept",
+		description: "Agent edits land in the worktree without confirmation.",
+		tooltip: "Auto-accept edits — tool calls run without prompting."
+	},
+	{
+		projectMode: "approve",
+		sdkMode: "default",
+		label: "Require approval",
+		shortLabel: "Approval required",
+		description: "Each edit pauses for your approval before applying.",
+		tooltip: "Approval required — the agent prompts before each tool call."
+	},
+	{
+		projectMode: "dry-run",
+		sdkMode: "plan",
+		label: "Dry-run only",
+		shortLabel: "Dry-run",
+		description: "Agents propose but never write. Useful for review-only setups.",
+		tooltip: "Dry-run — plan mode: the agent reasons without running tools."
+	}
+];
+const PermissionModeSchema = z.enum(PROJECT_PERMISSION_MODES.map((m) => m.projectMode));
+z.object({
+	baseBranch: z.string(),
+	worktreeRetentionDays: z.number().int().nonnegative(),
+	perConversationCapUsd: z.number(),
+	monthlyBudgetUsd: z.number().nullable(),
+	permissionMode: PermissionModeSchema,
+	/**
+	* If `PINAGENT_AGENT_PERMISSION_MODE` is set on the dev server, this
+	* carries the resolved SDK mode that will *actually* be used at
+	* spawn time — overriding the user's saved `permissionMode` above.
+	* `null` when no env override is active. Read-only on the wire:
+	* `ProjectSettingsPatchSchema.partial()` silently drops it on PATCH.
+	*
+	* Default is `null` so older servers without this field still parse
+	* cleanly into the dock.
+	*/
+	permissionModeOverride: z.string().nullable().default(null)
+}).loose();
+z.object({
+	pruned: z.array(z.string()),
+	failed: z.array(z.object({
+		feedbackId: z.string(),
+		error: z.string()
+	}).loose()),
+	retentionDays: z.number().int().nonnegative()
+}).loose();
+const AuditActorSchema = z.enum([
+	"agent",
+	"user",
+	"system"
+]);
+z.object({
+	id: z.string(),
+	conversationId: z.string().nullable(),
+	actor: AuditActorSchema,
+	action: z.string(),
+	payload: z.record(z.string(), z.unknown()),
+	createdAt: z.string()
+}).loose();
+const HistoryMatchedFieldSchema = z.enum([
+	"comment",
+	"note",
+	"branch",
+	"anchor",
+	"selector"
+]);
+z.object({
+	id: z.string(),
+	comment: z.string(),
+	status: z.enum([
+		"fixed",
+		"wontfix",
+		"pending",
+		"deferred"
+	]),
+	worktreeState: z.enum([
+		"none",
+		"active",
+		"landed",
+		"discarded"
+	]),
+	branch: z.string().nullable(),
+	file: z.string().nullable(),
+	line: z.number().nullable(),
+	col: z.number().nullable(),
+	selector: z.string(),
+	url: z.string(),
+	createdAt: z.string(),
+	updatedAt: z.string(),
+	resolvedAt: z.string().nullable(),
+	matchedFields: z.array(HistoryMatchedFieldSchema),
+	snippet: z.string()
+}).loose();
+/**
+* postMessage protocol between the embedded dock iframe and its host
+* page. Defines the wire contract; no runtime yet — the EmbeddedTransport
+* class that implements this protocol lands in a follow-up phase once
+* the dock has a real cross-origin context to talk to (the hosted
+* dashboard relay).
+*
+* Why the contract lives in @pinagent/shared today rather than in the
+* dock or host-script package:
+*
+*   - Both sides of the boundary (the dock and the host's relay) need
+*     the same schemas to validate inbound frames; pulling them from
+*     a third package keeps either side independently swappable.
+*
+*   - The hosted relay (apps/cloud) and the local dev relay
+*     (packages/vite-plugin / packages/next-plugin) will both
+*     implement the same host-side surface; one source of truth for
+*     their input grammar makes the parity story explicit.
+*
+* Origin checking is strict in both directions and lives in the future
+* EmbeddedTransport class; the schemas here only validate shapes, not
+* provenance.
+*
+* Spec reference: pinpoint-dock-surface.md §5 (postMessage protocol).
+*/
+/**
+* RPC-style request. `id` is a UUID-ish correlation token the host
+* echoes back on the response so the dock can resolve the right
+* Promise. `path` mirrors the same-origin URL the LocalTransport hits
+* today (`/__pinagent/...`) so the host relay can forward without
+* its own routing table.
+*/
+const DockToHostQuerySchema = z.object({
+	type: z.literal("query"),
+	id: z.string().min(1),
+	path: z.string().min(1),
+	params: z.record(z.string(), z.unknown()).optional()
+}).strict();
+const DockToHostMutateSchema = z.object({
+	type: z.literal("mutate"),
+	id: z.string().min(1),
+	path: z.string().min(1),
+	body: z.unknown()
+}).strict();
+/**
+* Open a long-lived subscription to a server channel (project events,
+* per-conversation event stream, etc). The host relay keeps a map of
+* `subscriptionId → backend listener` and pushes back `event` frames.
+*/
+const DockToHostSubscribeSchema = z.object({
+	type: z.literal("subscribe"),
+	channel: z.string().min(1),
+	subscriptionId: z.string().min(1),
+	params: z.record(z.string(), z.unknown()).optional()
+}).strict();
+const DockToHostUnsubscribeSchema = z.object({
+	type: z.literal("unsubscribe"),
+	subscriptionId: z.string().min(1)
+}).strict();
+/**
+* Ask the host to open a popup window (OAuth flow, external link). The
+* host owns the window because the iframe sandbox bars
+* `allow-top-navigation`. Response comes back as `popup-closed` with
+* an optional result the popup posted to its opener pre-close.
+*/
+const DockToHostOpenPopupSchema = z.object({
+	type: z.literal("open-popup"),
+	url: z.string().url(),
+	subscriptionId: z.string().min(1)
+}).strict();
+/**
+* Pure UI signals — open/close/resize — that the host might react to
+* (e.g. shifting the underlying page when the dock opens in panel
+* mode). The host doesn't have to handle these; the dock fires them
+* for observability.
+*/
+const DockToHostUiEventSchema = z.object({
+	type: z.literal("ui-event"),
+	event: z.enum([
+		"open",
+		"close",
+		"resize"
+	]),
+	payload: z.record(z.string(), z.unknown()).optional()
+}).strict();
+z.discriminatedUnion("type", [
+	DockToHostQuerySchema,
+	DockToHostMutateSchema,
+	DockToHostSubscribeSchema,
+	DockToHostUnsubscribeSchema,
+	DockToHostOpenPopupSchema,
+	DockToHostUiEventSchema
+]);
+/**
+* RPC response — `ok: true` carries the data, `ok: false` carries a
+* code + human-readable message so the dock can route into its
+* ErrorState components without re-deriving from string contents.
+*/
+const HostToDockResponseSchema = z.discriminatedUnion("ok", [z.object({
+	type: z.literal("response"),
+	id: z.string().min(1),
+	ok: z.literal(true),
+	data: z.unknown()
+}).strict(), z.object({
+	type: z.literal("response"),
+	id: z.string().min(1),
+	ok: z.literal(false),
+	error: z.object({
+		code: z.string().min(1),
+		message: z.string().min(1)
+	}).strict()
+}).strict()]);
+const HostToDockEventSchema = z.object({
+	type: z.literal("event"),
+	subscriptionId: z.string().min(1),
+	payload: z.unknown()
+}).strict();
+const HostToDockPopupClosedSchema = z.object({
+	type: z.literal("popup-closed"),
+	subscriptionId: z.string().min(1),
+	result: z.record(z.string(), z.unknown()).optional()
+}).strict();
+/**
+* Once at iframe load (and on any host-side change worth re-broadcasting),
+* the host pushes its environment: which URL it's on, current viewport
+* dimensions, current theme. Lets the dock skip its own re-render
+* dance for context the host already knows.
+*/
+const HostToDockContextSchema = z.object({
+	type: z.literal("host-context"),
+	payload: z.object({
+		url: z.string(),
+		viewport: z.object({
+			w: z.number().int().nonnegative(),
+			h: z.number().int().nonnegative()
+		}).strict(),
+		theme: z.enum(["light", "dark"])
+	}).strict()
+}).strict();
+z.union([
+	HostToDockResponseSchema,
+	HostToDockEventSchema,
+	HostToDockPopupClosedSchema,
+	HostToDockContextSchema
+]);
+/**
+* Zod mirror of the AgentEvent union. Kept alongside the TS type so
+* the wire-boundary parse (ws-client on the dock) catches shape drift
+* the moment the server adds or renames a field — better than React
+* rendering `undefined` at runtime. Use `.loose()` on each
+* object so unknown fields survive the parse instead of being
+* stripped; future event-payload additions stay backwards compatible
+* for old clients.
+*/
+const AgentEventSchema = z.discriminatedUnion("type", [
+	z.object({
+		type: z.literal("init"),
+		sessionId: z.string(),
+		model: z.string(),
+		permissionMode: z.string(),
+		apiKeySource: z.string()
+	}).loose(),
+	z.object({
+		type: z.literal("text"),
+		text: z.string()
+	}).loose(),
+	z.object({
+		type: z.literal("tool_use"),
+		name: z.string(),
+		summary: z.string()
+	}).loose(),
+	z.object({
+		type: z.literal("tool_result"),
+		ok: z.boolean()
+	}).loose(),
+	z.object({
+		type: z.literal("progress"),
+		turn: z.number()
+	}).loose(),
+	z.object({
+		type: z.literal("ask_user"),
+		askId: z.string(),
+		question: z.string(),
+		context: z.string().optional(),
+		options: z.array(z.string()).optional()
+	}).loose(),
+	z.object({
+		type: z.literal("error"),
+		message: z.string()
+	}).loose(),
+	z.object({
+		type: z.literal("result"),
+		subtype: z.string(),
+		numTurns: z.number(),
+		totalCostUsd: z.number(),
+		durationMs: z.number(),
+		errors: z.array(z.string()).optional()
+	}).loose(),
+	z.object({
+		type: z.literal("status_changed"),
+		status: z.enum([
+			"pending",
+			"fixed",
+			"wontfix",
+			"deferred"
+		]),
+		note: z.string().nullable(),
+		commitSha: z.string().nullable(),
+		resolvedAt: z.string().nullable()
+	}).loose()
+]);
+/**
+* True when a run's reported `total_cost_usd` is notional rather than a
+* real charge — i.e. the SDK authenticated via a `claude login` session
+* (`apiKeySource === 'oauth'`) and the cost is billed against the Claude
+* subscription quota, not the developer's card. Both the in-page widget
+* footer and the dock's cost badge gate on this so the two surfaces can
+* never disagree on what counts as a billed run. If the SDK ever reports
+* a different string for subscription auth, change it here only.
+*/
+function isNotionalCost(apiKeySource) {
+	return apiKeySource === "oauth";
+}
+/**
+* Wire-format messages between the browser widget and the dev-side
+* WebSocket server.
+*
+* Validated on the server with the Zod schemas below. Client-side is
+* untyped at the wire boundary — the widget renders defensively.
+*
+* Reserved for the connection lifecycle:
+*  - `ping` / `pong`  — explicit liveness check (the `ws` library also
+*                       runs lower-level WS ping frames; this is
+*                       application-level and visible in protocol logs).
+*
+* Per-feedback subscribe/unsubscribe so one socket can multiplex
+* multiple in-flight agents — sets us up for the v2 "multiple widgets
+* per page" goal without changing the wire format.
+*/
+const FeedbackId = z.string().min(8).max(16).regex(/^[A-Za-z0-9_-]+$/);
+const ClientMessageSchema = z.discriminatedUnion("type", [
+	z.object({
+		type: z.literal("subscribe"),
+		feedbackId: FeedbackId
+	}),
+	z.object({
+		type: z.literal("unsubscribe"),
+		feedbackId: FeedbackId
+	}),
+	z.object({
+		type: z.literal("user_message"),
+		feedbackId: FeedbackId,
+		content: z.string().min(1).max(8e3)
+	}),
+	z.object({
+		type: z.literal("ask_response"),
+		askId: z.string().min(1).max(64),
+		answer: z.string().max(8e3)
+	}),
+	z.object({
+		type: z.literal("interrupt"),
+		feedbackId: FeedbackId
+	}),
+	z.object({
+		type: z.literal("land_request"),
+		feedbackId: FeedbackId
+	}),
+	z.object({
+		type: z.literal("discard_request"),
+		feedbackId: FeedbackId
+	}),
+	z.object({
+		type: z.literal("reopen_request"),
+		feedbackId: FeedbackId
+	}),
+	z.object({ type: z.literal("subscribe_project") }),
+	z.object({ type: z.literal("unsubscribe_project") }),
+	z.object({
+		type: z.literal("extension_hello"),
+		version: z.string().max(32).optional()
+	}),
+	z.object({ type: z.literal("query_extension") }),
+	z.object({
+		type: z.literal("set_branch_routing"),
+		defaultBaseBranch: z.string().min(1).max(128).nullable(),
+		allowedBranchPatterns: z.array(z.string().min(1).max(128)).max(50)
+	}),
+	z.object({ type: z.literal("ping") })
+]);
+const ProjectEventSchema = z.discriminatedUnion("type", [z.object({ type: z.literal("conversations_changed") }).loose(), z.object({ type: z.literal("worktree_servers_changed") }).loose()]);
+/**
+* Phase H lifecycle states the server can broadcast for a worktree.
+* Mirrors `Conversation.worktreeState` plus two transient states:
+*   - `landing` / `discarding` — operation is in flight (optimistic UI hint)
+*   - `conflict` — merge aborted because of conflicts; `conflicts` lists files
+*   - `ttl_warning` — orphan-sweeper found this worktree past TTL
+*/
+const WorktreeWireStateSchema = z.enum([
+	"none",
+	"active",
+	"landing",
+	"landed",
+	"discarding",
+	"discarded",
+	"conflict",
+	"ttl_warning"
+]);
+z.discriminatedUnion("type", [
+	z.object({
+		type: z.literal("event"),
+		feedbackId: z.string(),
+		event: AgentEventSchema
+	}).loose(),
+	z.object({
+		type: z.literal("done"),
+		feedbackId: z.string()
+	}).loose(),
+	z.object({
+		type: z.literal("error"),
+		feedbackId: z.string().optional(),
+		message: z.string()
+	}).loose(),
+	z.object({
+		type: z.literal("worktree_state"),
+		feedbackId: z.string(),
+		state: WorktreeWireStateSchema,
+		commitSha: z.string().optional(),
+		conflicts: z.array(z.string()).optional(),
+		message: z.string().optional(),
+		changesCount: z.number().optional()
+	}).loose(),
+	z.object({
+		type: z.literal("project_event"),
+		event: ProjectEventSchema
+	}).loose(),
+	z.object({
+		type: z.literal("extension_status"),
+		present: z.boolean(),
+		version: z.string().optional()
+	}).loose(),
+	z.object({ type: z.literal("pong") }).loose()
+]);
+//#endregion
+//#region ../agent-runner/dist/host-branch-pr.js
+/**
+* Small helpers for safe on-disk JSON stores (secrets, settings):
+*
+*  - `withFileLock` serializes a read-modify-write critical section against a
+*    path across all callers in this process, so two concurrent `patch()` calls
+*    can't both read the same base and clobber each other's update.
+*  - `atomicWriteFile` writes a sibling temp file (at the requested mode) then
+*    renames it over the target, so a reader never sees a half-written file and
+*    a sensitive file is never momentarily world-readable. A crash mid-write
+*    leaves the previous file intact instead of truncating it.
+*/
+const locks = /* @__PURE__ */ new Map();
+let tmpCounter = 0;
+/** Run `fn` holding an exclusive in-process lock keyed by `key` (a file path). */
+function withFileLock(key, fn) {
+	const run = (locks.get(key) ?? Promise.resolve()).then(fn, fn);
+	const tail = run.then(() => {}, () => {});
+	locks.set(key, tail);
+	tail.then(() => {
+		if (locks.get(key) === tail) locks.delete(key);
+	});
+	return run;
+}
+/**
+* Atomically write `data` to `path`: write a temp sibling (created with `mode`
+* when given, so it's never momentarily more permissive than intended) and
+* rename it over the target. Cleans up the temp on failure.
+*/
+async function atomicWriteFile(path, data, mode) {
+	await mkdir(dirname(path), { recursive: true });
+	const tmp = `${path}.tmp-${process.pid}-${tmpCounter++}`;
+	try {
+		await writeFile(tmp, data, mode !== void 0 ? { mode } : void 0);
+		await rename(tmp, path);
+	} catch (err) {
+		await rm(tmp, { force: true }).catch(() => {});
+		throw err;
+	}
+}
+const ProjectSettingsSchema = z.object({
+	baseBranch: z.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9/_.-]*$/, "invalid branch name"),
+	worktreeRetentionDays: z.number().int().min(1).max(60),
+	perConversationCapUsd: z.number().min(.1).max(1e3),
+	monthlyBudgetUsd: z.number().min(0).max(1e5).nullable(),
+	permissionMode: PermissionModeSchema,
+	allowedBranchPatterns: z.array(z.string().min(1).max(128)).max(50)
+});
+ProjectSettingsSchema.partial();
+const DEFAULT_SETTINGS = {
+	baseBranch: "main",
+	worktreeRetentionDays: 7,
+	perConversationCapUsd: 5,
+	monthlyBudgetUsd: null,
+	permissionMode: "auto",
+	allowedBranchPatterns: []
+};
+var SettingsStore = class {
+	projectRoot;
+	constructor(projectRoot) {
+		this.projectRoot = projectRoot;
+	}
+	path() {
+		return join(this.projectRoot, ".pinagent", "config.json");
+	}
+	async read() {
+		const path = this.path();
+		if (!existsSync(path)) return DEFAULT_SETTINGS;
+		try {
+			const raw = await readFile(path, "utf8");
+			const merged = {
+				...DEFAULT_SETTINGS,
+				...JSON.parse(raw)
+			};
+			return ProjectSettingsSchema.parse(merged);
+		} catch {
+			return DEFAULT_SETTINGS;
+		}
+	}
+	async patch(patch) {
+		const path = this.path();
+		return withFileLock(path, async () => {
+			const current = await this.read();
+			const next = ProjectSettingsSchema.parse({
+				...current,
+				...patch
+			});
+			await atomicWriteFile(path, JSON.stringify(next, null, 2));
+			return next;
+		});
+	}
+};
+{
+	const proc = process;
+	const originalEmit = proc.emit.bind(proc);
+	proc.emit = (event, ...args) => {
+		if (event === "warning") {
+			const warning = args[0];
+			if (warning instanceof Error && warning.name === "ExperimentalWarning" && warning.message.startsWith("SQLite is an experimental feature")) return false;
+		}
+		return originalEmit(event, ...args);
+	};
+}
+/**
+* One Drizzle handle per dev process, keyed by project root so a
+* monorepo with multiple Pinagent-enabled apps gets distinct DBs.
+*
+* Storage is per-process and held on a globalThis Symbol so Next 16's
+* route module re-evaluations don't open the same DB file twice. The
+* underlying node:sqlite handle is cheap to keep open for the lifetime
+* of `next dev`.
+*
+* We use Node's built-in `node:sqlite` (stable since Node 22.13) rather
+* than `better-sqlite3` to avoid the native-build install step (pnpm
+* 10+ blocks postinstall by default; users were hitting
+* `Could not locate the bindings file` after fresh installs). Same
+* underlying SQLite engine, same on-disk format — no data migration.
+*
+* `drizzle-orm/sqlite-proxy` is the right adapter shape: it takes a
+* callback that executes SQL against any backend. We thread node:sqlite
+* synchronous calls through it. Drizzle exposes an async API to
+* consumers but our storage layer already `await`s everything, so call
+* sites are unchanged.
+*/
+const SINGLETON_KEY = Symbol.for("pinagent.db");
+const moduleUrl = import.meta.url;
+const MIGRATIONS_DIR = (() => {
+	const base = moduleUrl ? dirname(fileURLToPath(moduleUrl)) : __dirname;
+	const candidates = [
+		resolve(base, "..", "drizzle"),
+		resolve(base, "..", "..", "db", "drizzle"),
+		resolve(base, "..", "..", "..", "db", "drizzle")
+	];
+	return candidates.find((p) => existsSync(resolve(p, "meta", "_journal.json"))) ?? candidates[0];
+})();
+/**
+* Wrap a `node:sqlite` DatabaseSync in the drizzle-orm/sqlite-proxy
+* callback shape. `method` distinguishes 'run' (no rows expected,
+* returns changes / lastInsertRowid) from 'all' / 'get' / 'values'
+* (rows). The proxy callback is declared async; we just call the sync
+* primitives and return synchronously — Drizzle awaits the result.
+*/
+function makeDrizzle(raw) {
+	return drizzle(async (sql, params, method) => {
+		const stmt = raw.prepare(sql);
+		if (method === "run") {
+			const info = stmt.run(...params);
+			return { rows: [{
+				changes: Number(info.changes),
+				lastInsertRowid: info.lastInsertRowid
+			}] };
+		}
+		const rows = stmt.all(...params);
+		const columns = stmt.columns().map((c) => c.column ?? c.name);
+		const projected = rows.map((r) => columns.map((c) => r[c] ?? null));
+		if (method === "get") return { rows: projected[0] ?? [] };
+		return { rows: projected };
+	}, { schema: schema_exports });
+}
+/**
+* Apply every `.sql` migration in journal order. Replaces
+* `drizzle-orm/better-sqlite3/migrator` (which is bound to the
+* better-sqlite3 driver) with a tiny equivalent that drives node:sqlite
+* directly. Mirrors the browser-side migrator pattern in
+* `packages/widget/src/db/migrations.ts`.
+*/
+function runMigrations(raw, migrationsDir) {
+	const journalPath = join(migrationsDir, "meta", "_journal.json");
+	if (!existsSync(journalPath)) {
+		console.warn(`[pinagent:db] no migrations dir at ${migrationsDir}; skipping migrate(). Run \`pnpm --filter @pinagent/db drizzle:gen\` to generate.`);
+		return;
+	}
+	raw.exec(`CREATE TABLE IF NOT EXISTS __drizzle_migrations (
+       id INTEGER PRIMARY KEY AUTOINCREMENT,
+       hash TEXT NOT NULL,
+       created_at NUMERIC
+     )`);
+	const sortedEntries = JSON.parse(readFileSync(journalPath, "utf8")).entries.slice().sort((a, b) => a.idx - b.idx);
+	const hashOf = (entry) => {
+		const sql = readFileSync(join(migrationsDir, `${entry.tag}.sql`), "utf8");
+		return createHash("sha256").update(sql).digest("hex");
+	};
+	const insert = raw.prepare("INSERT INTO __drizzle_migrations (hash, created_at) VALUES (?, ?)");
+	const lastRow = raw.prepare("SELECT created_at FROM __drizzle_migrations ORDER BY created_at DESC LIMIT 1").get();
+	let lastWhen = lastRow?.created_at != null ? Number(lastRow.created_at) : null;
+	if (lastWhen == null && sortedEntries.length > 0) {
+		if (raw.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='conversations'").get()) {
+			for (const entry of sortedEntries) insert.run(hashOf(entry), entry.when);
+			return;
+		}
+	}
+	for (const entry of sortedEntries) {
+		if (lastWhen != null && lastWhen >= entry.when) continue;
+		const sql = readFileSync(join(migrationsDir, `${entry.tag}.sql`), "utf8");
+		const statements = sql.split("--> statement-breakpoint").map((s) => s.trim()).filter(Boolean);
+		for (const stmt of statements) raw.exec(stmt);
+		insert.run(createHash("sha256").update(sql).digest("hex"), entry.when);
+		lastWhen = entry.when;
+	}
+}
+function getDb(projectRoot) {
+	const g = globalThis;
+	if (!g[SINGLETON_KEY]) g[SINGLETON_KEY] = /* @__PURE__ */ new Map();
+	const cache = g[SINGLETON_KEY];
+	const root = resolve(projectRoot);
+	const existing = cache.get(root);
+	if (existing) return existing.db;
+	const dbPath = join(root, ".pinagent", "db.sqlite");
+	const pinagentDir = dirname(dbPath);
+	mkdirSync(pinagentDir, { recursive: true });
+	const giPath = join(pinagentDir, ".gitignore");
+	if (!existsSync(giPath)) try {
+		writeFileSync(giPath, "*\n");
+	} catch {}
+	const raw = new DatabaseSync(dbPath);
+	raw.exec("PRAGMA journal_mode = WAL");
+	raw.exec("PRAGMA busy_timeout = 5000");
+	raw.exec("PRAGMA foreign_keys = ON");
+	runMigrations(raw, MIGRATIONS_DIR);
+	raw.exec("DELETE FROM active_runs");
+	const db = makeDrizzle(raw);
+	cache.set(root, {
+		db,
+		raw
+	});
+	return db;
+}
+/**
+* Shared `git` runner. Lifted out of agent.ts so other modules
+* (changes.ts, future PR-composer code) can use the same spawn shape
+* without importing the whole agent module + its SDK pulls.
+*/
+/**
+* Spawn `git` with the given args in `cwd`, capturing stdout and stderr.
+* Never rejects on non-zero exit — callers inspect `code` themselves
+* because non-zero exits are meaningful for several git commands
+* (`git merge` returns 1 on conflict, `git rev-parse` returns non-zero
+* for missing refs, etc).
+*/
+function runGitCapture(cwd, args, opts = {}) {
+	return runCapture("git", args, cwd, opts);
+}
+/**
+* Generic command-capture, same drain-safe shape as {@link runGitCapture}
+* (resolves on 'close', never rejects on non-zero exit). Used for `gh` (PR
+* creation fallback) as well as `git`. Rejects only if the binary can't be
+* spawned (e.g. `gh` not installed → ENOENT) — callers catch that to treat
+* the tool as unavailable.
+*/
+function runCapture(file, args, cwd, opts = {}) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(file, args, {
+			cwd,
+			stdio: "pipe"
+		});
+		let stdout = "";
+		let stderr = "";
+		let capped = false;
+		const max = opts.maxBytes;
+		child.stdout.on("data", (d) => {
+			if (capped) return;
+			stdout += d.toString("utf8");
+			if (max !== void 0 && stdout.length >= max) {
+				stdout = stdout.slice(0, max);
+				capped = true;
+				child.kill();
+			}
+		});
+		child.stderr.on("data", (d) => {
+			stderr += d.toString("utf8");
+		});
+		child.on("error", reject);
+		child.on("close", (code) => resolve({
+			code: code ?? -1,
+			stdout,
+			stderr,
+			capped
+		}));
+	});
+}
+/**
+* Spawn `git` and reject on non-zero exit, appending a diagnostic line to
+* the conversation log. Used for fire-and-forget mutations (`worktree add`)
+* where the caller wants an exception on failure rather than inspecting a
+* code — contrast with `runGitCapture`, which never rejects.
+*/
+function runGit(cwd, args, logPath) {
+	return new Promise((res, rej) => {
+		const child = spawn("git", args, {
+			cwd,
+			stdio: "pipe"
+		});
+		let stderr = "";
+		child.stderr.on("data", (d) => {
+			stderr += d.toString("utf8");
+		});
+		child.on("error", rej);
+		child.on("close", (code) => {
+			if (code === 0) res();
+			else {
+				appendLog(logPath, `[pinagent:git] git ${args.join(" ")} → exit ${code}\n${stderr}\n`).catch(() => {});
+				rej(/* @__PURE__ */ new Error(`git ${args.join(" ")} exited ${code}: ${stderr.trim()}`));
+			}
+		});
+	});
+}
+/** Append `text` to the file at `path`, creating it if needed. No-op on empty text. */
+async function appendLog(path, text) {
+	if (!text) return;
+	const h = await open(path, "a");
+	try {
+		await h.write(text);
+	} finally {
+		await h.close();
+	}
+}
+/**
+* Plaintext secrets at rest under `.pinagent/secrets.json`. The
+* dock's Connections route reads / writes via the HTTP endpoints
+* in `vite-plugin` / `next-plugin`, which call into this.
+*
+* For local dev: the secrets file lives on the same filesystem as
+* the user's git credentials, `.env` files, and shell history —
+* there's no real threat model improvement from encrypting at
+* rest. The hosted dashboard tier (spec §13 onwards) will need a
+* different storage backend; the API surface here is shaped so
+* that swap is local.
+*
+* Tokens never round-trip back out — readers either consume the
+* raw token inside the agent process (composer, SDK), or get the
+* presentable shape via `presentable()`.
+*/
+const SecretsFileSchema = z.object({
+	github: z.object({
+		token: z.string().min(1),
+		/** Cached from the validate-on-set GitHub `/user` call. */
+		login: z.string().min(1)
+	}).nullable().optional(),
+	anthropic: z.object({ key: z.string().min(1) }).nullable().optional()
+}).default({});
+var SecretsStore = class {
+	projectRoot;
+	constructor(projectRoot) {
+		this.projectRoot = projectRoot;
+	}
+	path() {
+		return join(this.projectRoot, ".pinagent", "secrets.json");
+	}
+	/** Read + parse. Returns `{}` for "no file yet" — that's expected on first run. */
+	async read() {
+		const path = this.path();
+		if (!existsSync(path)) return SecretsFileSchema.parse({});
+		try {
+			const raw = await readFile(path, "utf8");
+			return SecretsFileSchema.parse(JSON.parse(raw));
+		} catch {
+			return SecretsFileSchema.parse({});
+		}
+	}
+	async patch(patch) {
+		const path = this.path();
+		return withFileLock(path, async () => {
+			const next = {
+				...await this.read(),
+				...patch
+			};
+			await atomicWriteFile(path, JSON.stringify(next, null, 2), 384);
+			return next;
+		});
+	}
+	async setGithub(token, login) {
+		await this.patch({ github: {
+			token,
+			login
+		} });
+	}
+	async clearGithub() {
+		await this.patch({ github: null });
+	}
+	async setAnthropic(key) {
+		await this.patch({ anthropic: { key } });
+	}
+	async clearAnthropic() {
+		await this.patch({ anthropic: null });
+	}
+	async getGithubToken() {
+		return (await this.read()).github?.token ?? null;
+	}
+	async getAnthropicKey() {
+		return (await this.read()).anthropic?.key ?? null;
+	}
+	/** Token-free view safe to ship over the wire. */
+	async presentable() {
+		const f = await this.read();
+		return {
+			github: {
+				connected: Boolean(f.github),
+				login: f.github?.login ?? null
+			},
+			anthropic: { keySet: Boolean(f.anthropic) }
+		};
+	}
+};
+/**
+* Audit log — append-only record of meaningful project actions. Backs
+* the dock's History → Activity tab.
+*
+* Emitted at the action sites (Storage.create, mergeWorktree,
+* discardWorktree, composePullRequest) rather than tailing every event
+* the WS bus carries: the goal is a human-readable trail of what
+* happened to each conversation, not a transaction log.
+*
+* Writes are best-effort — `recordAuditEvent` swallows DB errors so a
+* failed audit insert can never mask a successful land/discard/PR. The
+* read side is exposed via `listAuditEvents` and surfaces a single
+* GET /__pinagent/audit-log endpoint to the dock.
+*/
+async function recordAuditEvent(projectRoot, input) {
+	try {
+		await getDb(projectRoot).insert(auditEvents).values({
+			conversationId: input.conversationId ?? null,
+			actor: input.actor,
+			action: input.action,
+			payload: input.payload ?? {}
+		});
+	} catch {}
+}
+//#endregion
+//#region ../agent-runner/dist/index.js
+/**
+* Resolve the SDK permission mode for a run. Precedence:
+*   `PINAGENT_AGENT_PERMISSION_MODE` env override > project settings
+*   (`.pinagent/config.json` permissionMode) > default.
+* The env override is kept so CI / power users can bypass the dock UI
+* without editing the settings file.
+*/
+async function resolveRunPermissionMode(projectRoot) {
+	const override = resolvePermissionModeOverride(process.env);
+	if (override) return override;
+	return toSdkPermissionMode((await new SettingsStore(projectRoot).read()).permissionMode);
+}
+function resolvePermissionMode(env) {
+	const v = env.PINAGENT_AGENT_PERMISSION_MODE;
+	if (v === "default" || v === "acceptEdits" || v === "bypassPermissions" || v === "plan" || v === "dontAsk" || v === "auto") return v;
+	return "acceptEdits";
+}
+/**
+* The active env override for permission mode, or `null` when no
+* override is set. Different shape from `resolvePermissionMode`, which
+* falls back to `'acceptEdits'` whether the env was unset or invalid —
+* callers that need to distinguish "no override" from "override → some
+* mode" (e.g. the dock's Settings UI banner) want this signal.
+*/
+function resolvePermissionModeOverride(env) {
+	if (!env.PINAGENT_AGENT_PERMISSION_MODE) return null;
+	return resolvePermissionMode(env);
+}
+/**
+* Map the user-facing project setting to the SDK's permission-mode
+* value-space. Looks up the shared `PROJECT_PERMISSION_MODES` table so
+* the mapping stays in sync with the dock's Settings labels and the
+* detail-header chip.
+*/
+function toSdkPermissionMode(mode) {
+	return PROJECT_PERMISSION_MODES.find((m) => m.projectMode === mode)?.sdkMode ?? "acceptEdits";
+}
+const POLL_INTERVAL_MS = 100;
+const FINISHED_ROLE = "__finished";
+var SqliteEventBus = class {
+	feedbackId;
+	projectRoot;
+	constructor(feedbackId, projectRoot) {
+		this.feedbackId = feedbackId;
+		this.projectRoot = projectRoot;
+	}
+	/**
+	* Append an event to the bus. INSERTs one row into `messages` keyed
+	* by the conversation id. Idempotent failures (e.g. the conversation
+	* row doesn't exist yet because POST handler hasn't finished writing
+	* it) are silently swallowed — the caller's event ordering is
+	* preserved by the autoincrement id, and a missing row would only
+	* happen during a narrow startup race we already tolerate.
+	*/
+	async publish(event) {
+		try {
+			await getDb(this.projectRoot).insert(messages).values({
+				conversationId: this.feedbackId,
+				turn: 1,
+				role: event.type,
+				content: event
+			});
+		} catch {}
+	}
+	/**
+	* Start delivering events to `sub`. Replays everything written so
+	* far for this feedback id (via the first poll), then delivers new
+	* events as they arrive. Calling the returned function stops
+	* polling.
+	*
+	* Polling is per-subscriber. For our actual subscriber load (1–3
+	* widget connections per feedback) this is cheaper than maintaining
+	* a shared poll loop with a fan-out Set.
+	*/
+	subscribe(sub) {
+		let lastSeenId = 0;
+		let stopped = false;
+		let polling = false;
+		const poll = async () => {
+			if (stopped || polling) return;
+			polling = true;
+			try {
+				const rows = await getDb(this.projectRoot).select().from(messages).where(and(eq(messages.conversationId, this.feedbackId), gt(messages.id, lastSeenId))).orderBy(asc(messages.id));
+				for (const row of rows) {
+					if (stopped) return;
+					lastSeenId = row.id;
+					if (row.role === FINISHED_ROLE) {
+						stopped = true;
+						clearInterval(interval);
+						try {
+							sub.onClose();
+						} catch {}
+						return;
+					}
+					try {
+						sub.onEvent(row.content);
+					} catch {}
+				}
+			} catch {} finally {
+				polling = false;
+			}
+		};
+		poll();
+		const interval = setInterval(() => {
+			poll();
+		}, POLL_INTERVAL_MS);
+		return () => {
+			stopped = true;
+			clearInterval(interval);
+		};
+	}
+	/**
+	* Signal that no more events will be published for this feedback.
+	* Writes a sentinel row that subscribers pick up on their next poll
+	* and translate into `onClose`. The DB rows themselves stay until
+	* the parent `conversations` row is deleted (FK cascade).
+	*/
+	async markFinished() {
+		try {
+			await getDb(this.projectRoot).insert(messages).values({
+				conversationId: this.feedbackId,
+				turn: 1,
+				role: FINISHED_ROLE,
+				content: {}
+			});
+		} catch {}
+	}
+};
+/**
+* Per-context cache of bus instances. Cross-context publish/subscribe
+* still works because the instances all hit the same SQLite file —
+* the cache here just avoids re-allocating the bus object on every
+* lookup within one context.
+*/
+const BUSES_SYMBOL = Symbol.for("pinagent.agent-runner.bus");
+const buses = globalThis[BUSES_SYMBOL] ?? /* @__PURE__ */ new Map();
+globalThis[BUSES_SYMBOL] = buses;
+function getOrCreateBus(feedbackId, projectRoot) {
+	const root = projectRoot ?? process.env.PINAGENT_PROJECT_ROOT ?? process.cwd();
+	let bus = buses.get(feedbackId);
+	if (!bus) {
+		bus = new SqliteEventBus(feedbackId, root);
+		buses.set(feedbackId, bus);
+	}
+	return bus;
+}
+/**
+* `ask_user` custom SDK tool — the agent's only blessed way to pause and
+* wait for a typed human answer mid-run.
+*
+* Flow:
+*   1. Model calls `ask_user({ question, ... })`.
+*   2. Handler generates an askId, publishes an `ask_user` AgentEvent to
+*      the feedback's bus (so subscribed WS clients render a form), and
+*      returns a Promise.
+*   3. User types an answer in the widget; the widget sends
+*      `ask_response { askId, answer }` over WS.
+*   4. The WS server calls `resolveAsk(askId, answer)`; the Promise
+*      resolves with a `CallToolResult` carrying the answer text; the
+*      agent receives it as the tool result and continues.
+*
+* If the run ends, the dev server restarts, or a TTL elapses with no
+* answer, the Promise rejects so the agent gets a clear failure rather
+* than hanging on a dead UI.
+*/
+const ASK_TTL_MS = 600 * 1e3;
+/**
+* Pending asks LOCAL TO THIS CONTEXT. The resolve/reject closures are
+* tied to the agent's Promise — process-bound, not serialisable. The
+* WS server can land in a different context than the one running the
+* agent (Next 16 Turbopack, Vite 8), so we route cross-context responses
+* via `process.emit(ASK_RESPONSE_EVENT, ...)` — see `resolveAsk`.
+*/
+const pending = /* @__PURE__ */ new Map();
+const ASK_RESPONSE_EVENT = "pinagent:ask-response";
+const inputSchema = {
+	question: z.string().min(1).max(2e3).describe("The question to ask the user. Be specific and concise."),
+	context: z.string().max(2e3).optional().describe("Optional: what you are trying to do and why you need this clarification. Helps the user answer with the right context."),
+	options: z.array(z.string().min(1).max(200)).max(6).optional().describe("Optional: suggested answers. Rendered as one-click buttons. Use sparingly — only when the answer is genuinely closed-ended.")
+};
+/**
+* Build an SDK MCP server that exposes a single `ask_user` tool scoped to
+* one feedback id. The handler closes over `feedbackId` so the published
+* event lands on the correct bus.
+*/
+function createAskUserMcpServer(feedbackId) {
+	return createSdkMcpServer({
+		name: "pinagent-ask-user",
+		version: "0.1.0",
+		tools: [tool("ask_user", [
+			"Ask the human developer a question and wait for their typed answer.",
+			"Use this when you cannot proceed without clarification — preferred over",
+			"guessing or making an assumption. The user sees the question in their",
+			"browser widget and types a response."
+		].join(" "), inputSchema, async (args) => {
+			const askId = nanoid(10);
+			const bus = getOrCreateBus(feedbackId);
+			return { content: [{
+				type: "text",
+				text: await new Promise((resolve, reject) => {
+					const timeout = setTimeout(() => {
+						pending.delete(askId);
+						process.off(ASK_RESPONSE_EVENT, onResponse);
+						reject(/* @__PURE__ */ new Error(`ask_user timed out after ${ASK_TTL_MS / 1e3}s with no response`));
+					}, ASK_TTL_MS);
+					const onResponse = (payload) => {
+						if (payload.askId !== askId) return;
+						const entry = pending.get(askId);
+						if (entry) entry.resolve(payload.answer);
+					};
+					process.on(ASK_RESPONSE_EVENT, onResponse);
+					pending.set(askId, {
+						feedbackId,
+						resolve: (a) => {
+							clearTimeout(timeout);
+							pending.delete(askId);
+							process.off(ASK_RESPONSE_EVENT, onResponse);
+							resolve(a);
+						},
+						reject: (reason) => {
+							clearTimeout(timeout);
+							pending.delete(askId);
+							process.off(ASK_RESPONSE_EVENT, onResponse);
+							reject(new Error(reason));
+						},
+						timeout
+					});
+					bus.publish({
+						type: "ask_user",
+						askId,
+						question: args.question,
+						context: args.context,
+						options: args.options
+					});
+				})
+			}] };
+		})]
+	});
+}
+/**
+* Resolve the matching pending ask. Tries the local-context Map first
+* for the same-context case; otherwise broadcasts via `process.emit`
+* so the context running the agent (and holding the resolve closure)
+* can settle the Promise. Returns true optimistically when emitting
+* cross-context — we can't know synchronously whether another context
+* had a matching pending entry, but stale UI / double-submits are rare
+* enough that swallowing the "no pending ask" error is acceptable.
+*/
+function resolveAsk(askId, answer) {
+	const entry = pending.get(askId);
+	if (entry) {
+		entry.resolve(answer);
+		return true;
+	}
+	const payload = {
+		askId,
+		answer
+	};
+	process.emit(ASK_RESPONSE_EVENT, payload);
+	return true;
+}
+/**
+* Reject every pending ask tied to this feedback id. Called when the
+* agent stream ends so the SDK Promise unblocks rather than hanging
+* until TTL.
+*/
+function rejectAsk(feedbackId, reason) {
+	for (const [askId, entry] of pending.entries()) if (entry.feedbackId === feedbackId) {
+		entry.reject(reason);
+		pending.delete(askId);
+	}
+}
+/**
+* MCP namespaces tools as `mcp__<server-name>__<tool-name>`. Pass this in
+* the SDK's `allowedTools` so the model can actually call it without a
+* permission prompt — otherwise `acceptEdits` mode wouldn't auto-allow a
+* non-Edit tool call.
+*/
+const ASK_USER_TOOL_NAME = "mcp__pinagent-ask-user__ask_user";
+const LISTENERS_SYMBOL = Symbol.for("pinagent.project-event.listeners");
+const listeners = globalThis[LISTENERS_SYMBOL] ?? /* @__PURE__ */ new Set();
+globalThis[LISTENERS_SYMBOL] = listeners;
+function emitProjectChange(event) {
+	for (const listener of listeners) try {
+		listener(event);
+	} catch {}
+}
+function onProjectChange(listener) {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
+}
+/**
+* Auth for agent runs — the explicit-key contract.
+*
+* Pinagent must never authenticate a run with an API key it merely *found* in
+* the environment. The Claude Agent SDK (and agentic CLIs like Codex) read a
+* raw `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` straight from `process.env`, so a
+* stale, scoped, or third-party key a developer exported for some unrelated
+* tool would otherwise be picked up silently — billing their key and, worse,
+* shadowing the Claude Code / Codex subscription they actually meant to use, so
+* the run dies with `authentication_failed` ("Invalid API key").
+*
+* A key is therefore used ONLY when the developer hands one to pinagent
+* explicitly, through one of two channels:
+*
+*   1. the `apiKey` option in the consuming app's plugin config
+*      (`pinagent({ apiKey })` in vite.config / next.config), bridged to the
+*      runner as `PINAGENT_AGENT_API_KEY`; or
+*   2. a key saved at runtime via the dock's Connections route (`SecretsStore`).
+*
+* With neither set, the implicit key is stripped from the run's environment and
+* the provider falls back to the agentic subscription — the behaviour a
+* developer running Pinagent locally expects.
+*/
+/**
+* pinagent-namespaced bridge var the plugins set from the explicit `apiKey`
+* option. This is the ONLY env channel pinagent treats as an opt-in to use a
+* raw key — never the ambient `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` a
+* developer may have exported for other tools.
+*/
+const EXPLICIT_API_KEY_ENV = "PINAGENT_AGENT_API_KEY";
+/**
+* Credentials provider SDKs / agentic CLIs read straight from the environment.
+* Stripped from any env pinagent hands to a run so a stray shell key can't
+* authenticate by accident; an explicitly-configured key is re-supplied on top.
+*/
+const ANTHROPIC_KEY_VAR = "ANTHROPIC_API_KEY";
+const PROVIDER_KEY_VARS = [ANTHROPIC_KEY_VAR, "OPENAI_API_KEY"];
+/** The key the developer configured for `pinagent({ apiKey })`, if any. */
+function configuredKey() {
+	return process.env["PINAGENT_AGENT_API_KEY"]?.trim() || null;
+}
+/**
+* Resolve the explicitly-configured Anthropic key for a Claude Agent SDK run,
+* or null when the developer configured neither channel (→ subscription).
+* A dock-saved key is the runtime override and wins, so a user can swap auth
+* without editing config or restarting the dev server; otherwise the
+* plugin-config key applies.
+*/
+async function resolveAnthropicKey(projectRoot) {
+	return await new SecretsStore(projectRoot).getAnthropicKey() ?? configuredKey();
+}
+/**
+* Build the environment handed to a Claude Agent SDK `query()`: the inherited
+* environment with the implicit `ANTHROPIC_API_KEY` (and the internal bridge
+* var) removed, plus the explicitly-configured key re-added when one exists.
+* Entries in `extra` are applied last so callers can still pin run-scoped vars
+* (e.g. `PINAGENT_PROJECT_ROOT`).
+*/
+async function buildSdkAuthEnv(projectRoot, extra = {}) {
+	const env = { ...process.env };
+	delete env[ANTHROPIC_KEY_VAR];
+	delete env[EXPLICIT_API_KEY_ENV];
+	const key = await resolveAnthropicKey(projectRoot);
+	if (key) env[ANTHROPIC_KEY_VAR] = key;
+	return {
+		...env,
+		...extra
+	};
+}
+/**
+* Build the environment for a wrapped agent CLI (Codex, aider, …): the
+* inherited environment with the implicit provider keys (and the internal
+* bridge var) stripped, plus the explicitly-configured key re-supplied under
+* both provider names so whichever the CLI reads picks it up. Absent an
+* explicit key, the CLI sees none and falls back to its own login (e.g. Codex →
+* the ChatGPT subscription). `extra` overrides win last.
+*
+* Only the plugin-config key feeds the CLI: the dock's saved key is
+* Claude-provider-specific, so it isn't reinterpreted as an arbitrary CLI's
+* credential.
+*/
+function buildCliAuthEnv(extra = {}) {
+	const env = { ...process.env };
+	const key = configuredKey();
+	for (const v of PROVIDER_KEY_VARS) delete env[v];
+	delete env[EXPLICIT_API_KEY_ENV];
+	if (key) for (const v of PROVIDER_KEY_VARS) env[v] = key;
+	return {
+		...env,
+		...extra
+	};
+}
+/**
+* Surfacing the project guidance nearest to the element the developer
+* clicked. When feedback lands with a `file:line`, walk up the directory
+* tree from that file toward the project root and pull in the closest
+* `CLAUDE.md` / `AGENTS.md` so the agent starts with the conventions that
+* actually govern the code it's about to touch.
+*
+* The Claude Agent SDK (and Codex) already discover guide files by walking
+* UP from the agent's working directory — but that misses a nested guide
+* sitting *below* the worktree/project root, right next to the clicked
+* file. That nested guide is exactly the one most relevant to the edit, so
+* we resolve it explicitly here and inject it into the system prompt.
+*/
+/**
+* Guide filenames we recognise. `CLAUDE.md` is Claude's convention and
+* `AGENTS.md` is the cross-agent (Codex, etc.) one; both are checked at
+* each directory so whichever a project uses is found.
+*/
+const GUIDE_FILENAMES = ["CLAUDE.md", "AGENTS.md"];
+/**
+* Hard cap on injected guide bytes. A sprawling guide shouldn't crowd out
+* the actual task in the prompt; past this we truncate with a marker.
+*/
+const MAX_GUIDE_BYTES = 16e3;
+/**
+* Find the guide file nearest to `file`, searching its own directory first
+* and walking up to (and including) `projectRoot`. Returns `null` when the
+* feedback has no file, the path escapes the project, or no guide exists
+* anywhere on the path.
+*/
+function findNearestAgentGuide(file, projectRoot, opts = {}) {
+	if (!file) return null;
+	const root = resolve(projectRoot);
+	const absFile = isAbsolute(file) ? resolve(file) : resolve(root, file);
+	if (!isWithin(root, absFile)) return null;
+	const order = guideOrder(opts.prefer);
+	let dir = dirname(absFile);
+	while (true) {
+		for (const filename of order) {
+			const guidePath = resolve(dir, filename);
+			const content = tryRead(guidePath);
+			if (content !== null) {
+				const clipped = clip(content);
+				return {
+					filename,
+					relativePath: toPosix(relative(root, guidePath)),
+					content: clipped.content,
+					truncated: clipped.truncated
+				};
+			}
+		}
+		if (dir === root) break;
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return null;
+}
+/**
+* Render a found guide as a block to append to the agent's system prompt
+* (or, for a wrapped CLI with no system prompt, its task prompt). Framed so
+* the agent knows the guidance is scoped to the file it's editing.
+*/
+function renderAgentGuide(guide) {
+	return [
+		"",
+		`Project guidance applies to the code you're editing. The nearest guide to`,
+		`the clicked element is \`${guide.relativePath}\` — follow it${guide.truncated ? " (truncated below; read the full file if you need more)" : ""}:`,
+		"",
+		`<project-guidance path="${guide.relativePath}">`,
+		guide.content,
+		"</project-guidance>"
+	].join("\n");
+}
+/** Order the filenames so the preferred one is checked first at each dir. */
+function guideOrder(prefer) {
+	if (!prefer || prefer === GUIDE_FILENAMES[0]) return GUIDE_FILENAMES;
+	return [prefer, ...GUIDE_FILENAMES.filter((f) => f !== prefer)];
+}
+/** Read a file as UTF-8, returning null for any read error (missing, dir, …). */
+function tryRead(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return null;
+	}
+}
+/** True when `child` is `parent` or sits inside it. */
+function isWithin(parent, child) {
+	if (child === parent) return true;
+	const rel = relative(parent, child);
+	return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+/** Clip content to the byte cap on a line boundary, with a marker. */
+function clip(content) {
+	if (Buffer.byteLength(content, "utf8") <= MAX_GUIDE_BYTES) return {
+		content,
+		truncated: false
+	};
+	let sliced = content.slice(0, MAX_GUIDE_BYTES);
+	while (Buffer.byteLength(sliced, "utf8") > MAX_GUIDE_BYTES - 32) sliced = sliced.slice(0, -32);
+	const lastNl = sliced.lastIndexOf("\n");
+	if (lastNl > 0) sliced = sliced.slice(0, lastNl);
+	return {
+		content: `${sliced}\n\n… [truncated]`,
+		truncated: true
+	};
+}
+/** Normalise path separators to POSIX for stable prompt/display output. */
+function toPosix(path) {
+	return path.split(/[\\/]/).join("/");
+}
+/**
+* Render a single SDK message as a markdown fragment to append to the log.
+*
+* Returns '' for messages we don't surface (status pings, partial deltas,
+* etc.) so the caller can no-op cheaply.
+*
+* The aim is a readable transcript, not a raw event dump — text comes
+* through as plain markdown, tool calls collapse to a single-line chip,
+* errors stand out. If a new SDK message type arrives we don't recognise,
+* we drop it silently rather than serialising a JSON blob into the log.
+*/
+function renderMessage(message) {
+	switch (message.type) {
+		case "assistant": return renderAssistant(message);
+		case "result": return "\n---\n";
+		case "user": return renderUser(message);
+		default: return "";
+	}
+}
+function renderInitFooter(message) {
+	const mcp = message.mcp_servers.map((s) => `${s.name}=${s.status}`).join(", ");
+	const lines = [`> _session_ \`${message.session_id}\` · model \`${message.model}\` · ${message.permissionMode}`];
+	if (mcp) lines.push(`> _mcp_ ${mcp}`);
+	lines.push("");
+	return `${lines.join("\n")}\n`;
+}
+function renderResultFooter(result, apiKeySource) {
+	const lines = [];
+	if (result.subtype === "success") lines.push(`**Outcome:** success (${result.num_turns} turn${result.num_turns === 1 ? "" : "s"})`);
+	else {
+		lines.push(`**Outcome:** \`${result.subtype}\``);
+		if (result.errors?.length) {
+			lines.push("");
+			for (const e of result.errors) lines.push(`> ${e}`);
+		}
+	}
+	lines.push(`**Tokens:** in=${result.usage.input_tokens} · out=${result.usage.output_tokens}${result.usage.cache_read_input_tokens ? ` · cache_read=${result.usage.cache_read_input_tokens}` : ""}${result.usage.cache_creation_input_tokens ? ` · cache_write=${result.usage.cache_creation_input_tokens}` : ""}`);
+	lines.push(isNotionalCost(apiKeySource) ? `**Cost:** ≈$${result.total_cost_usd.toFixed(4)} API-equivalent (subscription — not billed)` : `**Cost:** $${result.total_cost_usd.toFixed(4)}`);
+	lines.push(`**Duration:** ${(result.duration_ms / 1e3).toFixed(1)}s`);
+	return lines.join("  \n");
+}
+function renderAssistant(message) {
+	const blocks = message.message.content;
+	if (!Array.isArray(blocks)) return "";
+	const out = [];
+	for (const block of blocks) if (block.type === "text" && block.text.trim()) out.push(`${block.text}\n`);
+	else if (block.type === "tool_use") out.push(renderToolUse(block.name, block.input));
+	else if (block.type === "thinking") out.push("<!-- thinking -->\n");
+	if (message.error) out.push(`\n> ⚠️  assistant error: \`${message.error}\`\n`);
+	if (out.length === 0) return "";
+	return `${out.join("\n")}\n`;
+}
+function renderUser(message) {
+	const content = message.message?.content;
+	if (!Array.isArray(content)) return "";
+	const chips = [];
+	for (const block of content) if (block.type === "tool_result") chips.push(renderToolResult(block));
+	if (chips.length === 0) return "";
+	return `${chips.join("\n")}\n`;
+}
+function renderToolUse(name, input) {
+	const summary = summariseToolInput(name, input);
+	return `\`[${name}]\`${summary ? ` ${summary}` : ""}\n`;
+}
+function renderToolResult(block) {
+	return `${block.is_error ? "✗" : "✓"} _tool result_`;
+}
+function summariseToolInput(name, input) {
+	if (input == null || typeof input !== "object") return "";
+	const obj = input;
+	for (const f of [
+		"file_path",
+		"path",
+		"filePath",
+		"notebook_path"
+	]) if (typeof obj[f] === "string") return `\`${obj[f]}\``;
+	if (typeof obj.command === "string") return `\`${truncate(obj.command, 80)}\``;
+	if (typeof obj.pattern === "string") return `pattern=\`${truncate(obj.pattern, 60)}\``;
+	if (typeof obj.url === "string") return obj.url;
+	if (typeof obj.prompt === "string") return `\`${truncate(obj.prompt, 60)}\``;
+	if (name.startsWith("mcp__")) {
+		const keys = Object.keys(obj);
+		const first = keys[0];
+		if (keys.length === 1 && first != null && typeof obj[first] !== "object") return `${first}=\`${String(obj[first])}\``;
+	}
+	return "";
+}
+function truncate(s, n) {
+	if (s.length <= n) return s;
+	return `${s.slice(0, n - 1)}…`;
+}
+/**
+* @pinagent/mcp tool names the spawned agent needs to do its job:
+*
+* - `get_feedback`         — fetch the full feedback record incl. screenshot
+* - `resolve_feedback`     — mark fixed/wontfix/deferred when done
+* - `get_source_context`   — read a window of source around file:line
+* - `list_pending_feedback`— rarely needed by a spawned agent (it knows its
+*                            own id), included for parity with pull mode
+*
+* They are surfaced to the SDK via the user's `.mcp.json` (loaded by
+* `settingSources: ['user', 'project', 'local']`). Allowlisting them
+* makes the spawned agent auto-accept the calls instead of timing out
+* waiting for a non-existent permission prompt.
+*/
+const PINAGENT_MCP_TOOLS = [
+	"mcp__pinagent__get_feedback",
+	"mcp__pinagent__resolve_feedback",
+	"mcp__pinagent__get_source_context",
+	"mcp__pinagent__list_pending_feedback"
+];
+/**
+* Tools a dry-run must never be allowed to call: anything that writes to
+* the workspace, runs a command, or transitions the agent out of plan
+* mode. See `buildSdkOptions` for why denying `ExitPlanMode` is the load-
+* bearing entry — without it a headless `plan`-mode run silently writes.
+*/
+const DRY_RUN_DENIED_TOOLS = new Set([
+	"ExitPlanMode",
+	"Edit",
+	"MultiEdit",
+	"Write",
+	"NotebookEdit",
+	"Bash"
+]);
+/**
+* The default, most capable provider: the Claude Agent SDK. Runs the full
+* agentic loop (tool calls, edits, permission gating, session resume) and
+* streams its `SDKMessage`s, which we normalize into Pinagent's
+* `AgentEvent` union here so nothing downstream has to know it was Claude.
+*/
+var ClaudeCodeProvider = class {
+	id = "claude-code";
+	async *run(req) {
+		const sdkOptions = await buildSdkOptions(req);
+		const startedAt = Date.now();
+		let apiKeySource = null;
+		let turn = 0;
+		let sawResult = false;
+		try {
+			for await (const message of query({
+				prompt: req.prompt,
+				options: sdkOptions
+			})) {
+				const sessionId = "session_id" in message && typeof message.session_id === "string" ? message.session_id : void 0;
+				if (message.type === "system" && message.subtype === "init") {
+					apiKeySource = message.apiKeySource ?? null;
+					yield {
+						events: toAgentEvents(message),
+						log: renderInitFooter(message),
+						sessionId
+					};
+					continue;
+				}
+				if (message.type === "result") {
+					sawResult = true;
+					yield {
+						events: toAgentEvents(message),
+						log: renderMessage(message),
+						sessionId,
+						isResult: true,
+						resultFooter: renderResultFooter(message, apiKeySource)
+					};
+					continue;
+				}
+				const events = toAgentEvents(message);
+				if (message.type === "assistant") {
+					turn += 1;
+					events.push({
+						type: "progress",
+						turn
+					});
+				}
+				yield {
+					events,
+					log: renderMessage(message),
+					sessionId
+				};
+			}
+		} catch (err) {
+			if (sawResult) return;
+			const aborted = req.abortSignal.aborted;
+			const detail = err instanceof Error ? err.message : String(err);
+			const durationMs = Date.now() - startedAt;
+			const resultEvent = {
+				type: "result",
+				subtype: aborted ? "aborted" : "error",
+				numTurns: turn,
+				totalCostUsd: 0,
+				durationMs
+			};
+			const events = [];
+			const seconds = `${(durationMs / 1e3).toFixed(1)}s`;
+			let footer;
+			if (aborted) footer = `**Outcome:** \`aborted\`  \n**Duration:** ${seconds}`;
+			else {
+				resultEvent.errors = [detail];
+				events.push({
+					type: "error",
+					message: detail
+				});
+				footer = `**Outcome:** \`error\`  \n> ${detail}  \n**Duration:** ${seconds}`;
+			}
+			events.push(resultEvent);
+			yield {
+				events,
+				log: `\n> [pinagent] ${aborted ? "run aborted by user" : `agent stream errored: ${detail}`}\n`,
+				isResult: true,
+				resultFooter: footer
+			};
+		}
+	}
+};
+/**
+* Build the Claude Agent SDK options for a run. Kept byte-for-byte
+* equivalent to the original inline construction in `agent.ts` so the
+* SDK-mocking tests (which assert on the params handed to `query()`)
+* continue to pass unchanged.
+*/
+async function buildSdkOptions(req) {
+	const env = await buildSdkAuthEnv(req.projectRoot, {
+		PINAGENT_PROJECT_ROOT: req.projectRoot,
+		CLAUDE_CODE_STREAM_CLOSE_TIMEOUT: "720000"
+	});
+	const guide = findNearestAgentGuide(req.targetFile, req.projectRoot, { prefer: "CLAUDE.md" });
+	const options = {
+		cwd: req.cwd,
+		permissionMode: req.permissionMode,
+		env,
+		settingSources: [
+			"user",
+			"project",
+			"local"
+		],
+		abortController: toAbortController(req.abortSignal),
+		mcpServers: { "pinagent-ask-user": createAskUserMcpServer(req.feedbackId) },
+		allowedTools: [ASK_USER_TOOL_NAME, ...PINAGENT_MCP_TOOLS],
+		systemPrompt: {
+			type: "preset",
+			preset: "claude_code",
+			append: [
+				"",
+				"You are running inside Pinagent, a tool that lets developers click a UI",
+				"element in the browser and leave a comment for you to act on. The user",
+				"is watching your output stream into a small widget pane next to the",
+				"element they clicked.",
+				"",
+				`If you need clarification mid-task, call the \`${ASK_USER_TOOL_NAME}\``,
+				"tool with a clear question (and optional `options` for closed-ended",
+				"answers). Prefer asking over guessing on ambiguous requirements.",
+				...guide ? [renderAgentGuide(guide)] : []
+			].join("\n")
+		}
+	};
+	if (req.permissionMode === "plan") options.canUseTool = async (toolName) => DRY_RUN_DENIED_TOOLS.has(toolName) ? {
+		behavior: "deny",
+		message: `Dry-run mode: \`${toolName}\` is blocked. Pinagent is in dry-run (plan) mode — describe the change you would make, but do not edit files, run commands, or exit plan mode.`
+	} : { behavior: "allow" };
+	if (req.resume) options.resume = req.resume;
+	return options;
+}
+/**
+* The SDK wants an `AbortController`, but the provider contract hands us a
+* bare `AbortSignal` (so non-SDK providers aren't forced to fabricate a
+* controller). Bridge the two by forwarding the signal's abort to a fresh
+* controller the SDK can own.
+*/
+function toAbortController(signal) {
+	const controller = new AbortController();
+	if (signal.aborted) controller.abort();
+	else signal.addEventListener("abort", () => controller.abort(), { once: true });
+	return controller;
+}
+/** Translate one SDK message into zero or more Pinagent bus events. */
+function toAgentEvents(message) {
+	switch (message.type) {
+		case "system":
+			if (message.subtype === "init") return [{
+				type: "init",
+				sessionId: message.session_id,
+				model: message.model,
+				permissionMode: message.permissionMode,
+				apiKeySource: message.apiKeySource
+			}];
+			return [];
+		case "assistant": {
+			const out = [];
+			const blocks = message.message?.content;
+			if (!Array.isArray(blocks)) return out;
+			for (const block of blocks) if (block.type === "text" && block.text.trim()) out.push({
+				type: "text",
+				text: block.text
+			});
+			else if (block.type === "tool_use") {
+				if (block.name === "mcp__pinagent-ask-user__ask_user") continue;
+				out.push({
+					type: "tool_use",
+					name: block.name,
+					summary: summariseToolInput(block.name, block.input)
+				});
+			}
+			if (message.error) out.push({
+				type: "error",
+				message: `assistant error: ${message.error}`
+			});
+			return out;
+		}
+		case "user": {
+			const out = [];
+			const blocks = message.message?.content;
+			if (!Array.isArray(blocks)) return out;
+			for (const block of blocks) if (typeof block === "object" && block !== null && block.type === "tool_result") out.push({
+				type: "tool_result",
+				ok: !block.is_error
+			});
+			return out;
+		}
+		case "result": {
+			const event = {
+				type: "result",
+				subtype: message.subtype,
+				numTurns: message.num_turns,
+				totalCostUsd: message.total_cost_usd,
+				durationMs: message.duration_ms
+			};
+			if (message.subtype !== "success" && Array.isArray(message.errors)) event.errors = message.errors;
+			return [event];
+		}
+		default: return [];
+	}
+}
+/**
+* Bring-your-own-model provider: wrap an arbitrary agentic CLI (Codex,
+* aider, opencode, Cline headless, a shell script, …) and translate its
+* stdout into Pinagent's `AgentEvent` stream.
+*
+* The wrapped CLI owns its own agentic loop and edits files directly in
+* `req.cwd`. We don't intercept its tool calls — we surface its narration
+* to the widget and let its on-disk edits land in the project (or
+* worktree) exactly as the Claude provider's edits do.
+*
+* Configuration (env, read per-run so a dev-server restart isn't needed):
+*
+* - `PINAGENT_AGENT_CLI_COMMAND`  (required) the command to run. Either a
+*   JSON array (`["aider","--yes-always"]`) or a space-separated string
+*   (`aider --yes-always`). The first element is the executable.
+* - `PINAGENT_AGENT_CLI_PROMPT`   `arg` (default) appends the prompt as the
+*   final argv; `stdin` writes it to the child's stdin and closes it.
+* - `PINAGENT_AGENT_CLI_FORMAT`   `text` (default) treats each stdout line
+*   as assistant text; `stream-json` parses each line as JSON and maps a
+*   pragmatic subset of common agent event shapes.
+* - `PINAGENT_AGENT_CLI_MODEL`    label for the `init` event (defaults to
+*   the executable name). Cosmetic — drives the widget's model chip.
+*
+* The child inherits the parent env plus `PINAGENT_PROJECT_ROOT`,
+* `PINAGENT_FEEDBACK_ID`, and `PINAGENT_RESUME_SESSION` so an MCP-aware
+* CLI (or a wrapper script) can connect to the pinagent MCP server, fetch
+* the feedback, and call `resolve_feedback` itself.
+*
+* Auth is explicit-only (see agent-auth.ts): `buildCliAuthEnv` strips any
+* ambient `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` from the child's env so a
+* stray shell key can't bill against a wrapped CLI by accident, and re-supplies
+* a key only when the consuming app passed one via the `apiKey` plugin option.
+* Absent that, the CLI falls back to its own login (e.g. Codex → the ChatGPT
+* subscription).
+*/
+var CliAgentProvider = class {
+	id = "cli";
+	async *run(req) {
+		const config = resolveCliConfig(process.env);
+		const sessionId = req.resume ?? nanoid(12);
+		const startedAt = Date.now();
+		yield {
+			events: [{
+				type: "init",
+				sessionId,
+				model: config.model,
+				permissionMode: req.permissionMode,
+				apiKeySource: "cli"
+			}],
+			log: `> _cli_ \`${config.argv.join(" ")}\` · session \`${sessionId}\`\n\n`,
+			sessionId
+		};
+		const guide = findNearestAgentGuide(req.targetFile, req.projectRoot, { prefer: "AGENTS.md" });
+		const prompt = guide ? `${req.prompt}\n${renderAgentGuide(guide)}` : req.prompt;
+		const args = [...config.argv.slice(1)];
+		if (config.promptMode === "arg") args.push(prompt);
+		const child = spawn(config.argv[0], args, {
+			cwd: req.cwd,
+			env: buildCliAuthEnv({
+				PINAGENT_PROJECT_ROOT: req.projectRoot,
+				PINAGENT_FEEDBACK_ID: req.feedbackId,
+				PINAGENT_RESUME_SESSION: req.resume ?? ""
+			}),
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		const onAbort = () => child.kill("SIGTERM");
+		if (req.abortSignal.aborted) onAbort();
+		else req.abortSignal.addEventListener("abort", onAbort, { once: true });
+		child.stdin.on("error", () => {});
+		try {
+			if (config.promptMode === "stdin") child.stdin.write(prompt);
+			child.stdin.end();
+		} catch {}
+		const queue = new AsyncLineQueue();
+		const stdout = createInterface({ input: child.stdout });
+		const stderr = createInterface({ input: child.stderr });
+		stdout.on("line", (line) => queue.push({
+			line,
+			stream: "stdout"
+		}));
+		stderr.on("line", (line) => queue.push({
+			line,
+			stream: "stderr"
+		}));
+		let openStreams = 2;
+		const onClose = () => {
+			openStreams -= 1;
+			if (openStreams === 0) queue.close();
+		};
+		stdout.on("close", onClose);
+		stderr.on("close", onClose);
+		const exit = new Promise((resolve) => {
+			child.on("exit", (code, signal) => resolve({
+				code,
+				signal,
+				spawnError: null
+			}));
+			child.on("error", (err) => resolve({
+				code: null,
+				signal: null,
+				spawnError: err instanceof Error ? err : new Error(String(err))
+			}));
+		});
+		let turn = 0;
+		for await (const { line, stream } of queue) {
+			const events = stream === "stderr" ? parseTextLine(line, stream) : config.format === "stream-json" ? parseStreamJsonLine(line) : parseTextLine(line, stream);
+			if (events.length === 0) continue;
+			if (stream === "stdout" && events.some((e) => e.type === "text")) {
+				turn += 1;
+				events.push({
+					type: "progress",
+					turn
+				});
+			}
+			yield {
+				events,
+				log: renderCliLine(line, stream)
+			};
+		}
+		req.abortSignal.removeEventListener("abort", onAbort);
+		const { code, signal, spawnError } = await exit;
+		const aborted = req.abortSignal.aborted;
+		const subtype = aborted ? "aborted" : spawnError || signal || code !== 0 ? "error" : "success";
+		const resultEvent = {
+			type: "result",
+			subtype,
+			numTurns: turn,
+			totalCostUsd: 0,
+			durationMs: Date.now() - startedAt
+		};
+		if (subtype !== "success") {
+			let reason;
+			if (aborted) reason = "run aborted";
+			else if (spawnError) reason = `failed to start ${config.argv[0]}: ${spawnError.message}`;
+			else if (signal) reason = `${config.argv[0]} terminated by signal ${signal}`;
+			else reason = `${config.argv[0]} exited with code ${code}`;
+			resultEvent.errors = [reason];
+		}
+		yield {
+			events: [resultEvent],
+			log: "\n---\n",
+			isResult: true,
+			resultFooter: renderCliFooter(subtype, turn, Date.now() - startedAt)
+		};
+	}
+};
+/** Parse the CLI provider config out of the environment, validating it. */
+function resolveCliConfig(env) {
+	const raw = env.PINAGENT_AGENT_CLI_COMMAND?.trim();
+	if (!raw) throw new Error("PINAGENT_AGENT_CLI_COMMAND is required when PINAGENT_AGENT_PROVIDER=cli. Set it to the agent CLI to run, e.g. PINAGENT_AGENT_CLI_COMMAND='[\"aider\",\"--yes-always\"]'.");
+	let argv;
+	if (raw.startsWith("[")) try {
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed) || parsed.some((a) => typeof a !== "string")) throw new Error("not a string array");
+		argv = parsed;
+	} catch (err) {
+		throw new Error(`PINAGENT_AGENT_CLI_COMMAND looked like JSON but failed to parse as a string array: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	else argv = raw.split(/\s+/).filter(Boolean);
+	if (argv.length === 0) throw new Error("PINAGENT_AGENT_CLI_COMMAND resolved to an empty command");
+	const promptMode = env.PINAGENT_AGENT_CLI_PROMPT === "stdin" ? "stdin" : "arg";
+	const format = env.PINAGENT_AGENT_CLI_FORMAT === "stream-json" ? "stream-json" : "text";
+	const model = env.PINAGENT_AGENT_CLI_MODEL?.trim() || argv[0];
+	return {
+		argv,
+		promptMode,
+		format,
+		model
+	};
+}
+/** Plain-text mode: every non-blank line is assistant narration. */
+function parseTextLine(line, stream) {
+	if (!line.trim()) return [];
+	return [{
+		type: "text",
+		text: stream === "stderr" ? `[stderr] ${line}` : line
+	}];
+}
+/**
+* stream-json mode: best-effort mapping of the common shapes emitted by
+* agentic CLIs. Unknown/unparseable lines fall back to raw text so output
+* is never silently dropped.
+*/
+function parseStreamJsonLine(line) {
+	const trimmed = line.trim();
+	if (!trimmed) return [];
+	let obj;
+	try {
+		obj = JSON.parse(trimmed);
+	} catch {
+		return [{
+			type: "text",
+			text: line
+		}];
+	}
+	if (obj == null || typeof obj !== "object") return [{
+		type: "text",
+		text: line
+	}];
+	const o = obj;
+	const direct = pickString(o.text) ?? pickString(o.content) ?? pickString(o.delta) ?? deltaText(o.delta);
+	if (direct) return [{
+		type: "text",
+		text: direct
+	}];
+	const message = o.message;
+	if (message && typeof message === "object") {
+		const blocks = message.content;
+		if (Array.isArray(blocks)) return blocksToEvents(blocks);
+	}
+	if (Array.isArray(o.content)) return blocksToEvents(o.content);
+	const type = pickString(o.type);
+	if ((type === "tool_use" || type === "tool_call") && typeof o.name === "string") return [{
+		type: "tool_use",
+		name: o.name,
+		summary: summariseToolInput(o.name, o.input)
+	}];
+	return [{
+		type: "text",
+		text: line
+	}];
+}
+function blocksToEvents(blocks) {
+	const out = [];
+	for (const block of blocks) {
+		if (block == null || typeof block !== "object") continue;
+		const b = block;
+		if (b.type === "text" && typeof b.text === "string" && b.text.trim()) out.push({
+			type: "text",
+			text: b.text
+		});
+		else if ((b.type === "tool_use" || b.type === "tool_call") && typeof b.name === "string") out.push({
+			type: "tool_use",
+			name: b.name,
+			summary: summariseToolInput(b.name, b.input)
+		});
+		else if (b.type === "tool_result") out.push({
+			type: "tool_result",
+			ok: !b.is_error
+		});
+	}
+	return out;
+}
+function pickString(v) {
+	return typeof v === "string" && v.trim() ? v : null;
+}
+function deltaText(v) {
+	if (v && typeof v === "object") return pickString(v.text);
+	return null;
+}
+function renderCliLine(line, stream) {
+	if (!line.trim()) return "";
+	return stream === "stderr" ? `> \`${line}\`\n` : `${line}\n`;
+}
+function renderCliFooter(subtype, turns, durationMs) {
+	return [
+		subtype === "success" ? `**Outcome:** success (${turns} chunk${turns === 1 ? "" : "s"})` : `**Outcome:** \`${subtype}\``,
+		"**Cost:** n/a (external CLI)",
+		`**Duration:** ${(durationMs / 1e3).toFixed(1)}s`
+	].join("  \n");
+}
+/**
+* Minimal async iterable backed by a push queue. `readline` is push-based
+* (`'line'` events) but our provider is pull-based (`for await`), so this
+* buffers lines until the consumer asks for them and resolves cleanly when
+* the underlying streams close.
+*/
+var AsyncLineQueue = class {
+	buffer = [];
+	resolvers = [];
+	done = false;
+	push(item) {
+		if (this.done) return;
+		const resolve = this.resolvers.shift();
+		if (resolve) resolve({
+			value: item,
+			done: false
+		});
+		else this.buffer.push(item);
+	}
+	close() {
+		this.done = true;
+		for (const resolve of this.resolvers.splice(0)) resolve({
+			value: void 0,
+			done: true
+		});
+	}
+	[Symbol.asyncIterator]() {
+		return { next: () => {
+			const item = this.buffer.shift();
+			if (item) return Promise.resolve({
+				value: item,
+				done: false
+			});
+			if (this.done) return Promise.resolve({
+				value: void 0,
+				done: true
+			});
+			return new Promise((resolve) => this.resolvers.push(resolve));
+		} };
+	}
+};
+/**
+* Resolve which agent backend a run should use. Precedence:
+*   `PINAGENT_AGENT_PROVIDER` env > default (`claude-code`).
+*
+* Defaulting to `claude-code` keeps every existing setup working with no
+* config; "bring your own model" is opt-in via the env var.
+*/
+function resolveProviderId(env) {
+	if (env.PINAGENT_AGENT_PROVIDER?.trim().toLowerCase() === "cli") return "cli";
+	return "claude-code";
+}
+/** Instantiate the provider for an id. */
+function createProvider(id) {
+	switch (id) {
+		case "cli": return new CliAgentProvider();
+		default: return new ClaudeCodeProvider();
+	}
+}
+/** Convenience: resolve the provider straight from the environment. */
+function resolveProvider(env = process.env) {
+	return createProvider(resolveProviderId(env));
+}
+/**
+* Bus event roles that shouldn't count toward "transcript depth". The
+* `__finished` sentinel comes from `bus.ts` and isn't a real event;
+* `init` and `result` are agent-run bookkeeping the user-facing badge
+* shouldn't include. Anything else (text / tool_use / tool_result /
+* ask_user / error / user / ask_response) counts.
+*/
+const NON_MESSAGE_ROLES = [
+	"__finished",
+	"init",
+	"result"
+];
+const ID_RE = /^[A-Za-z0-9_-]{8,16}$/;
+/** Per-extra anchor in the multi-pick payload — flat fields mirroring
+* the primary widget_anchors columns, minus viewport/userAgent (those
+* are conversation-level). */
+const AdditionalAnchorSchema = z.object({
+	file: z.string().max(512).nullable(),
+	line: z.number().int().min(1).max(1e6).nullable(),
+	col: z.number().int().min(0).max(1e6).nullable(),
+	selector: z.string().max(2e3),
+	clickX: z.number().int().min(-1e6).max(1e6),
+	clickY: z.number().int().min(-1e6).max(1e6),
+	/** Enclosing component name for this extra pick, when instrumented. */
+	component: z.string().max(256).nullable().optional()
+});
+/**
+* Loop-instance disambiguation captured at pick time. Present only when
+* the target's `data-pa-loc` is shared by more than one live element (a
+* `.map()`), so the agent can tell which item was clicked.
+*/
+const InstanceInfoSchema = z.object({
+	index: z.number().int().min(0).max(1e6),
+	total: z.number().int().min(1).max(1e6),
+	fingerprint: z.string().max(512)
+});
+const FeedbackInputSchema = z.object({
+	comment: z.string().min(1).max(8e3),
+	loc: z.object({
+		file: z.string().min(1).max(512),
+		line: z.number().int().min(1).max(1e6),
+		col: z.number().int().min(0).max(1e6)
+	}).nullable(),
+	selector: z.string().max(2e3),
+	url: z.string().max(2048),
+	viewport: z.object({
+		w: z.number().int().min(1),
+		h: z.number().int().min(1)
+	}),
+	userAgent: z.string().max(1024),
+	screenshot: z.string().min(1),
+	createdAt: z.string().min(1),
+	/**
+	* Cmd/Ctrl-click extras queued before the committing click. Optional
+	* for backward compatibility with single-pick clients; capped at 32
+	* to keep a runaway client from blowing up the JSON column.
+	*/
+	additionalAnchors: z.array(AdditionalAnchorSchema).max(32).optional(),
+	/**
+	* Enclosing-component context from `data-pa-comp`. All optional for
+	* backward compatibility with clients that predate the attribute.
+	*/
+	component: z.string().max(256).nullable().optional(),
+	componentPath: z.array(z.string().max(256)).max(16).optional(),
+	instance: InstanceInfoSchema.nullable().optional()
+});
+const StatusSchema = z.enum([
+	"pending",
+	"fixed",
+	"wontfix",
+	"deferred"
+]);
+const WorktreeStateSchema = z.enum([
+	"none",
+	"active",
+	"landed",
+	"discarded"
+]);
+z.object({
+	status: StatusSchema.optional(),
+	note: z.string().max(8e3).nullable().optional(),
+	commitSha: z.string().max(64).nullable().optional(),
+	agentSessionId: z.string().max(128).nullable().optional(),
+	branch: z.string().max(256).nullable().optional(),
+	worktreePath: z.string().max(1024).nullable().optional(),
+	worktreeState: WorktreeStateSchema.optional(),
+	/**
+	* Title override. Pass an empty string or `null` to clear back to the
+	* comment-derived title. Capped at 200 chars so the list rows don't
+	* blow up.
+	*/
+	title: z.string().max(200).nullable().optional(),
+	archived: z.boolean().optional()
+});
+/**
+* Server-side feedback storage. Backed by SQLite via Drizzle on the
+* shared `@pinagent/db` schema; screenshots stay on disk as PNG files
+* under `.pinagent/screenshots/` because they're large binary blobs.
+*
+* The class deliberately preserves the v1 `FeedbackRecord` shape and
+* method names so the MCP server, route handler, and agent code don't
+* need to change. Internally it joins `conversations` and
+* `widget_anchors` on every read.
+*
+* On first open, any legacy `.pinagent/feedback/<id>.json` files are
+* imported into SQLite (and left on disk as a backup). Once they're in
+* the DB, subsequent reads come from SQLite.
+*/
+var Storage = class {
+	root;
+	feedbackDir;
+	screenshotsDir;
+	legacyImportDone = false;
+	constructor(root) {
+		this.root = root;
+		this.feedbackDir = join(root, ".pinagent", "feedback");
+		this.screenshotsDir = join(root, ".pinagent", "screenshots");
+	}
+	db() {
+		return getDb(this.root);
+	}
+	async ensureDirs() {
+		await mkdir(this.screenshotsDir, { recursive: true });
+	}
+	/**
+	* One-shot import of legacy JSON feedback records into SQLite.
+	* Safe to call multiple times — uses ON CONFLICT DO NOTHING so
+	* already-imported rows aren't overwritten.
+	*/
+	async maybeImportLegacy() {
+		if (this.legacyImportDone) return;
+		this.legacyImportDone = true;
+		if (!existsSync(this.feedbackDir)) return;
+		try {
+			const names = await readdir(this.feedbackDir);
+			for (const n of names) {
+				if (!n.endsWith(".json") || n.endsWith(".tmp")) continue;
+				const id = n.slice(0, -5);
+				if (!ID_RE.test(id)) continue;
+				try {
+					const raw = await readFile(join(this.feedbackDir, n), "utf8");
+					const rec = JSON.parse(raw);
+					if (!rec.id || !rec.comment) continue;
+					await this.insertRecord(rec);
+				} catch {}
+			}
+		} catch {}
+	}
+	async insertRecord(rec) {
+		const db = this.db();
+		await db.insert(conversations).values({
+			id: rec.id,
+			comment: rec.comment,
+			agentSessionId: rec.agentSessionId ?? null,
+			status: rec.status,
+			note: rec.note ?? null,
+			commitSha: rec.commitSha ?? null,
+			createdAt: parseDate(rec.createdAt),
+			updatedAt: parseDate(rec.createdAt),
+			resolvedAt: rec.resolvedAt ? parseDate(rec.resolvedAt) : null
+		}).onConflictDoNothing();
+		await db.insert(widgetAnchors).values({
+			conversationId: rec.id,
+			url: rec.url,
+			file: rec.file,
+			line: rec.line,
+			col: rec.col,
+			selector: rec.selector,
+			viewportW: rec.viewport.w,
+			viewportH: rec.viewport.h,
+			userAgent: rec.userAgent,
+			component: rec.component,
+			componentPath: rec.componentPath,
+			instanceIndex: rec.instanceIndex,
+			instanceTotal: rec.instanceTotal,
+			instanceFingerprint: rec.instanceFingerprint,
+			additionalAnchors: rec.additionalAnchors
+		}).onConflictDoNothing();
+	}
+	async create(id, input) {
+		await this.ensureDirs();
+		const pngBuf = Buffer$1.from(input.screenshot, "base64");
+		const pngRel = join("screenshots", `${id}.png`);
+		const pngAbs = join(this.root, ".pinagent", pngRel);
+		await this.atomicWriteBytes(pngAbs, pngBuf);
+		const db = this.db();
+		const createdAt = parseDate(input.createdAt);
+		await db.insert(conversations).values({
+			id,
+			comment: input.comment,
+			status: "pending",
+			createdAt,
+			updatedAt: createdAt
+		});
+		const componentPath = input.componentPath && input.componentPath.length > 0 ? input.componentPath : null;
+		await db.insert(widgetAnchors).values({
+			conversationId: id,
+			url: input.url,
+			file: input.loc?.file ?? null,
+			line: input.loc?.line ?? null,
+			col: input.loc?.col ?? null,
+			selector: input.selector,
+			viewportW: input.viewport.w,
+			viewportH: input.viewport.h,
+			userAgent: input.userAgent,
+			component: input.component ?? null,
+			componentPath,
+			instanceIndex: input.instance?.index ?? null,
+			instanceTotal: input.instance?.total ?? null,
+			instanceFingerprint: input.instance?.fingerprint ?? null,
+			additionalAnchors: input.additionalAnchors && input.additionalAnchors.length > 0 ? input.additionalAnchors : null
+		});
+		const record = {
+			id,
+			comment: input.comment,
+			file: input.loc?.file ?? null,
+			line: input.loc?.line ?? null,
+			col: input.loc?.col ?? null,
+			selector: input.selector,
+			url: input.url,
+			viewport: input.viewport,
+			userAgent: input.userAgent,
+			additionalAnchors: input.additionalAnchors && input.additionalAnchors.length > 0 ? input.additionalAnchors : null,
+			component: input.component ?? null,
+			componentPath,
+			instanceIndex: input.instance?.index ?? null,
+			instanceTotal: input.instance?.total ?? null,
+			instanceFingerprint: input.instance?.fingerprint ?? null,
+			screenshot: pngRel,
+			status: "pending",
+			note: null,
+			commitSha: null,
+			agentSessionId: null,
+			branch: null,
+			worktreePath: null,
+			worktreeState: "none",
+			title: null,
+			archived: false,
+			createdAt: input.createdAt,
+			updatedAt: input.createdAt,
+			resolvedAt: null,
+			messageCount: 0,
+			totalCostUsd: 0,
+			apiKeySource: null,
+			isRunning: false
+		};
+		emitProjectChange({ type: "conversations_changed" });
+		await recordAuditEvent(this.root, {
+			conversationId: id,
+			actor: "user",
+			action: "conversation_created",
+			payload: {
+				page: input.url,
+				...input.loc?.file ? { file: input.loc.file } : {}
+			}
+		});
+		return record;
+	}
+	async list() {
+		await this.maybeImportLegacy();
+		const db = this.db();
+		const rows = await db.select().from(conversations).leftJoin(widgetAnchors, eq$1(conversations.id, widgetAnchors.conversationId)).orderBy(asc$1(conversations.createdAt));
+		const counts = await db.select({
+			id: messages.conversationId,
+			n: count()
+		}).from(messages).where(notInArray(messages.role, NON_MESSAGE_ROLES)).groupBy(messages.conversationId);
+		const countByConvId = new Map(counts.map((c) => [c.id, c.n]));
+		const costRows = await db.select({
+			id: messages.conversationId,
+			content: messages.content
+		}).from(messages).where(eq$1(messages.role, "result"));
+		const costByConvId = /* @__PURE__ */ new Map();
+		for (const r of costRows) {
+			const c = extractResultCost(r.content);
+			if (c > 0) costByConvId.set(r.id, (costByConvId.get(r.id) ?? 0) + c);
+		}
+		const initRows = await db.select({
+			id: messages.conversationId,
+			content: messages.content
+		}).from(messages).where(eq$1(messages.role, "init"));
+		const apiKeySourceByConvId = /* @__PURE__ */ new Map();
+		for (const r of initRows) {
+			if (apiKeySourceByConvId.has(r.id)) continue;
+			const src = extractApiKeySource(r.content);
+			if (src) apiKeySourceByConvId.set(r.id, src);
+		}
+		const runningRows = await db.select({ id: activeRuns.conversationId }).from(activeRuns);
+		const runningIds = new Set(runningRows.map((r) => r.id));
+		return rows.map((r) => rowToRecord(r, countByConvId.get(r.conversations.id) ?? 0, costByConvId.get(r.conversations.id) ?? 0, apiKeySourceByConvId.get(r.conversations.id) ?? null, runningIds.has(r.conversations.id)));
+	}
+	async read(id) {
+		if (!ID_RE.test(id)) return null;
+		await this.maybeImportLegacy();
+		const db = this.db();
+		const row = (await db.select().from(conversations).leftJoin(widgetAnchors, eq$1(conversations.id, widgetAnchors.conversationId)).where(eq$1(conversations.id, id)).limit(1))[0];
+		if (!row) return null;
+		const countRows = await db.select({ n: count() }).from(messages).where(and$1(eq$1(messages.conversationId, id), notInArray(messages.role, NON_MESSAGE_ROLES)));
+		const totalCostUsd = await this.computeConversationCost(id);
+		const apiKeySource = await this.readApiKeySource(id);
+		const runningRows = await db.select({ id: activeRuns.conversationId }).from(activeRuns).where(eq$1(activeRuns.conversationId, id)).limit(1);
+		return rowToRecord(row, countRows[0]?.n ?? 0, totalCostUsd, apiKeySource, runningRows.length > 0);
+	}
+	/**
+	* Read `apiKeySource` off the conversation's `init` event. Drives the
+	* dock's notional-cost relabeling (see `isNotionalCost`). Null when no
+	* `init` has been recorded yet (created but never run).
+	*/
+	async readApiKeySource(id) {
+		if (!ID_RE.test(id)) return null;
+		const rows = await this.db().select({ content: messages.content }).from(messages).where(and$1(eq$1(messages.conversationId, id), eq$1(messages.role, "init"))).orderBy(asc$1(messages.id)).limit(1);
+		return rows[0] ? extractApiKeySource(rows[0].content) : null;
+	}
+	/**
+	* Sum the SDK-reported `totalCostUsd` across every `result` event
+	* recorded for one conversation. Used both for the per-row display
+	* value and for the per-conversation cap check at spawn time.
+	*/
+	async computeConversationCost(id) {
+		if (!ID_RE.test(id)) return 0;
+		const rows = await this.db().select({ content: messages.content }).from(messages).where(and$1(eq$1(messages.conversationId, id), eq$1(messages.role, "result")));
+		let total = 0;
+		for (const r of rows) total += extractResultCost(r.content);
+		return total;
+	}
+	/**
+	* Sum the SDK-reported `totalCostUsd` across every `result` event
+	* recorded in the given UTC calendar month, across all conversations.
+	* Drives the `monthlyBudgetUsd` cap check. The `month` argument's
+	* day-of-month is ignored — we always span the calendar month it
+	* falls in. Callers pass `new Date()` for "current month".
+	*/
+	async computeMonthlySpend(month) {
+		const db = this.db();
+		const start = new Date(Date.UTC(month.getUTCFullYear(), month.getUTCMonth(), 1));
+		const end = new Date(Date.UTC(month.getUTCFullYear(), month.getUTCMonth() + 1, 1));
+		const rows = await db.select({ content: messages.content }).from(messages).where(and$1(eq$1(messages.role, "result"), gte(messages.createdAt, start), lt(messages.createdAt, end)));
+		let total = 0;
+		for (const r of rows) total += extractResultCost(r.content);
+		return total;
+	}
+	/**
+	* Full transcript for one conversation, in insertion order. Returns
+	* the raw `AgentEvent` payloads as they were appended to the bus,
+	* skipping the `__finished` sentinel (which is internal bookkeeping,
+	* not an event subscribers should see). Backs the HTTP transcript
+	* endpoint that external clients (CLI, hosted dock) read.
+	*
+	* Returns [] for unknown ids — matches `read()`'s "no error on
+	* missing row" contract; the route handler distinguishes via `read`.
+	*/
+	async listMessages(id) {
+		if (!ID_RE.test(id)) return [];
+		await this.maybeImportLegacy();
+		return (await this.db().select().from(messages).where(and$1(eq$1(messages.conversationId, id), notInArray(messages.role, ["__finished"]))).orderBy(asc$1(messages.id))).map((r) => r.content);
+	}
+	async readScreenshotBase64(rec) {
+		const abs = join(this.root, ".pinagent", rec.screenshot);
+		if (!existsSync(abs)) return null;
+		return (await readFile(abs)).toString("base64");
+	}
+	/**
+	* Returns the patched record + the previous status (so callers can
+	* tell whether a terminal-status transition just happened and fire a
+	* `status_changed` event without re-reading).
+	*/
+	async patchWithDiff(id, patch) {
+		if (!ID_RE.test(id)) return null;
+		const current = await this.read(id);
+		if (!current) return null;
+		const previousStatus = current.status;
+		const update = { updatedAt: /* @__PURE__ */ new Date() };
+		if (patch.status !== void 0) {
+			update.status = patch.status;
+			if (patch.status !== "pending") update.resolvedAt = /* @__PURE__ */ new Date();
+			else update.resolvedAt = null;
+		}
+		if (patch.note !== void 0) update.note = patch.note;
+		if (patch.commitSha !== void 0) update.commitSha = patch.commitSha;
+		if (patch.agentSessionId !== void 0) update.agentSessionId = patch.agentSessionId;
+		if (patch.branch !== void 0) update.branch = patch.branch;
+		if (patch.worktreePath !== void 0) update.worktreePath = patch.worktreePath;
+		if (patch.worktreeState !== void 0) update.worktreeState = patch.worktreeState;
+		if (patch.title !== void 0) update.title = patch.title && patch.title.trim().length > 0 ? patch.title.trim() : null;
+		if (patch.archived !== void 0) update.archived = patch.archived;
+		await this.db().update(conversations).set(update).where(eq$1(conversations.id, id));
+		const next = await this.read(id);
+		if (!next) return null;
+		emitProjectChange({ type: "conversations_changed" });
+		return {
+			record: next,
+			previousStatus
+		};
+	}
+	async patch(id, patch) {
+		const result = await this.patchWithDiff(id, patch);
+		return result ? result.record : null;
+	}
+	async atomicWriteBytes(p, data) {
+		const tmp = `${p}.tmp`;
+		await writeFile(tmp, data);
+		await rename(tmp, p);
+	}
+};
+function parseDate(iso) {
+	const d = new Date(iso);
+	if (Number.isNaN(d.getTime())) return /* @__PURE__ */ new Date();
+	return d;
+}
+function rowToRecord(row, messageCount, totalCostUsd, apiKeySource, isRunning) {
+	const c = row.conversations;
+	const a = row.widget_anchors;
+	return {
+		id: c.id,
+		comment: c.comment,
+		file: a?.file ?? null,
+		line: a?.line ?? null,
+		col: a?.col ?? null,
+		selector: a?.selector ?? "",
+		url: a?.url ?? "",
+		viewport: {
+			w: a?.viewportW ?? 0,
+			h: a?.viewportH ?? 0
+		},
+		userAgent: a?.userAgent ?? "",
+		additionalAnchors: a?.additionalAnchors ?? null,
+		component: a?.component ?? null,
+		componentPath: a?.componentPath ?? null,
+		instanceIndex: a?.instanceIndex ?? null,
+		instanceTotal: a?.instanceTotal ?? null,
+		instanceFingerprint: a?.instanceFingerprint ?? null,
+		screenshot: join("screenshots", `${c.id}.png`),
+		status: c.status,
+		note: c.note,
+		commitSha: c.commitSha,
+		agentSessionId: c.agentSessionId,
+		branch: c.branch,
+		worktreePath: c.worktreePath,
+		worktreeState: c.worktreeState,
+		title: c.title,
+		archived: c.archived,
+		createdAt: c.createdAt.toISOString(),
+		updatedAt: c.updatedAt.toISOString(),
+		resolvedAt: c.resolvedAt ? c.resolvedAt.toISOString() : null,
+		messageCount,
+		totalCostUsd,
+		apiKeySource,
+		isRunning
+	};
+}
+/**
+* Pull the `totalCostUsd` out of a stored `result` event's JSON content.
+* Tolerant of missing/non-numeric values so a malformed historical row
+* (or a future event shape) doesn't poison the aggregate — those just
+* count as 0.
+*/
+function extractResultCost(content) {
+	if (content && typeof content === "object" && "totalCostUsd" in content) {
+		const v = content.totalCostUsd;
+		if (typeof v === "number" && Number.isFinite(v) && v >= 0) return v;
+	}
+	return 0;
+}
+/**
+* Pull `apiKeySource` out of a stored `init` event's JSON content. Mirrors
+* `extractResultCost`'s tolerance: missing/non-string values yield null so
+* the dock simply falls back to showing the raw cost (the pre-existing
+* behavior) rather than mis-labeling it.
+*/
+function extractApiKeySource(content) {
+	if (content && typeof content === "object" && "apiKeySource" in content) {
+		const v = content.apiKeySource;
+		if (typeof v === "string" && v) return v;
+	}
+	return null;
+}
+/**
+* Branch-routing enforcement primitives (OSS / dev-side).
+*
+* The cloud control plane owns the *policy* (an org's default base branch +
+* allowed land-target patterns); this module is the on-machine enforcement of
+* it. The matching logic is re-implemented here rather than imported from the
+* Elastic `@pinagent/ee-team-features` package so the OSS agent-runner stays
+* free of any source-available dependency — the policy crosses the boundary
+* as plain data (today via local project settings; later pushed over the relay
+* channel) and is enforced with this code.
+*
+* Keep this behaviourally in sync with ee-team-features' `branch-routing.ts`:
+* patterns are anchored full-string globs where `*` matches any run of
+* characters, and an empty pattern list allows any branch.
+*/
+function escapeRegExp(literal) {
+	return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Match a branch name against a single `*`-glob pattern (anchored). */
+function matchBranchPattern(pattern, branch) {
+	return new RegExp(`^${pattern.split("*").map(escapeRegExp).join(".*")}$`).test(branch);
+}
+/**
+* Whether `branch` may be landed on under `allowedPatterns`. An empty list
+* (the default) allows any branch — branch routing is opt-in.
+*/
+function isBranchAllowed(allowedPatterns, branch) {
+	if (allowedPatterns.length === 0) return true;
+	return allowedPatterns.some((pattern) => matchBranchPattern(pattern, branch));
+}
+async function createWorktree(projectRoot, feedbackId, logPath) {
+	if (!existsSync(join(projectRoot, ".git"))) throw new Error("project root is not a git repository");
+	const worktreeDir = join(projectRoot, ".pinagent", "worktrees");
+	await mkdir(worktreeDir, { recursive: true });
+	const worktreePath = join(worktreeDir, feedbackId);
+	const branch = `pinagent/${feedbackId}`;
+	const { baseBranch } = await new SettingsStore(projectRoot).read();
+	const baseResolves = (await runGitCapture(projectRoot, [
+		"rev-parse",
+		"--verify",
+		"--quiet",
+		baseBranch
+	])).code === 0;
+	const addArgs = baseResolves ? [
+		"worktree",
+		"add",
+		"-b",
+		branch,
+		worktreePath,
+		baseBranch
+	] : [
+		"worktree",
+		"add",
+		"-b",
+		branch,
+		worktreePath
+	];
+	if (!baseResolves) await appendLog(logPath, `> [pinagent] base branch \`${baseBranch}\` not found; forking worktree from HEAD\n`);
+	await runGit(projectRoot, addArgs, logPath);
+	try {
+		await new Storage(projectRoot).patch(feedbackId, {
+			branch,
+			worktreePath,
+			worktreeState: "active"
+		});
+	} catch {}
+	return worktreePath;
+}
+/**
+* Land the agent's worktree onto the project's HEAD branch — but only when HEAD
+* still matches the base the worktree forked from (`settings.baseBranch`). If
+* the developer switched the main checkout to another branch, landing is
+* refused rather than silently merging the work into the wrong branch.
+*
+* The agent intentionally does not commit (see `buildInitialPrompt`) so the
+* developer can review the diff before landing; we stage and commit on its
+* behalf as a single squash here. On merge conflict the merge is aborted —
+* the worktree is left intact so the user can resolve manually and retry.
+*
+* Should be called via `merge-queue.ts` so concurrent landings on the same
+* project serialize cleanly.
+*/
+async function mergeWorktree(projectRoot, feedbackId, logPath) {
+	const storage = new Storage(projectRoot);
+	const rec = await storage.read(feedbackId);
+	if (!rec) return {
+		ok: false,
+		error: `feedback not found: ${feedbackId}`
+	};
+	if (!rec.worktreePath || !rec.branch) return {
+		ok: false,
+		error: "this conversation has no worktree (inline-mode submission)"
+	};
+	if (rec.worktreeState !== "active") return {
+		ok: false,
+		error: `cannot land: worktree state is ${rec.worktreeState}`
+	};
+	if (!existsSync(rec.worktreePath)) return {
+		ok: false,
+		error: `worktree no longer exists at ${rec.worktreePath}`
+	};
+	if (!existsSync(join(projectRoot, ".git"))) return {
+		ok: false,
+		error: "project root is not a git repository"
+	};
+	await appendLog(logPath, `\n## Land · ${(/* @__PURE__ */ new Date()).toISOString()}\n\n`);
+	const head = await runGitCapture(projectRoot, [
+		"symbolic-ref",
+		"--short",
+		"HEAD"
+	]);
+	if (head.code !== 0) return {
+		ok: false,
+		error: `cannot resolve project HEAD branch (detached?): ${head.stderr.trim()}`
+	};
+	const targetBranch = head.stdout.trim();
+	if (targetBranch === rec.branch) return {
+		ok: false,
+		error: `project HEAD is already on ${rec.branch}; nothing to land`
+	};
+	const settings = await new SettingsStore(projectRoot).read();
+	if ((await runGitCapture(projectRoot, [
+		"rev-parse",
+		"--verify",
+		"--quiet",
+		settings.baseBranch
+	])).code === 0 && targetBranch !== settings.baseBranch) return {
+		ok: false,
+		error: `cannot land: the project is on "${targetBranch}" but this worktree was based on "${settings.baseBranch}". Check out "${settings.baseBranch}" to land, or discard.`
+	};
+	const { allowedBranchPatterns } = settings;
+	if (!isBranchAllowed(allowedBranchPatterns, targetBranch)) {
+		const allowed = allowedBranchPatterns.join(", ");
+		await appendLog(logPath, `> [pinagent] branch routing blocked landing onto \`${targetBranch}\` (allowed: ${allowed})\n`);
+		return {
+			ok: false,
+			error: `branch routing policy does not allow landing onto "${targetBranch}" (allowed: ${allowed})`
+		};
+	}
+	const status = await runGitCapture(rec.worktreePath, ["status", "--porcelain"]);
+	if (status.code !== 0) return {
+		ok: false,
+		error: `git status failed in worktree: ${status.stderr.trim()}`
+	};
+	if (status.stdout.trim()) {
+		const add = await runGitCapture(rec.worktreePath, ["add", "-A"]);
+		if (add.code !== 0) return {
+			ok: false,
+			error: `git add failed: ${add.stderr.trim()}`
+		};
+		const commit = await runGitCapture(rec.worktreePath, [
+			"commit",
+			"-m",
+			formatLandCommitMessage(rec)
+		]);
+		if (commit.code !== 0) {
+			const combined = `${commit.stdout}\n${commit.stderr}`;
+			if (!/nothing to commit/.test(combined)) return {
+				ok: false,
+				error: `git commit failed: ${commit.stderr.trim() || commit.stdout.trim()}`
+			};
+		}
+	}
+	const ahead = await runGitCapture(projectRoot, [
+		"rev-list",
+		"--count",
+		`${targetBranch}..${rec.branch}`
+	]);
+	if (ahead.code !== 0) return {
+		ok: false,
+		error: `cannot compare branches: ${ahead.stderr.trim()}`
+	};
+	if (Number(ahead.stdout.trim()) === 0) {
+		await appendLog(logPath, "> [pinagent] no changes to land\n");
+		await cleanupWorktreeFiles(rec.worktreePath, rec.branch, projectRoot, logPath);
+		await storage.patch(feedbackId, { worktreeState: "landed" });
+		await recordAuditEvent(projectRoot, {
+			conversationId: feedbackId,
+			actor: "user",
+			action: "conversation_landed",
+			payload: {
+				branch: rec.branch,
+				target: targetBranch,
+				noop: true
+			}
+		});
+		return { ok: true };
+	}
+	if ((await runGitCapture(projectRoot, [
+		"merge",
+		"--no-ff",
+		"--no-edit",
+		rec.branch
+	])).code !== 0) {
+		const conflicts = (await runGitCapture(projectRoot, [
+			"diff",
+			"--name-only",
+			"--diff-filter=U"
+		])).stdout.split("\n").map((s) => s.trim()).filter(Boolean);
+		const abort = await runGitCapture(projectRoot, ["merge", "--abort"]);
+		await appendLog(logPath, `> [pinagent] merge into \`${targetBranch}\` failed: ${conflicts.length} conflicted file(s)\n${conflicts.map((c) => `>   - \`${c}\`\n`).join("")}\n`);
+		if (abort.code !== 0) {
+			await appendLog(logPath, `> [pinagent] WARNING: \`git merge --abort\` failed; the project working tree may be left mid-merge: ${abort.stderr.trim()}\n`);
+			return {
+				ok: false,
+				error: `merge conflicted and \`git merge --abort\` failed; the project working tree may be left mid-merge — resolve manually: ${abort.stderr.trim()}`,
+				conflicts
+			};
+		}
+		return {
+			ok: false,
+			conflicts
+		};
+	}
+	const sha = await runGitCapture(projectRoot, ["rev-parse", "HEAD"]);
+	const commitSha = sha.code === 0 ? sha.stdout.trim() : void 0;
+	await cleanupWorktreeFiles(rec.worktreePath, rec.branch, projectRoot, logPath);
+	await storage.patch(feedbackId, {
+		worktreeState: "landed",
+		...commitSha ? { commitSha } : {}
+	});
+	await recordAuditEvent(projectRoot, {
+		conversationId: feedbackId,
+		actor: "user",
+		action: "conversation_landed",
+		payload: {
+			branch: rec.branch,
+			target: targetBranch,
+			...commitSha ? { commitSha } : {}
+		}
+	});
+	await appendLog(logPath, `> [pinagent] landed onto \`${targetBranch}\`${commitSha ? ` as \`${commitSha.slice(0, 12)}\`` : ""}\n`);
+	return {
+		ok: true,
+		...commitSha ? { commitSha } : {}
+	};
+}
+/**
+* Reverse a landed/discarded conversation: put it back in the active
+* list so the user can follow up with the agent. We reset
+* `worktreeState` to `'none'` and `status` to `'pending'`; we do NOT
+* recreate the worktree (it was cleaned up at land/discard time and
+* the developer's actual changes have either already merged or were
+* thrown away). For inline-mode runs that's all that's needed — the
+* user can immediately send a follow-up. For ex-worktree runs the
+* conversation is conceptually inline-mode from this point forward.
+*
+* Refuses on conversations that aren't already resolved so a stray
+* client click can't reset a still-active worktree.
+*/
+async function reopenConversation(projectRoot, feedbackId, logPath) {
+	const storage = new Storage(projectRoot);
+	const rec = await storage.read(feedbackId);
+	if (!rec) return {
+		ok: false,
+		error: `feedback not found: ${feedbackId}`
+	};
+	if (rec.worktreeState !== "landed" && rec.worktreeState !== "discarded") return {
+		ok: false,
+		error: `cannot reopen: worktree state is ${rec.worktreeState} (expected landed or discarded)`
+	};
+	await appendLog(logPath, `\n## Reopen · ${(/* @__PURE__ */ new Date()).toISOString()}\n\n`);
+	await storage.patch(feedbackId, {
+		worktreeState: "none",
+		status: "pending"
+	});
+	await recordAuditEvent(projectRoot, {
+		conversationId: feedbackId,
+		actor: "user",
+		action: "conversation_reopened",
+		payload: {
+			previousWorktreeState: rec.worktreeState,
+			previousStatus: rec.status
+		}
+	});
+	return { ok: true };
+}
+/**
+* Throw away the worktree and its branch without merging. Idempotent —
+* tolerates a missing worktree or branch (the user may have cleaned
+* them up manually).
+*/
+async function discardWorktree(projectRoot, feedbackId, logPath) {
+	const storage = new Storage(projectRoot);
+	const rec = await storage.read(feedbackId);
+	if (!rec) return { ok: true };
+	await appendLog(logPath, `\n## Discard · ${(/* @__PURE__ */ new Date()).toISOString()}\n\n`);
+	if (rec.worktreePath && rec.branch) await cleanupWorktreeFiles(rec.worktreePath, rec.branch, projectRoot, logPath);
+	await storage.patch(feedbackId, { worktreeState: "discarded" });
+	await recordAuditEvent(projectRoot, {
+		conversationId: feedbackId,
+		actor: "user",
+		action: "conversation_discarded",
+		payload: rec.branch ? { branch: rec.branch } : {}
+	});
+	return { ok: true };
+}
+async function cleanupWorktreeFiles(worktreePath, branch, projectRoot, logPath) {
+	if (existsSync(worktreePath)) {
+		const rm = await runGitCapture(projectRoot, [
+			"worktree",
+			"remove",
+			"--force",
+			worktreePath
+		]);
+		if (rm.code !== 0) await appendLog(logPath, `> [pinagent:git] worktree remove → exit ${rm.code}\n${rm.stderr}\n`);
+	}
+	await runGitCapture(projectRoot, ["worktree", "prune"]);
+	const br = await runGitCapture(projectRoot, [
+		"branch",
+		"-D",
+		branch
+	]);
+	if (br.code !== 0 && !/not found|did not match/i.test(br.stderr)) await appendLog(logPath, `> [pinagent:git] branch -D ${branch} → exit ${br.code}\n${br.stderr}\n`);
+}
+function formatLandCommitMessage(rec) {
+	const firstLine = rec.comment.split(/\r?\n/)[0]?.trim() ?? "";
+	const subject = firstLine.length > 70 ? `${firstLine.slice(0, 67)}…` : firstLine;
+	const where = rec.file ? `${rec.file}:${rec.line ?? "?"}${rec.col != null ? `:${rec.col}` : ""}` : rec.selector;
+	return [
+		`pinagent: ${subject || "agent edit"}`,
+		"",
+		"Landed via pinagent.",
+		"",
+		`Feedback: ${rec.id}`,
+		`Target:   ${where}`,
+		""
+	].join("\n");
+}
+/**
+* Count files with uncommitted changes in a worktree (`git status --porcelain`
+* line count). Returns `null` if the worktree path doesn't exist or `git`
+* fails — the caller treats that as "unknown" rather than zero, so the widget
+* can omit the count from its label instead of showing a misleading "0 changes".
+*/
+async function countWorktreeChanges(worktreePath) {
+	if (!existsSync(worktreePath)) return null;
+	const status = await runGitCapture(worktreePath, ["status", "--porcelain"]);
+	if (status.code !== 0) return null;
+	const trimmed = status.stdout.trim();
+	if (!trimmed) return 0;
+	return trimmed.split("\n").length;
+}
+/**
+* In-flight runs LOCAL TO THIS CONTEXT. The AbortController is a
+* process-bound object — there's no way to serialise it across
+* contexts/processes, so we keep the per-context Map. Cross-context
+* `interruptRun` calls reach the owning context via `process.emit`
+* (see INTERRUPT_EVENT below), which all contexts in the same Node
+* process share.
+*
+* Cross-context "is a run in flight?" visibility is handled separately
+* by the `active_runs` SQLite table — see `hasActiveRun` below.
+*/
+const activeRuns$1 = /* @__PURE__ */ new Map();
+/**
+* Cross-context signalling channel for interrupts. The WS server can
+* land in a different context than the one running the SDK loop (Next 16
+* Turbopack, Vite 8 environments), so the in-memory `activeRuns` Map in
+* the WS server's context wouldn't see the entry. Node's `process`
+* EventEmitter is shared across all contexts in one process, so emit-ing
+* here reliably reaches the owning context's listener (registered in
+* `runQuery`). Same idea as the SQLite-backed bus, but for a transient
+* signal rather than a stream — no persistence needed.
+*/
+const INTERRUPT_EVENT = "pinagent:interrupt";
+async function recordActiveRun(projectRoot, feedbackId) {
+	try {
+		await getDb(projectRoot).insert(activeRuns).values({
+			conversationId: feedbackId,
+			startedAt: /* @__PURE__ */ new Date(),
+			currentTurn: 1
+		}).onConflictDoUpdate({
+			target: activeRuns.conversationId,
+			set: { startedAt: /* @__PURE__ */ new Date() }
+		});
+		emitProjectChange({ type: "conversations_changed" });
+	} catch {}
+}
+async function clearActiveRun(projectRoot, feedbackId) {
+	try {
+		await getDb(projectRoot).delete(activeRuns).where(eq(activeRuns.conversationId, feedbackId));
+		emitProjectChange({ type: "conversations_changed" });
+	} catch {}
+}
+/**
+* Run an isolated Claude Agent SDK query for a single freshly-submitted
+* feedback record. Kicks off in the background; the route handler resolves
+* its POST as soon as this returns "started", not when the agent finishes.
+*
+* Log file at `.pinagent/logs/<id>.md` accumulates the transcript across
+* the initial run plus any follow-up turns the user sends over WS.
+*/
+async function spawnAgent(ctx) {
+	if (ctx.mode === false) return;
+	const logsDir = join(ctx.projectRoot, ".pinagent", "logs");
+	await mkdir(logsDir, { recursive: true });
+	const logPath = join(logsDir, `${ctx.feedback.id}.md`);
+	const capCheck = await checkCostCaps(ctx.projectRoot, ctx.feedback.id);
+	if (!capCheck.ok) {
+		await getOrCreateBus(ctx.feedback.id, ctx.projectRoot).publish({
+			type: "error",
+			message: capCheck.reason
+		});
+		await appendLog(logPath, `\n> [pinagent] spawn refused: ${capCheck.reason}\n`);
+		return;
+	}
+	let cwd = ctx.projectRoot;
+	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+	if (ctx.mode === "worktree") try {
+		cwd = await createWorktree(ctx.projectRoot, ctx.feedback.id, logPath);
+	} catch (err) {
+		await appendLog(logPath, `${renderHeader(ctx, cwd, startedAt, false)}\n> [pinagent] worktree creation failed: ${stringifyErr(err)}\n`);
+		return;
+	}
+	await appendLog(logPath, renderHeader(ctx, cwd, startedAt, true));
+	const prompt = buildInitialPrompt(ctx.feedback, ctx.mode, cwd);
+	const permissionMode = await resolveRunPermissionMode(ctx.projectRoot);
+	runQuery({
+		projectRoot: ctx.projectRoot,
+		feedbackId: ctx.feedback.id,
+		cwd,
+		logPath,
+		prompt,
+		isInitial: true,
+		permissionMode,
+		targetFile: ctx.feedback.file
+	});
+}
+/**
+* Send a follow-up message into the existing conversation for `feedbackId`.
+* Resumes the prior SDK session so the agent keeps full context. Resolves
+* once the new turn has been started, not when it finishes.
+*
+* Refuses if there's no prior session (the feedback was never spawn-mode).
+*
+* The widget queues follow-ups client-side and flushes the next one the
+* instant it sees the prior turn's `result` event. That flush can reach us
+* a few ms BEFORE the just-finished run has torn down its `active_runs`
+* row (the teardown's `clearActiveRun` runs in `runQuery`'s finally, after
+* the `result` was already published). The widget only ever has one turn
+* in flight, so a lingering active run here is that finishing turn — not a
+* parallel one — so we briefly wait for it to clear rather than bouncing
+* the follow-up back. A bounced follow-up is effectively dropped: the
+* widget re-queues it but has no further turn-end event to re-flush it on,
+* so the agent appears to "just end" without addressing the follow-up.
+*/
+async function runFollowUpTurn(feedbackId, content) {
+	const projectRoot = process.env.PINAGENT_PROJECT_ROOT ?? process.cwd();
+	if (!await waitForRunToClear(feedbackId, projectRoot)) throw new Error("a turn is already in progress for this feedback");
+	const rec = await new Storage(projectRoot).read(feedbackId);
+	if (!rec) throw new Error(`feedback not found: ${feedbackId}`);
+	if (!rec.agentSessionId) throw new Error("no prior agent session — only spawn-mode submissions support follow-ups");
+	const capCheck = await checkCostCaps(projectRoot, feedbackId);
+	if (!capCheck.ok) {
+		await getOrCreateBus(feedbackId, projectRoot).publish({
+			type: "error",
+			message: capCheck.reason
+		});
+		throw new Error(capCheck.reason);
+	}
+	const worktreePath = join(projectRoot, ".pinagent", "worktrees", feedbackId);
+	const cwd = existsSync(worktreePath) ? worktreePath : projectRoot;
+	const logsDir = join(projectRoot, ".pinagent", "logs");
+	await mkdir(logsDir, { recursive: true });
+	const logPath = join(logsDir, `${feedbackId}.md`);
+	await appendLog(logPath, `\n## Follow-up turn · ${(/* @__PURE__ */ new Date()).toISOString()}\n\n> **User**\n> \n> ${content.split("\n").join("\n> ")}\n\n`);
+	runQuery({
+		projectRoot,
+		feedbackId,
+		cwd,
+		logPath,
+		prompt: content,
+		isInitial: false,
+		permissionMode: await resolveRunPermissionMode(projectRoot),
+		resume: rec.agentSessionId,
+		targetFile: rec.file
+	});
+}
+/**
+* True iff an SDK run is currently in flight for this feedback id, in
+* ANY context. Reads the `active_runs` SQLite row inserted by
+* `runQuery`. Local-Map check is cheap and short-circuits the common
+* case where the run was started in the same context.
+*/
+async function hasActiveRun(feedbackId, projectRoot) {
+	if (activeRuns$1.has(feedbackId)) return true;
+	const root = projectRoot ?? process.env.PINAGENT_PROJECT_ROOT ?? process.cwd();
+	try {
+		return (await getDb(root).select().from(activeRuns).where(eq(activeRuns.conversationId, feedbackId)).limit(1)).length > 0;
+	} catch {
+		return false;
+	}
+}
+/** Longest a follow-up waits for the prior turn's cleanup to land. */
+const FOLLOWUP_RUN_CLEAR_TIMEOUT_MS = 3e3;
+/** How often `waitForRunToClear` re-checks the `active_runs` row. */
+const FOLLOWUP_RUN_CLEAR_POLL_MS = 25;
+/**
+* Wait (bounded) for any in-flight run for `feedbackId` to finish, polling
+* `hasActiveRun`. Returns true once it's clear, or false if the timeout
+* elapses with a run still active. Returns true immediately when nothing is
+* in flight — the common case — so this is cheap. See `runFollowUpTurn` for
+* why a follow-up tolerates a briefly-lingering run rather than bouncing it.
+*/
+async function waitForRunToClear(feedbackId, projectRoot) {
+	const deadline = Date.now() + FOLLOWUP_RUN_CLEAR_TIMEOUT_MS;
+	while (await hasActiveRun(feedbackId, projectRoot)) {
+		if (Date.now() >= deadline) return false;
+		await new Promise((resolve) => setTimeout(resolve, FOLLOWUP_RUN_CLEAR_POLL_MS));
+	}
+	return true;
+}
+/**
+* Abort an in-flight run for `feedbackId`. Returns true if the run
+* either lives in this context (local abort) OR lives in some other
+* context in this process (cross-context signal sent via `process.emit`
+* — the owning context's listener will call `abort` on its
+* AbortController). Returns false if no SQLite row exists for an
+* active run, i.e. nothing was actually in flight.
+*
+* The SDK propagates the abort through its tool loop and exits the
+* iterator; `consumeStream` catches the abort error and writes a
+* minimal footer.
+*/
+async function interruptRun(feedbackId, projectRoot) {
+	const local = activeRuns$1.get(feedbackId);
+	if (local) {
+		local.abort.abort();
+		return true;
+	}
+	const root = projectRoot ?? process.env.PINAGENT_PROJECT_ROOT ?? process.cwd();
+	let exists = false;
+	try {
+		exists = (await getDb(root).select().from(activeRuns).where(eq(activeRuns.conversationId, feedbackId)).limit(1)).length > 0;
+	} catch {
+		exists = false;
+	}
+	if (!exists) return false;
+	process.emit(INTERRUPT_EVENT, feedbackId);
+	return true;
+}
+/**
+* Gate every new turn (initial spawn + follow-ups) on the cost caps in
+* the project's settings. The cap is breached when the *running total*
+* is already at or above the cap — that lets the first-ever turn run
+* freely (totalCostUsd starts at 0) but blocks the next turn once
+* spending has caught up.
+*
+* Returns `{ ok: true }` when within both caps, or `{ ok: false, reason }`
+* with a user-facing message. Callers emit the message on the bus so
+* every subscriber sees it, and refuse to actually start the turn.
+*/
+async function checkCostCaps(projectRoot, feedbackId) {
+	const settings = await new SettingsStore(projectRoot).read();
+	const storage = new Storage(projectRoot);
+	const notional = isNotionalCost(await storage.readApiKeySource(feedbackId));
+	const conversationCost = await storage.computeConversationCost(feedbackId);
+	if (conversationCost >= settings.perConversationCapUsd) return {
+		ok: false,
+		reason: `per-conversation cost cap reached: ${formatCapSpend(conversationCost, settings.perConversationCapUsd, notional)}. Raise the cap in Settings or resolve this conversation.`
+	};
+	if (settings.monthlyBudgetUsd !== null) {
+		const monthlySpend = await storage.computeMonthlySpend(/* @__PURE__ */ new Date());
+		if (monthlySpend >= settings.monthlyBudgetUsd) return {
+			ok: false,
+			reason: `monthly budget reached: ${formatCapSpend(monthlySpend, settings.monthlyBudgetUsd, notional)} this month. Raise the budget in Settings.`
+		};
+	}
+	return { ok: true };
+}
+/**
+* Format the `<used> of <cap>` fragment of a cap-breach message. For
+* notional (subscription) runs the amount is API-equivalent and was never
+* billed, so we say so rather than "spent".
+*/
+function formatCapSpend(used, cap, notional) {
+	const usedUsd = `$${used.toFixed(2)}`;
+	const capUsd = `$${cap.toFixed(2)}`;
+	return notional ? `≈${usedUsd} of ${capUsd} API-equivalent (subscription — not billed)` : `${usedUsd} of ${capUsd} spent`;
+}
+async function runQuery(opts) {
+	const { permissionMode } = opts;
+	const abort = new AbortController();
+	activeRuns$1.set(opts.feedbackId, { abort });
+	const onInterrupt = (id) => {
+		if (id === opts.feedbackId) abort.abort();
+	};
+	process.on(INTERRUPT_EVENT, onInterrupt);
+	recordActiveRun(opts.projectRoot, opts.feedbackId);
+	const provider = resolveProvider(process.env);
+	const request = {
+		projectRoot: opts.projectRoot,
+		feedbackId: opts.feedbackId,
+		cwd: opts.cwd,
+		targetFile: opts.targetFile,
+		prompt: opts.prompt,
+		isInitial: opts.isInitial,
+		permissionMode,
+		resume: opts.resume,
+		abortSignal: abort.signal
+	};
+	try {
+		await consumeStream(opts, provider.run(request));
+	} finally {
+		activeRuns$1.delete(opts.feedbackId);
+		process.off(INTERRUPT_EVENT, onInterrupt);
+		await clearActiveRun(opts.projectRoot, opts.feedbackId);
+		rejectAsk(opts.feedbackId, "agent run ended");
+	}
+}
+/**
+* Drive one provider run: publish its events to the bus, append its log
+* chunks to the transcript, persist the session id, and finalize the
+* resolution block. Provider-neutral — every backend funnels through the
+* same `ProviderRunItem` stream, so cost/session/status handling is shared.
+*/
+async function consumeStream(opts, stream) {
+	let sessionRecorded = false;
+	let resultRendered = false;
+	const bus = getOrCreateBus(opts.feedbackId);
+	try {
+		for await (const item of stream) {
+			if (!sessionRecorded && item.sessionId) {
+				sessionRecorded = true;
+				await persistSessionId(opts.projectRoot, opts.feedbackId, item.sessionId);
+			}
+			for (const ev of item.events ?? []) await bus.publish(ev);
+			if (item.isResult) {
+				resultRendered = true;
+				if (item.log) await appendLog(opts.logPath, item.log);
+				if (opts.isInitial) await appendResolution(opts.projectRoot, opts.feedbackId, opts.logPath, item.resultFooter ?? null);
+				else if (item.resultFooter) await appendLog(opts.logPath, `\n${item.resultFooter}\n`);
+				try {
+					const rec = await new Storage(opts.projectRoot).read(opts.feedbackId);
+					if (rec && rec.status !== "pending") {
+						await bus.publish({
+							type: "status_changed",
+							status: rec.status,
+							note: rec.note,
+							commitSha: rec.commitSha,
+							resolvedAt: rec.resolvedAt
+						});
+						emitProjectChange({ type: "conversations_changed" });
+					}
+				} catch {}
+				continue;
+			}
+			if (item.log) await appendLog(opts.logPath, item.log);
+		}
+	} catch (err) {
+		const msg = stringifyErr(err);
+		await bus.publish({
+			type: "error",
+			message: msg
+		});
+		await appendLog(opts.logPath, `\n> [pinagent] agent stream errored: ${msg}\n`);
+	} finally {
+		if (!resultRendered && opts.isInitial) await appendResolution(opts.projectRoot, opts.feedbackId, opts.logPath, null);
+	}
+}
+async function persistSessionId(projectRoot, feedbackId, sessionId) {
+	try {
+		await new Storage(projectRoot).patch(feedbackId, { agentSessionId: sessionId });
+	} catch {}
+}
+function stringifyErr(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+function renderHeader(ctx, cwd, startedAt, worktreeReady) {
+	const rec = ctx.feedback;
+	const where = rec.file ? `${rec.file}:${rec.line ?? "?"}${rec.col != null ? `:${rec.col}` : ""}` : rec.selector;
+	const branchLine = ctx.mode === "worktree" && worktreeReady ? `branch: pinagent/${rec.id}\n` : "";
+	return [
+		"---",
+		`id: ${rec.id}`,
+		`mode: ${ctx.mode}`,
+		`target: ${where}`,
+		`url: ${rec.url}`,
+		`started: ${startedAt}`,
+		`cwd: ${cwd}`,
+		branchLine.trimEnd(),
+		"---",
+		"",
+		`# Pinagent feedback \`${rec.id}\``,
+		"",
+		`**Target:** \`${where}\`  `,
+		`**URL:** ${rec.url}  `,
+		`**Mode:** ${ctx.mode}${ctx.mode === "worktree" && worktreeReady ? `  ·  **Branch:** \`pinagent/${rec.id}\`` : ""}`,
+		"",
+		"> **Comment**",
+		"> ",
+		`> ${rec.comment.split("\n").join("\n> ")}`,
+		"",
+		"## Agent output",
+		"",
+		""
+	].filter((l) => l !== null).join("\n");
+}
+async function appendResolution(projectRoot, feedbackId, logPath, footer) {
+	const updated = await new Storage(projectRoot).read(feedbackId);
+	const finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const lines = [];
+	lines.push("");
+	lines.push("## Resolution");
+	lines.push("");
+	lines.push(`**Finished:** ${finishedAt}  `);
+	if (footer) lines.push(footer);
+	else lines.push("> Stream ended without a `result` message.");
+	if (!updated) {
+		lines.push("");
+		lines.push("> Feedback record disappeared between spawn and exit.");
+	} else {
+		lines.push(`**Status:** \`${updated.status}\``);
+		if (updated.resolvedAt) lines.push(`**Resolved at:** ${updated.resolvedAt}`);
+		if (updated.commitSha) lines.push(`**Commit:** \`${updated.commitSha}\``);
+		if (updated.agentSessionId) lines.push(`**Session:** \`${updated.agentSessionId}\``);
+		if (updated.note) {
+			lines.push("");
+			lines.push("### Note from agent");
+			lines.push("");
+			lines.push(updated.note);
+		}
+		if (updated.status === "pending") {
+			lines.push("");
+			lines.push("> ⚠️  Agent exited without calling `resolve_feedback`. The record is still pending.");
+		}
+	}
+	lines.push("");
+	await appendLog(logPath, lines.join("\n"));
+}
+function buildInitialPrompt(rec, mode, cwd) {
+	const where = rec.file ? `${rec.file}:${rec.line ?? "?"}${rec.col != null ? `:${rec.col}` : ""}` : rec.selector;
+	const worktreeContext = mode === "worktree" ? [
+		"",
+		"You are working in a FRESH git worktree at:",
+		`  ${cwd}`,
+		`on branch pinagent/${rec.id} (forked from current HEAD).`,
+		"",
+		"Make edits freely. DO NOT commit — the developer will review your",
+		"changes by diffing this branch against main."
+	].join("\n") : "";
+	const componentLine = rec.component ? `Component: <${rec.component}>` : "";
+	const componentPathLine = rec.componentPath && rec.componentPath.length > 1 ? `Component path: ${rec.componentPath.join(" › ")}` : "";
+	const instanceNote = rec.instanceTotal && rec.instanceTotal > 1 ? [
+		"",
+		`Heads up: this target's source location is rendered ${rec.instanceTotal} times`,
+		`(likely a list/.map()). The developer clicked instance #${(rec.instanceIndex ?? 0) + 1} of ${rec.instanceTotal}.`,
+		rec.instanceFingerprint ? `That instance's content: ${rec.instanceFingerprint}` : "",
+		`The file:line points at the *shared* JSX literal — edit there, but use the`,
+		`screenshot and the content above to act on the correct item if the change is`,
+		`instance-specific (e.g. its data source) rather than the markup itself.`
+	].filter((l) => l !== "").join("\n") : "";
+	const additional = rec.additionalAnchors ?? [];
+	const additionalTargets = additional.length > 0 ? [
+		"",
+		`The developer multi-selected ${additional.length + 1} elements and left a single`,
+		`comment that applies to ALL of them. Besides the primary Target above, also`,
+		`address these (apply the same change to each unless the comment says otherwise):`,
+		...additional.map((a, i) => {
+			const aloc = a.file ? `${a.file}:${a.line ?? "?"}${a.col != null ? `:${a.col}` : ""}` : a.selector;
+			const comp = a.component ? ` (<${a.component}>)` : "";
+			return `  ${i + 2}. ${aloc}${comp}`;
+		})
+	].join("\n") : "";
+	return [
+		"A developer submitted Pinagent feedback. Address it autonomously.",
+		"",
+		`Feedback id: ${rec.id}`,
+		`Target: ${where}`,
+		componentLine,
+		componentPathLine,
+		`Comment: "${rec.comment.replace(/\s+/g, " ").slice(0, 200)}"`,
+		instanceNote,
+		additionalTargets,
+		worktreeContext,
+		"",
+		"Workflow:",
+		"  1. Call the pinagent MCP tool `get_feedback` with the id above —",
+		"     it returns the full comment plus a screenshot of what the user",
+		"     selected.",
+		"  2. Optionally call `get_source_context` to see code around the target.",
+		"  3. Edit the file(s) to address the request. Be conservative: only",
+		"     change what the comment asks for.",
+		"  4. Call `resolve_feedback` with status=\"fixed\" and a one-sentence",
+		"     note describing what you changed. Use status=\"wontfix\" with a",
+		"     reason if you cannot apply the change."
+	].filter((l) => l !== "").join("\n");
+}
+/**
+* Per-project FIFO queue for landing/discarding pinagent worktrees.
+*
+* v2 plan §6 calls for serialised merges so two widgets racing to land
+* onto the same target branch can't interleave. We do that by chaining
+* each enqueued job onto the project's current tail Promise. Failures
+* are isolated — a rejected job's error is returned to its caller, but
+* the queue continues from the same logical point so the next job
+* isn't poisoned.
+*
+* In-memory only. On an agent-runner restart, in-flight queue entries are
+* dropped along with the WS connections that initiated them; the DB
+* still shows `worktreeState='active'` for any conversation that
+* hadn't reached `landed`/`discarded`, so the user can re-click Land
+* from the widget after the server comes back.
+*/
+const QUEUES_SYMBOL = Symbol.for("pinagent.merge-queue.tails");
+const tails = globalThis[QUEUES_SYMBOL] ?? /* @__PURE__ */ new Map();
+globalThis[QUEUES_SYMBOL] = tails;
+/**
+* Enqueue `fn` onto the FIFO for `projectRoot`. The returned Promise
+* resolves/rejects with whatever `fn` does once every previously
+* enqueued job for this project has settled. A throwing `fn` does not
+* poison the queue: subsequent enqueues still run.
+*/
+function enqueue(projectRoot, fn) {
+	const result = (tails.get(projectRoot) ?? Promise.resolve()).then(fn, fn);
+	const next = result.then(() => void 0, () => void 0);
+	tails.set(projectRoot, next);
+	next.then(() => {
+		if (tails.get(projectRoot) === next) tails.delete(projectRoot);
+	});
+	return result;
+}
+const REGISTRY_SYMBOL = Symbol.for("pinagent.worktreeServers");
+const registry = globalThis[REGISTRY_SYMBOL] ?? /* @__PURE__ */ new Map();
+globalThis[REGISTRY_SYMBOL] = registry;
+const CLEANUP_SYMBOL = Symbol.for("pinagent.worktreeServersCleanup");
+if (!globalThis[CLEANUP_SYMBOL]) {
+	globalThis[CLEANUP_SYMBOL] = true;
+	const killAll = () => {
+		for (const id of [...registry.keys()]) killEntry(id);
+	};
+	process.once("exit", killAll);
+	process.once("SIGINT", killAll);
+	process.once("SIGTERM", killAll);
+}
+function killEntry(feedbackId) {
+	const entry = registry.get(feedbackId);
+	if (!entry) return;
+	registry.delete(feedbackId);
+	const pid = entry.child.pid;
+	if (pid === void 0) return;
+	try {
+		process.kill(-pid, "SIGTERM");
+	} catch {
+		try {
+			entry.child.kill("SIGTERM");
+		} catch {}
+	}
+}
+z.object({ feedbackIds: z.array(z.string().regex(ID_RE)).min(1).max(200) });
+z.object({
+	ids: z.array(z.string().regex(ID_RE)).min(1).max(200),
+	patch: z.object({ archived: z.boolean() })
+});
+z.object({ feedbackIds: z.array(z.string().regex(ID_RE)).min(1).max(200) });
+z.object({
+	feedbackIds: z.array(z.string().min(1)).min(1).max(50),
+	branchName: z.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9/_.-]*$/, "invalid branch name"),
+	title: z.string().min(1).max(200),
+	description: z.string().max(2e4),
+	baseBranch: z.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9/_.-]*$/, "invalid base branch")
+});
+/**
+* Phase H — orphan-worktree TTL sweep.
+*
+* On agent-runner boot, scan SQLite for conversations whose worktree has been
+* sitting in `worktreeState='active'` past the configured TTL. Add each one
+* to an in-memory set; next time the widget subscribes to that feedback,
+* the WS server overrides the initial `worktree_state` emission from
+* `active` to `ttl_warning` so the UI nudges the user to land or discard.
+*
+* We do NOT auto-discard: the user might genuinely want a multi-week
+* worktree, and silent data loss is the worst failure mode for a tool
+* whose pitch is "trust what the agents did". TTL is advisory only.
+*
+* Env:
+*   PINAGENT_WORKTREE_TTL_DAYS (default 7) — days since last update
+*     before a worktree is flagged. Set to 0 to disable the sweep.
+*/
+const DEFAULT_TTL_DAYS = 7;
+const TTL_SYMBOL = Symbol.for("pinagent.worktree-ttl.flagged");
+const flagged = globalThis[TTL_SYMBOL] ?? /* @__PURE__ */ new Set();
+globalThis[TTL_SYMBOL] = flagged;
+function ttlDays(env) {
+	const raw = env.PINAGENT_WORKTREE_TTL_DAYS;
+	if (raw === void 0 || raw === "") return DEFAULT_TTL_DAYS;
+	const n = Number(raw);
+	if (!Number.isFinite(n) || n < 0) return DEFAULT_TTL_DAYS;
+	return n;
+}
+/**
+* One-shot scan at startup. Idempotent — re-running just refreshes the
+* flag set. Best-effort; swallows DB errors so an agent-runner boot is
+* never blocked by a TTL sweep failure.
+*/
+async function sweepStaleWorktrees(projectRoot) {
+	const days = ttlDays(process.env);
+	if (days === 0) {
+		flagged.clear();
+		return;
+	}
+	try {
+		const cutoff = /* @__PURE__ */ new Date(Date.now() - days * 24 * 60 * 60 * 1e3);
+		const rows = await getDb(projectRoot).select({ id: conversations.id }).from(conversations).where(and$1(eq$1(conversations.worktreeState, "active"), lt(conversations.updatedAt, cutoff)));
+		flagged.clear();
+		for (const r of rows) flagged.add(r.id);
+	} catch {}
+}
+/**
+* True iff the most recent sweep flagged this conversation. Returns false
+* after the user has taken an action (land/discard) and `clearWarning`
+* was called.
+*/
+function isStale(feedbackId) {
+	return flagged.has(feedbackId);
+}
+/**
+* Drop a feedback from the flagged set. Called from the WS server's
+* `land_request` / `discard_request` handlers so the warning doesn't
+* reappear for repeat subscribes after the user has acted.
+*/
+function clearWarning(feedbackId) {
+	flagged.delete(feedbackId);
+}
+/**
+* Build a `noServer` WebSocket endpoint to hand to a host that owns its own
+* HTTP server and routes the `upgrade` event by pathname — notably Metro's
+* `config.server.websocketEndpoints` (React Native / Expo).
+*
+* Unlike {@link startWsServer}, this binds no port: the caller's dev server
+* (Metro) already listens, performs the HTTP upgrade, and dispatches matching
+* requests here via `handleUpgrade`. That means RN streaming rides the *same*
+* host:port the widget already talks to for `POST /__pinagent/feedback`, so a
+* physical device needs no second port and no port discovery.
+*
+* Each accepted socket is wired to the same {@link attachConnection} the web
+* path uses — identical wire protocol, bus subscription, and worktree
+* controls. We also start the project-event fan-out and relay (idempotent,
+* singleton-guarded) so worktree Land/Discard and cloud mode behave the same.
+*/
+function createPinagentWsEndpoint() {
+	const wss = new WebSocketServer({ noServer: true });
+	wss.on("connection", (socket) => {
+		attachConnection(socket);
+	});
+	sweepStaleWorktrees(projectRoot());
+	ensureProjectListener();
+	ensureCrossProcessProjectPoller();
+	maybeStartRelayClient();
+	return wss;
+}
+/**
+* Worktree-state fan-out: keyed by feedbackId, value is the set of
+* sockets currently subscribed. Lives separately from the
+* `event-bus` because worktree state is a property of the conversation
+* row (durable in SQLite) rather than an agent-run event — and changes
+* to it can happen long after the agent run's bus has been finished
+* and evicted. Survives module re-eval via globalThis pinning.
+*/
+const WT_SUBS_SYMBOL = Symbol.for("pinagent.ws.worktreeSubs");
+const worktreeSubs = globalThis[WT_SUBS_SYMBOL] ?? /* @__PURE__ */ new Map();
+globalThis[WT_SUBS_SYMBOL] = worktreeSubs;
+function addWorktreeSub(feedbackId, socket) {
+	let set = worktreeSubs.get(feedbackId);
+	if (!set) {
+		set = /* @__PURE__ */ new Set();
+		worktreeSubs.set(feedbackId, set);
+	}
+	set.add(socket);
+}
+function removeWorktreeSub(feedbackId, socket) {
+	const set = worktreeSubs.get(feedbackId);
+	if (!set) return;
+	set.delete(socket);
+	if (set.size === 0) worktreeSubs.delete(feedbackId);
+}
+function broadcastWorktreeState(feedbackId, payload) {
+	const set = worktreeSubs.get(feedbackId);
+	if (!set) return;
+	const msg = {
+		type: "worktree_state",
+		feedbackId,
+		...payload
+	};
+	for (const sock of set) send(sock, msg);
+}
+/**
+* Project-wide subscribers. Sockets self-register via `subscribe_project`
+* and receive `project_event` messages whenever Storage emits a change
+* (see project-events.ts). Lives separately from `worktreeSubs` because
+* it's not keyed by feedbackId — every project subscriber gets every
+* project event.
+*
+* Pinned via globalThis so Next 16 / HMR re-evaluation doesn't lose
+* subscribers across module reloads — same approach as worktreeSubs.
+*/
+const PROJECT_SUBS_SYMBOL = Symbol.for("pinagent.ws.projectSubs");
+const projectSubs = globalThis[PROJECT_SUBS_SYMBOL] ?? /* @__PURE__ */ new Set();
+globalThis[PROJECT_SUBS_SYMBOL] = projectSubs;
+/**
+* Singleton-guarded listener registration. `onProjectChange` returns an
+* unsubscribe handle; we keep the handle around the same global slot so
+* a duplicate `startWsServer` call doesn't stack listeners (which would
+* cause each event to fan out twice, then three times, etc).
+*/
+const PROJECT_LISTENER_SYMBOL = Symbol.for("pinagent.ws.projectListener");
+function ensureProjectListener() {
+	const slot = globalThis;
+	if (slot[PROJECT_LISTENER_SYMBOL]) return;
+	slot[PROJECT_LISTENER_SYMBOL] = onProjectChange((event) => fanoutProjectEvent(event));
+}
+/**
+* Watches `conversations.updatedAt` so writes from OTHER processes
+* (notably the MCP server's `resolve_feedback`, which runs as a child
+* Node process under the SDK and never touches our in-process
+* `emitProjectChange`) still trigger a dock refresh.
+*
+* Mirrors the polling pattern in `bus.ts` (per-conversation events).
+* Latency upper bound is one poll interval; the dock's TanStack Query
+* invalidation is idempotent, so the worst case if an in-process event
+* also fires is one extra refetch ~`POLL_MS` later — harmless.
+*
+* The initial watermark is seeded asynchronously; until the seed
+* resolves, the very first poll might fire a redundant
+* `conversations_changed`. That's acceptable: project subscribers
+* connect AFTER startWsServer, so they normally won't see it; if they
+* do, it's one wasted refetch on first connect.
+*/
+const PROJECT_POLLER_SYMBOL = Symbol.for("pinagent.ws.projectPoller");
+const PROJECT_POLL_MS = 250;
+function ensureCrossProcessProjectPoller() {
+	const slot = globalThis;
+	if (slot[PROJECT_POLLER_SYMBOL]) return;
+	let lastSeenMs = 0;
+	let polling = false;
+	(async () => {
+		try {
+			const ms = (await getDb(projectRoot()).select({ max: sql`MAX(${conversations.updatedAt})` }).from(conversations))[0]?.max ?? null;
+			if (ms !== null) lastSeenMs = Number(ms);
+		} catch {}
+	})();
+	const interval = setInterval(() => {
+		if (polling) return;
+		polling = true;
+		(async () => {
+			try {
+				const ms = (await getDb(projectRoot()).select({ max: sql`MAX(${conversations.updatedAt})` }).from(conversations))[0]?.max ?? null;
+				if (ms !== null && Number(ms) > lastSeenMs) {
+					lastSeenMs = Number(ms);
+					fanoutProjectEvent({ type: "conversations_changed" });
+				}
+			} catch {} finally {
+				polling = false;
+			}
+		})();
+	}, PROJECT_POLL_MS);
+	slot[PROJECT_POLLER_SYMBOL] = () => clearInterval(interval);
+}
+function fanoutProjectEvent(event) {
+	const msg = {
+		type: "project_event",
+		event
+	};
+	for (const sock of projectSubs) send(sock, msg);
+}
+/**
+* Connected VSCode-extension sockets, mapped to their reported version.
+* An entry exists for every socket that sent `extension_hello`. The dock
+* consults presence (size > 0) to decide whether to nudge the user to
+* install the editor bridge.
+*
+* Pinned to globalThis for the same Next-16 / HMR-survival reason as the
+* subscriber sets above — a module re-eval mustn't forget that an
+* extension is live and start telling docks it's missing.
+*/
+const EXTENSION_SOCKETS_SYMBOL = Symbol.for("pinagent.ws.extensionSockets");
+const extensionSockets = globalThis[EXTENSION_SOCKETS_SYMBOL] ?? /* @__PURE__ */ new Map();
+globalThis[EXTENSION_SOCKETS_SYMBOL] = extensionSockets;
+/**
+* Snapshot the current presence state. `version` is the last-registered
+* extension's version (newest connection wins) — good enough for the
+* single-editor common case; multi-window users just see one of them.
+*/
+function extensionStatusMessage() {
+	let version;
+	for (const v of extensionSockets.values()) if (v) version = v;
+	const msg = {
+		type: "extension_status",
+		present: extensionSockets.size > 0
+	};
+	if (version) msg.version = version;
+	return msg;
+}
+/** Push the current presence snapshot to every project subscriber. */
+function broadcastExtensionStatus() {
+	const msg = extensionStatusMessage();
+	for (const sock of projectSubs) send(sock, msg);
+}
+function projectRoot() {
+	return process.env.PINAGENT_PROJECT_ROOT ?? process.cwd();
+}
+function logPathFor(root, feedbackId) {
+	return join(root, ".pinagent", "logs", `${feedbackId}.md`);
+}
+const PING_INTERVAL_MS = 3e4;
+function attachConnection(socket) {
+	const state = {
+		subscriptions: /* @__PURE__ */ new Map(),
+		projectSubscribed: false,
+		alive: true
+	};
+	const ping = setInterval(() => {
+		if (!state.alive) {
+			socket.terminate();
+			return;
+		}
+		state.alive = false;
+		try {
+			socket.ping();
+		} catch {}
+	}, PING_INTERVAL_MS);
+	socket.on("pong", () => {
+		state.alive = true;
+	});
+	socket.on("message", (raw) => {
+		let parsed;
+		try {
+			parsed = JSON.parse(raw.toString("utf8"));
+		} catch {
+			sendError(socket, void 0, "invalid JSON");
+			return;
+		}
+		const validated = ClientMessageSchema.safeParse(parsed);
+		if (!validated.success) {
+			sendError(socket, void 0, `invalid message: ${validated.error.message}`);
+			return;
+		}
+		handleClientMessage(socket, state, validated.data);
+	});
+	socket.on("close", () => {
+		clearInterval(ping);
+		for (const [feedbackId, unsub] of state.subscriptions.entries()) {
+			unsub();
+			removeWorktreeSub(feedbackId, socket);
+		}
+		state.subscriptions.clear();
+		if (state.projectSubscribed) {
+			projectSubs.delete(socket);
+			state.projectSubscribed = false;
+		}
+		if (extensionSockets.delete(socket)) broadcastExtensionStatus();
+	});
+	socket.on("error", () => {});
+}
+async function handleClientMessage(socket, state, msg) {
+	switch (msg.type) {
+		case "subscribe": {
+			if (state.subscriptions.has(msg.feedbackId)) return;
+			const unsub = getOrCreateBus(msg.feedbackId).subscribe({
+				onEvent(event) {
+					send(socket, {
+						type: "event",
+						feedbackId: msg.feedbackId,
+						event
+					});
+				},
+				onClose() {
+					send(socket, {
+						type: "done",
+						feedbackId: msg.feedbackId
+					});
+					state.subscriptions.delete(msg.feedbackId);
+					removeWorktreeSub(msg.feedbackId, socket);
+				}
+			});
+			state.subscriptions.set(msg.feedbackId, unsub);
+			addWorktreeSub(msg.feedbackId, socket);
+			emitCurrentWorktreeState(socket, msg.feedbackId);
+			return;
+		}
+		case "unsubscribe": {
+			const unsub = state.subscriptions.get(msg.feedbackId);
+			if (unsub) {
+				unsub();
+				state.subscriptions.delete(msg.feedbackId);
+			}
+			removeWorktreeSub(msg.feedbackId, socket);
+			return;
+		}
+		case "ask_response":
+			if (!resolveAsk(msg.askId, msg.answer)) sendError(socket, void 0, `no pending ask ${msg.askId}`);
+			return;
+		case "user_message":
+			try {
+				await runFollowUpTurn(msg.feedbackId, msg.content);
+			} catch (err) {
+				sendError(socket, msg.feedbackId, err instanceof Error ? err.message : String(err));
+			}
+			return;
+		case "interrupt":
+			if (!await interruptRun(msg.feedbackId)) sendError(socket, msg.feedbackId, "no in-flight run to interrupt");
+			return;
+		case "land_request": {
+			const root = projectRoot();
+			const logPath = logPathFor(root, msg.feedbackId);
+			clearWarning(msg.feedbackId);
+			broadcastWorktreeState(msg.feedbackId, { state: "landing" });
+			const result = await enqueue(root, () => mergeWorktree(root, msg.feedbackId, logPath));
+			if (result.ok) broadcastWorktreeState(msg.feedbackId, {
+				state: "landed",
+				...result.commitSha ? { commitSha: result.commitSha } : {}
+			});
+			else if (result.conflicts && result.conflicts.length > 0) broadcastWorktreeState(msg.feedbackId, {
+				state: "conflict",
+				conflicts: result.conflicts
+			});
+			else broadcastWorktreeState(msg.feedbackId, {
+				state: "active",
+				...result.error ? { message: result.error } : {}
+			});
+			return;
+		}
+		case "discard_request": {
+			const root = projectRoot();
+			const logPath = logPathFor(root, msg.feedbackId);
+			clearWarning(msg.feedbackId);
+			broadcastWorktreeState(msg.feedbackId, { state: "discarding" });
+			try {
+				await enqueue(root, () => discardWorktree(root, msg.feedbackId, logPath));
+				broadcastWorktreeState(msg.feedbackId, { state: "discarded" });
+			} catch (err) {
+				broadcastWorktreeState(msg.feedbackId, {
+					state: "active",
+					message: err instanceof Error ? err.message : String(err)
+				});
+			}
+			return;
+		}
+		case "reopen_request": {
+			const root = projectRoot();
+			const logPath = logPathFor(root, msg.feedbackId);
+			const result = await enqueue(root, () => reopenConversation(root, msg.feedbackId, logPath));
+			if (result.ok) broadcastWorktreeState(msg.feedbackId, { state: "none" });
+			else sendError(socket, msg.feedbackId, result.error);
+			return;
+		}
+		case "subscribe_project":
+			if (state.projectSubscribed) return;
+			projectSubs.add(socket);
+			state.projectSubscribed = true;
+			send(socket, extensionStatusMessage());
+			return;
+		case "unsubscribe_project":
+			if (!state.projectSubscribed) return;
+			projectSubs.delete(socket);
+			state.projectSubscribed = false;
+			return;
+		case "extension_hello":
+			extensionSockets.set(socket, msg.version);
+			broadcastExtensionStatus();
+			return;
+		case "set_branch_routing": {
+			const patch = { allowedBranchPatterns: msg.allowedBranchPatterns };
+			if (msg.defaultBaseBranch !== null) patch.baseBranch = msg.defaultBaseBranch;
+			try {
+				await new SettingsStore(projectRoot()).patch(patch);
+			} catch (err) {
+				console.error("[pinagent] failed to apply pushed branch-routing policy:", err);
+			}
+			return;
+		}
+		case "query_extension":
+			send(socket, extensionStatusMessage());
+			return;
+		case "ping":
+			send(socket, { type: "pong" });
+			return;
+	}
+}
+async function emitCurrentWorktreeState(socket, feedbackId) {
+	try {
+		const rec = await new Storage(projectRoot()).read(feedbackId);
+		if (!rec) return;
+		const state = rec.worktreeState === "active" && isStale(feedbackId) ? "ttl_warning" : rec.worktreeState;
+		const payload = {
+			type: "worktree_state",
+			feedbackId,
+			state
+		};
+		if (rec.commitSha) payload.commitSha = rec.commitSha;
+		if (rec.worktreePath && (state === "active" || state === "ttl_warning")) {
+			const n = await countWorktreeChanges(rec.worktreePath);
+			if (n !== null) payload.changesCount = n;
+		}
+		send(socket, payload);
+	} catch {}
+}
+function send(socket, message) {
+	if (socket.readyState !== socket.OPEN) return;
+	try {
+		socket.send(JSON.stringify(message));
+	} catch {}
+}
+function sendError(socket, feedbackId, message) {
+	send(socket, feedbackId ? {
+		type: "error",
+		feedbackId,
+		message
+	} : {
+		type: "error",
+		message
+	});
+}
+const DEFAULT_MIN_BACKOFF_MS = 1e3;
+const DEFAULT_MAX_BACKOFF_MS = 3e4;
+const DEVICE_PATH = "/__pinagent/device";
+/** Build the relay's device-endpoint URL for a session. */
+function buildDeviceUrl(origin, sessionId) {
+	return `${origin.replace(/\/+$/, "")}${DEVICE_PATH}?session=${encodeURIComponent(sessionId)}`;
+}
+/**
+* Full-jitter exponential backoff: a random delay in `[exp/2, exp]` where
+* `exp = min(max, min * 2^attempt)`. Jitter avoids a thundering herd of
+* dev machines all reconnecting in lockstep after a relay blip.
+*/
+function nextBackoff(attempt, opts) {
+	const exp = Math.min(opts.max, opts.min * 2 ** attempt);
+	return Math.round(exp / 2 + Math.random() * (exp / 2));
+}
+function defaultConnect(url, token) {
+	return new WebSocket(url, { headers: { Authorization: `Bearer ${token}` } });
+}
+/**
+* Open and maintain the outbound device connection, reconnecting with
+* backoff on any drop. Returns a handle whose `close()` stops reconnecting
+* and tears down the current socket.
+*/
+function startRelayClient(opts) {
+	const min = opts.minBackoffMs ?? DEFAULT_MIN_BACKOFF_MS;
+	const max = opts.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
+	const connect = opts.connect ?? defaultConnect;
+	const attach = opts.attach ?? attachConnection;
+	const schedule = opts.schedule ?? ((fn, ms) => void setTimeout(fn, ms));
+	const log = opts.log ?? ((msg) => console.log(`[pinagent] ${msg}`));
+	const deviceUrl = buildDeviceUrl(opts.url, opts.sessionId);
+	let stopped = false;
+	let attempt = 0;
+	let socket = null;
+	const open = () => {
+		if (stopped) return;
+		const ws = connect(deviceUrl, opts.token);
+		socket = ws;
+		ws.on("open", () => {
+			attempt = 0;
+			log(`relay connected (${deviceUrl})`);
+			attach(ws);
+		});
+		ws.on("close", () => {
+			if (stopped) return;
+			const delay = nextBackoff(attempt++, {
+				min,
+				max
+			});
+			log(`relay disconnected; reconnecting in ${delay}ms`);
+			schedule(open, delay);
+		});
+		ws.on("error", () => {});
+	};
+	open();
+	return { close() {
+		stopped = true;
+		try {
+			socket?.close();
+		} catch {}
+	} };
+}
+/**
+* Derive a stable session id from the project root when one isn't supplied
+* via env. Stable across restarts (so a machine reconnects to its own
+* Durable Object) and opaque (doesn't leak the filesystem path).
+*/
+function defaultSessionId() {
+	const root = process.env.PINAGENT_PROJECT_ROOT ?? process.cwd();
+	return createHash("sha256").update(root).digest("hex").slice(0, 16);
+}
+const RELAY_CLIENT_SYMBOL = Symbol.for("pinagent.relayClient");
+/**
+* Start the dial-out client iff cloud mode is configured. Reads:
+*   - `PINAGENT_RELAY_URL`     (required to enable; e.g. wss://relay.pinagent.dev)
+*   - `PINAGENT_RELAY_TOKEN`   (required; bearer token for the relay — must be a
+*      `device`-scoped session token; the relay rejects a `client` token on the
+*      device endpoint)
+*   - `PINAGENT_RELAY_SESSION` (optional; defaults to a hash of the project root)
+*
+* Singleton-guarded via globalThis for the same Next-16 / HMR re-eval
+* reason the ws-server subscriber sets are pinned — a module reload mustn't
+* open a second device connection.
+*/
+function maybeStartRelayClient() {
+	const url = process.env.PINAGENT_RELAY_URL;
+	const token = process.env.PINAGENT_RELAY_TOKEN;
+	if (!url || !token) return null;
+	const g = globalThis;
+	const existing = g[RELAY_CLIENT_SYMBOL];
+	if (existing) return existing;
+	const handle = startRelayClient({
+		url,
+		token,
+		sessionId: process.env.PINAGENT_RELAY_SESSION ?? defaultSessionId()
+	});
+	g[RELAY_CLIENT_SYMBOL] = handle;
+	return handle;
+}
+const CONVENTIONAL_SPEC = [
+	"Format the subject as a Conventional Commit: `type(scope): summary`.",
+	"- type is one of: feat, fix, chore, docs, refactor, test, perf, build, ci.",
+	"- scope is the main area changed, inferred from the file paths in the diff",
+	"  (e.g. dock, widget, agent-runner, mcp, vite-plugin, next-plugin, ui, db).",
+	"  Omit the parentheses only if the change is genuinely repo-wide.",
+	"- summary is concise, imperative, lowercase, no trailing period, <70 chars.",
+	"Examples: \"fix(dock): commit working changes before opening the PR\",",
+	"\"feat(widget): add multi-element selection\"."
+].join("\n");
+[
+	"You write pull-request descriptions for Pinagent, a click-to-fix dev tool.",
+	"You are given a git diff and commit log for a feature branch.",
+	"Respond with ONLY a single JSON object, no prose, no code fences:",
+	"{ \"title\": \"<Conventional Commits PR title>\", \"body\": \"<markdown body>\" }",
+	"",
+	CONVENTIONAL_SPEC,
+	"",
+	"The body should open with a one-paragraph summary, then a \"## Changes\"",
+	"section with bullet points of what changed and why. Keep it factual and",
+	"grounded in the diff. End the body with this exact line (keep the link):",
+	"🤖 Generated with [Pinagent](https://pinagent.dev)"
+].join("\n");
+[
+	"You write git commit messages. You are given a diff of uncommitted changes.",
+	"Respond with ONLY the commit message: a subject line, then optionally a",
+	"blank line and a short body. No prose, no code fences, no quotes.",
+	"",
+	CONVENTIONAL_SPEC
+].join("\n");
+//#endregion
+//#region src/server/ws-endpoint.ts
+/**
+* Returns the `{ [path]: ws.Server }` map to spread into Metro's
+* `config.server.websocketEndpoints`. Mounts the Pinagent stream at
+* `/__pinagent/ws`.
+*/
+function pinagentWebsocketEndpoints(opts) {
+	if (!process.env.PINAGENT_PROJECT_ROOT) process.env.PINAGENT_PROJECT_ROOT = opts.projectRoot;
+	return { "/__pinagent/ws": createPinagentWsEndpoint() };
+}
+/** Per-server guard so we only take over the `upgrade` event once. */
+const UPGRADE_HOOKED = Symbol.for("pinagent.rn.upgradeHooked");
+/**
+* Idempotently mount `/__pinagent/ws` on a live HTTP server, regardless of
+* whether the host honors `config.server.websocketEndpoints`.
+*
+* Expo's dev server registers a single `upgrade` listener that destroys any
+* path it doesn't know, so simply *adding* a second listener races with that
+* destroy. Instead we take the listener over: capture whatever `upgrade`
+* listeners are already attached (Metro's `/hot`, Expo's devtools/debugger
+* sockets, …), remove them, and install one router that handles
+* `/__pinagent/ws` itself and delegates every other path back to the captured
+* listeners untouched. HMR and the rest keep working; our path no longer gets
+* destroyed out from under us.
+*
+* Called lazily from `pinagentMiddleware` with `req.socket.server` — by the
+* time any HTTP request reaches the middleware the dev server is listening and
+* its own `upgrade` listener is already registered, so the capture is complete.
+*/
+function ensurePinagentUpgrade(server) {
+	const flagged = server;
+	if (flagged[UPGRADE_HOOKED]) return;
+	flagged[UPGRADE_HOOKED] = true;
+	const wss = createPinagentWsEndpoint();
+	const prior = server.listeners("upgrade");
+	server.removeAllListeners("upgrade");
+	server.on("upgrade", (req, socket, head) => {
+		let pathname = "";
+		try {
+			pathname = new URL(req.url ?? "", "http://localhost").pathname;
+		} catch {
+			pathname = (req.url ?? "").split("?")[0] ?? "";
+		}
+		if (pathname === "/__pinagent/ws") {
+			wss.handleUpgrade(req, socket, head, (ws) => wss.emit("connection", ws, req));
+			return;
+		}
+		for (const fn of prior) fn.call(server, req, socket, head);
+	});
+}
+//#endregion
+//#region src/server/metro-middleware.ts
+/**
+* Metro dev-server adapter for Pinagent.
+*
+* This is a near-copy of the `POST /__pinagent/feedback` arm of
+* `packages/vite-plugin/src/middleware.ts`. It reuses the existing
+* backend verbatim — `Storage` (writes to `.pinagent/db.sqlite` +
+* screenshots), `FeedbackInputSchema` (the wire contract), and
+* `spawnAgent` (inline / worktree agent runs). Nothing about agent
+* pickup is RN-specific; only the route mounting differs.
+*
+* Wire it in `metro.config.js`:
+*
+*   const { pinagentMiddleware } = require('@pinagent/react-native/server');
+*   module.exports = {
+*     server: {
+*       enhanceMiddleware: (metroMiddleware, server) =>
+*         pinagentMiddleware({ projectRoot: __dirname }).chain(metroMiddleware),
+*     },
+*   };
+*
+* `.chain(next)` returns a single connect handler that runs our routes
+* first and defers everything else to Metro's own middleware.
+*/
+const MAX_BODY_BYTES = 8 * 1024 * 1024;
+function pinagentMiddleware(opts) {
+	const storage = new Storage(opts.projectRoot);
+	const spawnMode = opts.spawnMode ?? "inline";
+	if (!process.env.PINAGENT_PROJECT_ROOT) process.env.PINAGENT_PROJECT_ROOT = opts.projectRoot;
+	if (opts.apiKey) process.env.PINAGENT_AGENT_API_KEY = opts.apiKey;
+	const handler = (async (req, res, next) => {
+		const server = req.socket?.server;
+		if (server) ensurePinagentUpgrade(server);
+		const url = req.url ?? "";
+		if (!url.startsWith("/__pinagent")) return next();
+		try {
+			if (req.method === "POST" && url === "/__pinagent/feedback") {
+				const raw = await readJsonBody(req);
+				const parsed = FeedbackInputSchema.safeParse(raw);
+				if (!parsed.success) return badRequest(res, parsed.error.message);
+				if (Buffer$1.from(parsed.data.screenshot, "base64").length > 5 * 1024 * 1024) return badRequest(res, "screenshot exceeds 5MB");
+				const id = nanoid(10);
+				const rec = await storage.create(id, parsed.data);
+				const agentSpawned = spawnMode !== false;
+				if (agentSpawned) try {
+					await spawnAgent({
+						projectRoot: storage.root,
+						feedback: rec,
+						mode: spawnMode
+					});
+				} catch {}
+				return json(res, 200, {
+					id: rec.id,
+					agentSpawned
+				});
+			}
+			if (req.method === "GET" && url === "/__pinagent/feedback") return json(res, 200, await storage.list());
+			if (req.method === "POST" && url === "/__pinagent/open") {
+				const raw = await readJsonBody(req);
+				const file = typeof raw?.file === "string" ? raw.file : "";
+				if (!file) return badRequest(res, "missing file");
+				const abs = resolve(opts.projectRoot, file);
+				const rel = relative(opts.projectRoot, abs);
+				if (rel.startsWith("..") || isAbsolute(rel)) return badRequest(res, "path outside project root");
+				return json(res, 200, { ok: openInEditor(abs, Number.isFinite(Number(raw?.line)) ? Number(raw?.line) : 1, Number.isFinite(Number(raw?.col)) ? Number(raw?.col) : 1) });
+			}
+			return json(res, 404, { error: "not found" });
+		} catch (err) {
+			return json(res, 500, { error: err instanceof Error ? err.message : String(err) });
+		}
+	});
+	handler.chain = (nextMw) => {
+		return (req, res, next) => {
+			if ((req.url ?? "").startsWith("/__pinagent")) handler(req, res, () => nextMw(req, res, next));
+			else nextMw(req, res, next);
+		};
+	};
+	return handler;
+}
+function readJsonBody(req) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let total = 0;
+		req.on("data", (chunk) => {
+			total += chunk.length;
+			if (total > MAX_BODY_BYTES) {
+				reject(/* @__PURE__ */ new Error("payload too large"));
+				req.destroy();
+				return;
+			}
+			chunks.push(chunk);
+		});
+		req.on("end", () => {
+			if (chunks.length === 0) return resolve(null);
+			try {
+				resolve(JSON.parse(Buffer$1.concat(chunks).toString("utf8")));
+			} catch (e) {
+				reject(e);
+			}
+		});
+		req.on("error", reject);
+	});
+}
+function json(res, status, body) {
+	res.statusCode = status;
+	res.setHeader("Content-Type", "application/json; charset=utf-8");
+	res.setHeader("Cache-Control", "no-store");
+	res.end(JSON.stringify(body));
+}
+function badRequest(res, msg) {
+	json(res, 400, { error: msg });
+}
+/** Find an executable on `PATH`. Returns the full path, or null. */
+function findOnPath(bin) {
+	for (const dir of (process.env.PATH ?? "").split(delimiter)) if (dir && existsSync(join(dir, bin))) return join(dir, bin);
+	return null;
+}
+const CLI_EDITORS = [
+	{
+		bin: "code",
+		args: ["-g"]
+	},
+	{
+		bin: "cursor",
+		args: ["-g"]
+	},
+	{
+		bin: "windsurf",
+		args: ["-g"]
+	},
+	{
+		bin: "code-insiders",
+		args: ["-g"]
+	},
+	{
+		bin: "codium",
+		args: ["-g"]
+	},
+	{
+		bin: "zed",
+		args: []
+	},
+	{
+		bin: "subl",
+		args: []
+	}
+];
+const MAC_APPS = [
+	{
+		app: "Cursor",
+		args: ["-g"]
+	},
+	{
+		app: "Visual Studio Code",
+		args: ["-g"]
+	},
+	{
+		app: "Windsurf",
+		args: ["-g"]
+	},
+	{
+		app: "VSCodium",
+		args: ["-g"]
+	},
+	{
+		app: "Zed",
+		args: []
+	},
+	{
+		app: "Sublime Text",
+		args: []
+	}
+];
+/**
+* Pick a command that can open a `file:line:col` target. Order:
+* `PINAGENT_EDITOR` (explicit) → a known editor CLI on `PATH` → a known macOS
+* editor app. Returns null if nothing suitable is found.
+*/
+function resolveOpener() {
+	const override = process.env.PINAGENT_EDITOR?.trim();
+	if (override) {
+		const [cmd, ...prefixArgs] = override.split(/\s+/);
+		if (cmd) return {
+			cmd,
+			prefixArgs
+		};
+	}
+	for (const e of CLI_EDITORS) if (findOnPath(e.bin)) return {
+		cmd: e.bin,
+		prefixArgs: e.args
+	};
+	if (process.platform === "darwin") {
+		for (const a of MAC_APPS) if (existsSync(`/Applications/${a.app}.app`)) return {
+			cmd: "open",
+			prefixArgs: [
+				"-a",
+				a.app,
+				"--args",
+				...a.args
+			]
+		};
+	}
+	return null;
+}
+/**
+* Open `<file>:<line>:<col>` in the developer's editor (see
+* {@link resolveOpener} for selection). Best-effort and fully detached — a
+* missing editor must never crash Metro. Returns whether a launch was
+* attempted, so the device can tell the developer when no editor was found.
+*/
+function openInEditor(abs, line, col) {
+	const opener = resolveOpener();
+	if (!opener) return false;
+	const target = `${abs}:${line}:${col}`;
+	try {
+		const child = spawn(opener.cmd, [...opener.prefixArgs, target], {
+			stdio: "ignore",
+			detached: true
+		});
+		child.on("error", () => {});
+		child.unref();
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { ensurePinagentUpgrade, pinagentMiddleware, pinagentWebsocketEndpoints };
+
+//# sourceMappingURL=server.js.map