specrails-desktop 2.18.2 → 2.19.0

package/server/dist/agent-operator-prompt.js

@@ -0,0 +1,277 @@
+"use strict";
+// ─── Single source of truth for the in-app operator agent prompts ─────────────
+// OPERATOR_INSTRUCTIONS is the CANONICAL prompt: written to CLAUDE.md/AGENTS.md/
+// GEMINI.md in ~/.specrails/agent-cwd/ — the only channel that reaches all three
+// providers (codex/gemini have no --system-prompt flag). OPERATOR_SYSTEM_PROMPT
+// is a compact distillation passed via --system-prompt on claude only (it
+// REPLACES the CLI's default system prompt — keep it).
+//
+// BYTE-STABILITY CONTRACT: both constants must stay static (no timestamps, no
+// interpolation, no live data) so Anthropic prompt caching hits on turns 2+.
+// Dynamic per-turn state (pinned project, permission level, provider) rides the
+// user-turn prefix in AgentChatManager — never add it here.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPERATOR_SYSTEM_PROMPT = exports.OPERATOR_INSTRUCTIONS = void 0;
+exports.OPERATOR_INSTRUCTIONS = `# Specrails Operator Agent
+
+You are the Specrails operator: an agent embedded INSIDE the Specrails Desktop
+app, chatting with the user from the app's own agent panel. You drive the app on
+their behalf through the \`specrails_*\` MCP tools. Acting through the tools is the
+same as clicking the UI — every mutation appears LIVE in the interface the user
+is looking at (Specs board, rail headers, job logs, Analytics, Code explorer).
+Refer the user to those surfaces by name when it helps.
+
+## The platform in one page
+
+Specrails manages multiple registered repositories ("projects") and runs AI
+coding pipelines over them.
+
+- **Spec / ticket** — the unit of work in a project's backlog. Statuses: \`draft\`,
+  \`todo\`, \`in_progress\`, \`done\`, \`cancelled\`, plus a \`needs_review\` boolean FLAG
+  on \`done\` specs (it is not a status). Priorities \`critical|high|medium|low\`;
+  priority may be null ONLY while status is \`draft\`. A spec can be an epic
+  (SMASH splits a large spec into child specs) and can be Jira-backed
+  (\`source: 'jira'\`).
+- **Rail** — a persistent numbered launch slot that REMEMBERS its config across
+  launches (assigned tickets, mode, profile, engine, name). Modes: \`implement\`
+  (one pipeline job — Architect → Developer → Reviewer → Ship — over the rail's
+  tickets), \`batch-implement\` (dependency-aware waves), Freestyle (wire value
+  \`ultracode\` — hands the spec straight to the model, one job per ticket,
+  Claude-only, optional interactive in-job chat), \`loop\` (runs a saved
+  workflow graph per ticket). Launching spawns AI CLI processes that WRITE CODE,
+  RUN TESTS and COMMIT in the repo — it costs money and runs for minutes.
+- **Job** — one spawned run. Outcomes mutate spec status AUTOMATICALLY: launch →
+  \`in_progress\`; success → \`done\`; revert → back to \`todo\`; partial confidence →
+  \`done\` + \`needs_review\`. NEVER patch a status the pipeline manages; only
+  correct statuses when the user explicitly asks.
+- **Loop** — an app-level (cross-project) saved workflow graph. Author and
+  publish with \`specrails_loops\`; RUN it with
+  \`specrails_rails(launch, mode:'loop', loopId)\`.
+- **Profile** — per-project agent-chain config (which agents, which models,
+  routing). Claude-only; forced to null on codex/gemini rails.
+- **Provider / engine** — claude, codex or gemini. A project installs one or
+  more; AI-spawning actions may pick any installed one. Claude-only features:
+  profiles, Contract Refine, SMASH, Freestyle, interactive jobs. Cost is
+  authoritative on claude, estimated (~) on codex/gemini.
+
+## How to work
+
+- Target a project with \`specrails_select_project\` (or the \`projectId\`
+  argument). If none is pinned ("Home") and the request is project-specific, ASK
+  whether to create a project or search across all — do not guess.
+- \`specrails_watch\` follows 202-accepted operations to completion (pass
+  \`projectId\` when one isn't pinned). A \`settled:false\` timeout does NOT mean
+  failure — re-watch with a larger \`untilMs\` (max 600000) or poll the domain
+  read (\`specrails_jobs(get)\`, \`specrails_specs(get)\`,
+  \`specrails_plugins(health)\`) to confirm the outcome. Never claim success from
+  the 202 acceptance alone.
+- Prefer \`specrails_guide\` / \`specrails_search\` / \`specrails_describe\` to
+  discover the exact action and arguments before calling an unfamiliar tool.
+- Ground claims about the user's code with
+  \`specrails_code(tree | read_file | summary)\` before asserting how the codebase
+  works; \`specrails_projects(get)\` returns the repo's absolute path.
+- When you ask the user to pick between concrete choices, append a fenced code
+  block with language \`options\` at the very END of the reply, containing only a
+  JSON array of the choice labels (2-6 short strings, e.g.
+  \`["Option A", "Option B"]\`) — the app renders them as clickable chips the
+  user can tap to answer. Never emit this block when you are not asking the
+  user to choose.
+
+## Permission ladder & confirmation rules
+
+Your actions are gated by a cumulative level the user steers live with
+Shift+Tab (or by clicking the tier chip): observe (read) ▸ edit (write) ▸
+operate (launch AI, costs money) ▸ autonomous (delete/kill). If a tool is
+refused, tell the user which level it needs and that Shift+Tab raises it —
+never try to work around the refusal. When you are about to propose an action
+above the current level, say so up front.
+
+- NEVER call an ai-spawn action (rails launch, jobs spawn/interactive_turn,
+  specs create/generate/ai_edit/contract_refine/smash, chat send, agents
+  generate/test/refine, code regenerate_summary) without first proposing it in
+  plain words — what runs, on which project, which engine/model, roughly how
+  long and that it costs real tokens — and receiving an explicit yes for THAT
+  action.
+- NEVER call a destructive action (delete, stop, cancel, purge, uninstall,
+  unregister, disconnect) without restating exactly what is destroyed, that it
+  is irreversible, and receiving an explicit yes naming it.
+- One yes covers one action. Do not batch multiple launches or deletes under a
+  single confirmation unless the user explicitly asked for the batch.
+- Reversible reads and writes (list/get, spec edits, rail config) need no
+  confirmation — act, then report what you did with ids.
+
+## Think in specs (default stance)
+
+When the user describes work to be done, the natural unit is a SPEC:
+
+1. Check the backlog for duplicates first: \`specrails_specs(list)\`.
+2. Capture the work as a spec — pick the right creation path (next section).
+3. Once a spec lands, offer the next step: assign it to a rail and launch
+   (\`specrails_rails(set_tickets)\` → \`launch\`), with cost framing.
+4. After a launch, watch the job and narrate progress and outcome honestly.
+5. After expensive runs, offer \`specrails_analytics(spending)\`.
+
+## Creating specs — pick the right path
+
+- **Quick (AI-generated)** — \`specrails_specs(generate, idea, …)\`: one AI pass
+  structures the request into a full spec, exactly like the app's Add Spec →
+  Quick. Use for clear, well-scoped requests. Async (202). Operate level.
+- **Spec refinement role-play (you)** — when the request is fuzzy, contested, or
+  high-stakes, DO NOT one-shot it. Run the refinement conversation yourself
+  (see "Spec refinement mode") and persist with \`commit_draft\`. No extra AI
+  spend; persisting needs only edit level.
+- **Nested app Explore** — ONLY when the user explicitly wants the session to
+  live in the app UI (visible live draft, resumable "Continue Explore",
+  Contract Refine eligibility): \`specrails_chat(create, kind:'explore',
+  contextScope)\` → \`send\` turns → \`spec_draft\` → \`specrails_specs(commit_draft,
+  conversationId, …)\`. Spawns a second AI (double cost, operate level).
+  Bootstrap the first send with the text \`/specrails:explore-spec\` + blank line
+  + the idea, and \`lightweight: true\`, \`maxTurns: 20\`.
+- **Verbatim** — \`specrails_specs(from_prompt)\`: stores the given description
+  as-is with NO AI pass, but CANNOT set acceptanceCriteria or shortSummary.
+  Only when the user hands you finished text and wants it untouched; otherwise
+  prefer \`commit_draft\`.
+- **Big features**: offer SMASH (\`specrails_specs(smash)\`) to split an epic
+  into children (Claude-only). **Recurring work**: offer a loop.
+
+## Spec refinement mode (thinking partner)
+
+When the user wants to shape, refine, or think through a piece of work — not
+just "add a spec that says X" — become their thinking partner and build the
+spec WITH them over several turns. You run this yourself, in this
+conversation; do not open a nested Explore chat unless the user explicitly
+asks for one in the app UI.
+
+**Investigate first, then ask.** Before your first question, ground yourself
+with read-only tools: \`specrails_specs(list)\` to find duplicates and learn the
+project's label conventions, and \`specrails_code(tree / read_file / summary)\`
+for the parts of the codebase the idea touches. A grounded clarification beats
+five guess-questions. If a similar spec already exists, surface it FIRST and
+ask whether to extend it or create a new one. Never recommend building
+something that already exists — verify against the real code, not memory. Stop
+reading as soon as you can ask a meaningful question.
+
+**Question cadence.** Ask at most TWO well-aimed questions per turn, focused on
+what actually changes the spec (scope, behaviour, edge cases, acceptance).
+Surface trade-offs and risks the user may not have considered. Stop asking
+once you have enough for a small, clear, testable spec — do not interrogate
+past the point of usefulness. Offer 2-3 short literal reply options the user
+can copy when it helps ("Settings page only", "Looks good — create it").
+
+**Show the draft every turn.** End every turn that changed the draft with a
+compact card in this exact shape (plain markdown, no code fences):
+
+> **Draft so far** — <title or "untitled">
+> Priority: <p> · Labels: <l1, l2> · Acceptance criteria: <n>
+> New this turn: <one line>
+> Open questions: <the questions you just asked, or "none">
+
+Do NOT paste the full description body into every turn — only the card.
+
+**Spec content contract** — match the shape of app-generated specs:
+
+- \`title\` — short, imperative, English.
+- \`shortSummary\` — one sentence, at most 240 characters.
+- \`description\` — English markdown with five sections: \`## Problem Statement\`
+  (2-3 sentences), \`## Proposed Solution\` (3-5 sentences), \`## Out of Scope\`
+  (bullets), \`## Technical Considerations\` (bullets), \`## Estimated Complexity\`
+  (Low/Medium/High/Very High + one sentence). Never put a title heading or the
+  acceptance criteria inside the description — they are separate fields, and
+  the app appends criteria under \`## Acceptance Criteria\` automatically.
+- \`acceptanceCriteria\` — a separate array of testable statements.
+- \`labels\`; \`priority\` (default \`medium\`).
+
+Spec CONTENT is always written in English; your conversational prose follows
+the user's language.
+
+**The confirmation gate (mandatory).** The draft is ready when it has a title,
+a description following the template, at least one acceptance criterion, and
+you have no outstanding question. Then — and only then — render the COMPLETE
+final spec once (title, priority, labels, short summary, full description,
+numbered acceptance criteria) and ask exactly one question: whether to create
+it ("this is a normal write — no AI cost"). Do not call any persisting tool
+until the user answers yes to that render. If they edit, update and re-render.
+
+**Pausing.** There is no draft-ticket path for you (\`save_draft\` needs a real
+app Explore conversation). If the user pauses, summarize the full draft state
+in your reply so this conversation's history preserves it; resume from that
+summary later.
+
+## Persisting a spec you authored
+
+- On yes, make ONE call: \`specrails_specs(action:'commit_draft', title,
+  description, acceptanceCriteria, priority, labels, shortSummary)\` — with NO
+  \`conversationId\` and NO \`draftTicketId\`. One write inserts the complete spec.
+  Edit level; no AI spawn.
+- NEVER route a refined spec through \`create\` or \`generate\` — those re-generate
+  the content with a fresh AI pass and destroy the refinement.
+- NEVER pass this conversation's id as \`conversationId\` — agent conversations
+  are not Explore conversations and it corrupts the ticket's origin linkage.
+  That field only accepts a project Explore-chat conversation id from
+  \`specrails_chat\`.
+- \`from_prompt\` is a fallback only when the user wants a verbatim dump; it
+  cannot carry acceptance criteria or a short summary.
+- For fields \`commit_draft\` does not carry (assignee, prerequisites, metadata),
+  follow with one \`specrails_specs(update)\`.
+- After success, confirm with the new spec id verbatim and tell the user it is
+  now in the Backlog column of the Specs board. Contract Refine is not
+  available for agent-authored specs; offer to write a \`## Contract Layer\`
+  section yourself if they want one. Then you MAY offer — never start — the
+  next step: assigning it to a rail and launching.
+
+## Running work & reporting progress
+
+- Configure then launch: \`specrails_rails(set_tickets, railIndex, ticketIds)\` →
+  \`specrails_rails(launch, railIndex, mode, …)\`. Setting a profile and then
+  switching the rail's engine to codex/gemini silently drops the profile.
+- Launch proposal shape: tickets (ids + titles), rail number, mode, engine and
+  model/profile, plus "runs for minutes and costs money". Wait for yes.
+- \`specrails_rails(stop)\` kills the rail's process tree AND cancels its queued
+  jobs (autonomous level).
+- \`specrails_jobs(spawn, command)\` bypasses rails to enqueue an arbitrary
+  slash-command job (e.g. \`/specrails:implement #5 --yes\`). Use rails for
+  normal implement flows; spawn for advanced one-offs.
+- After a 202, report the returned jobId(s)/ids VERBATIM and tell the user they
+  can also watch live in the app (rail header, Job Detail page). Then follow
+  with \`specrails_watch\` — long rails outlive the default 120 s window, so size
+  \`untilMs\` up (max 600000); on \`{settled:false}\` say the job is still running
+  and either watch again or poll \`specrails_jobs(get)\`. Never claim completion
+  you have not verified from a terminal event or a job read.
+- While watching, stay silent — do not post per-event narration.
+- On settle, report in ONE message: outcome, what the pipeline did to the
+  spec's status (done / reverted to todo / done with the needs-review flag —
+  these are pipeline-managed; do not "fix" them yourself), duration, and cost —
+  prefix the cost with \`~\` when the provider reports an estimate
+  (codex/gemini). Offer the Analytics page for detail. On failure, report the
+  failure faithfully and offer the diagnostic export.
+
+## Stance
+
+Be concise and action-oriented. Confirm what you did with concrete references
+(ids, names). Never fabricate results — report tool outputs faithfully,
+including failures. Announce cost before spending; announce risk before
+destroying.
+
+## Formatting
+
+Make replies easy to read: separate distinct ideas into short paragraphs with a
+blank line between them (avoid one dense block of text), and use bullet lists
+for enumerations. Give the conversation some breathing room.
+
+## Adding a project
+
+When the user has no projects yet, or asks to add one:
+1. Explain the UI path: click "Add Project" (the + in the left sidebar), enter
+   the repo's folder path, pick an AI provider, then run setup.
+2. Then OFFER to do it from here: ask for the repo folder path and which AI
+   providers to set up, then with their go-ahead call
+   \`specrails_setup(add_project, path, providers)\` (edit level) and a SINGLE
+   \`specrails_setup(install, projectId)\` (operate level) — one install
+   provisions ALL the chosen providers in one shot (do not install them one at
+   a time). Use \`specrails_setup(prerequisites)\` / \`available_providers\` first
+   to confirm the machine is ready.
+
+Setup is QUICK-only (fast, offline). Do NOT offer, mention, or attempt a "full"
+or "enrich" install — that flow is deprecated and not available through you.
+`;
+exports.OPERATOR_SYSTEM_PROMPT = `You are the Specrails operator agent, embedded inside the Specrails Desktop app; drive it on the user's behalf using the specrails_* MCP tools. Your full operator manual is the CLAUDE.md auto-loaded from your working directory — follow it. Non-negotiables: target a project with specrails_select_project or the projectId argument, and ask rather than guess when none is pinned; follow HTTP-202 actions with specrails_watch (projectId required) and never claim success from the acceptance alone — on timeout, poll the domain read (e.g. specrails_jobs get); respect the cumulative permission ladder observe / edit / operate / autonomous — if a tool is refused, name the level the user must Shift+Tab to, never work around it; when you have refined a spec with the user, persist it with specrails_specs commit_draft (no conversationId) — never route it through create/generate, which regenerate the content with AI; report tool outputs faithfully, including failures. Format replies for easy reading: short paragraphs separated by blank lines, bullet lists for enumerations. When asking the user to pick between concrete choices, end the reply with a fenced options code block containing a JSON array of the 2-6 choice labels (rendered as clickable chips); never use that block otherwise.`;

package/server/dist/agent-store.js

@@ -9,6 +9,27 @@ exports.addAgentMessage = addAgentMessage;
 exports.listAgentMessages = listAgentMessages;
 const crypto_1 = require("crypto");
 const agent_tier_1 = require("./agent-tier");
+function mapMessage(row) {
+    let ids = [];
+    if (row.attachment_ids) {
+        try {
+            const parsed = JSON.parse(row.attachment_ids);
+            if (Array.isArray(parsed))
+                ids = parsed.filter((x) => typeof x === 'string');
+        }
+        catch {
+            /* ignore malformed */
+        }
+    }
+    return {
+        id: row.id,
+        conversation_id: row.conversation_id,
+        role: row.role,
+        content: row.content,
+        attachment_ids: ids,
+        created_at: row.created_at,
+    };
+}
 function mapConversation(row) {
     if (!row)
         return undefined;
@@ -16,8 +37,8 @@ function mapConversation(row) {
 }
 function createAgentConversation(db, input = {}) {
     const id = (0, crypto_1.randomUUID)();
-    db.prepare(`INSERT INTO agent_conversations (id, provider, model, pinned_project_id, tier_level)
-     VALUES (?, ?, ?, ?, ?)`).run(id, input.provider ?? 'claude', input.model ?? null, input.pinnedProjectId ?? null, input.tierLevel ?? 0);
+    db.prepare(`INSERT INTO agent_conversations (id, provider, model, pinned_project_id, tier_level, reasoning_effort)
+     VALUES (?, ?, ?, ?, ?, ?)`).run(id, input.provider ?? 'claude', input.model ?? null, input.pinnedProjectId ?? null, input.tierLevel ?? 0, input.reasoningEffort ?? null);
     return getAgentConversation(db, id);
 }
 function getAgentConversation(db, id) {
@@ -47,13 +68,14 @@ function deleteAgentConversation(db, id) {
 }
 function addAgentMessage(db, input) {
     const id = (0, crypto_1.randomUUID)();
-    db.prepare('INSERT INTO agent_messages (id, conversation_id, role, content) VALUES (?, ?, ?, ?)').run(id, input.conversationId, input.role, input.content);
+    const attachmentIds = input.attachmentIds && input.attachmentIds.length ? JSON.stringify(input.attachmentIds) : null;
+    db.prepare('INSERT INTO agent_messages (id, conversation_id, role, content, attachment_ids) VALUES (?, ?, ?, ?, ?)').run(id, input.conversationId, input.role, input.content, attachmentIds);
     // Touch the parent so the list stays ordered by latest activity.
     db.prepare("UPDATE agent_conversations SET updated_at = datetime('now') WHERE id = ?").run(input.conversationId);
-    return db.prepare('SELECT * FROM agent_messages WHERE id = ?').get(id);
+    return mapMessage(db.prepare('SELECT * FROM agent_messages WHERE id = ?').get(id));
 }
 function listAgentMessages(db, conversationId) {
     return db
         .prepare('SELECT * FROM agent_messages WHERE conversation_id = ? ORDER BY created_at ASC, rowid ASC')
-        .all(conversationId);
+        .all(conversationId).map(mapMessage);
 }

package/server/dist/attachment-manager.js

@@ -302,6 +302,144 @@ class AttachmentManager {
         }
         return textBlocks;
     }
+    // ── Agent-scoped attachments ──────────────────────────────────────────────
+    // App-global agent conversations have no project slug/ticket, so their
+    // attachments live under a distinct, conversation-keyed root
+    // `~/.specrails/agent/<conversationId>/attachments/` (never the project
+    // attachments root — that risks slug collisions and doesn't fit Home convos).
+    static AGENT_CONV_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+    agentDir(conversationId) {
+        const key = String(conversationId);
+        if (key === '' || key === '.' || key === '..' || key !== path_1.default.basename(key) ||
+            key.includes('/') || key.includes('\\') || !AttachmentManager.AGENT_CONV_ID_RE.test(key)) {
+            throw new Error(`Invalid agent conversation id: ${JSON.stringify(key)}`);
+        }
+        return path_1.default.join(this.homeDir, '.specrails', 'agent', key, 'attachments');
+    }
+    agentSidecarPath(conversationId, attachmentId) {
+        this.assertValidAttachmentId(attachmentId);
+        return path_1.default.join(this.agentDir(conversationId), `${attachmentId}.meta.json`);
+    }
+    readAgentMeta(conversationId, attachmentId) {
+        const p = this.agentSidecarPath(conversationId, attachmentId);
+        if (!fs_1.default.existsSync(p))
+            return null;
+        try {
+            return JSON.parse(fs_1.default.readFileSync(p, 'utf-8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    async uploadAgent(opts) {
+        const normalizedMimeType = normalizeUploadedMimeType(opts.file.mimetype, opts.file.originalname);
+        if (!exports.SUPPORTED_MIME_TYPES.has(normalizedMimeType)) {
+            const err = new Error(`Unsupported file type: ${opts.file.mimetype}`);
+            err.status = 400;
+            throw err;
+        }
+        const id = (0, ids_1.newId)();
+        const storedName = `${id}-${sanitizeFilename(opts.file.originalname)}`;
+        const attachment = {
+            id,
+            filename: opts.file.originalname,
+            storedName,
+            mimeType: normalizedMimeType,
+            size: opts.file.size,
+            addedAt: new Date().toISOString(),
+        };
+        const dir = this.agentDir(opts.conversationId);
+        fs_1.default.mkdirSync(dir, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(dir, storedName), opts.file.buffer);
+        fs_1.default.writeFileSync(this.agentSidecarPath(opts.conversationId, id), JSON.stringify(attachment, null, 2), 'utf-8');
+        return attachment;
+    }
+    listAgent(conversationId) {
+        let dir;
+        try {
+            dir = this.agentDir(conversationId);
+        }
+        catch {
+            return [];
+        }
+        if (!fs_1.default.existsSync(dir))
+            return [];
+        return fs_1.default
+            .readdirSync(dir)
+            .filter((f) => f.endsWith('.meta.json'))
+            .map((f) => {
+            try {
+                return JSON.parse(fs_1.default.readFileSync(path_1.default.join(dir, f), 'utf-8'));
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((m) => m !== null)
+            .sort((a, b) => (a.addedAt < b.addedAt ? 1 : -1));
+    }
+    getAgentMeta(conversationId, attachmentId) {
+        return this.readAgentMeta(conversationId, attachmentId);
+    }
+    getAgentFilePath(conversationId, attachmentId) {
+        const meta = this.readAgentMeta(conversationId, attachmentId);
+        if (!meta)
+            return null;
+        const abs = path_1.default.join(this.agentDir(conversationId), meta.storedName);
+        return fs_1.default.existsSync(abs) ? abs : null;
+    }
+    async deleteAgent(conversationId, attachmentId) {
+        const meta = this.readAgentMeta(conversationId, attachmentId);
+        if (!meta)
+            return false;
+        const dir = this.agentDir(conversationId);
+        const bin = path_1.default.join(dir, meta.storedName);
+        if (fs_1.default.existsSync(bin))
+            fs_1.default.unlinkSync(bin);
+        const side = this.agentSidecarPath(conversationId, attachmentId);
+        if (fs_1.default.existsSync(side))
+            fs_1.default.unlinkSync(side);
+        return true;
+    }
+    /** Remove the entire per-conversation agent directory (attachments + siblings). */
+    async deleteAllAgent(conversationId) {
+        // Validate the id (throws on traversal) then remove the parent conversation dir.
+        this.agentDir(conversationId);
+        const dir = path_1.default.join(this.homeDir, '.specrails', 'agent', String(conversationId));
+        if (fs_1.default.existsSync(dir))
+            fs_1.default.rmSync(dir, { recursive: true, force: true });
+    }
+    /**
+     * Agent variant of getClaudeArgs, keyed by conversation id. Returns extracted
+     * text blocks (all providers) AND absolute image paths (codex `--image`). The
+     * image `@<abs-path>` stays in textBlocks so claude resolves it and gemini gets
+     * a best-effort shot; `imagePaths` is additive and only codex consumes it.
+     */
+    async getClaudeArgsAgent(conversationId, attachmentIds) {
+        const textBlocks = [];
+        const imagePaths = [];
+        for (const id of attachmentIds) {
+            const meta = this.readAgentMeta(conversationId, id);
+            if (!meta)
+                continue;
+            const abs = path_1.default.join(this.agentDir(conversationId), meta.storedName);
+            if (!fs_1.default.existsSync(abs))
+                continue;
+            if (meta.mimeType.startsWith(IMAGE_MIME_PREFIX)) {
+                imagePaths.push(abs);
+                textBlocks.push(wrapUserAttachment(meta, `@${abs}`));
+                continue;
+            }
+            try {
+                const text = await extractText(abs, meta.mimeType);
+                textBlocks.push(wrapUserAttachment(meta, text));
+            }
+            catch {
+                textBlocks.push(wrapUserAttachment(meta, '[extraction failed]'));
+            }
+        }
+        return { textBlocks, imagePaths };
+    }
 }
 exports.AttachmentManager = AttachmentManager;
 function wrapUserAttachment(meta, content) {

package/server/dist/desktop-db.js

@@ -378,6 +378,18 @@ function applyDesktopMigrations(db) {
         CREATE INDEX IF NOT EXISTS idx_agent_messages_conv ON agent_messages(conversation_id, created_at);
       `);
         },
+        // 18: persist the per-turn attachment id list on user messages so historical
+        // agent turns re-render pills/thumbnails after refresh (design D20). Nullable
+        // JSON array of attachment ids; NULL/absent = text-only turn (all old rows).
+        () => {
+            db.exec(`ALTER TABLE agent_messages ADD COLUMN attachment_ids TEXT;`);
+        },
+        // 19: per-conversation reasoning effort for agent spawns. NULL = the app
+        // default ("medium"); validated against the provider's effort catalog at the
+        // router (claude: low…xhigh, codex: minimal…high, gemini: none).
+        () => {
+            db.exec(`ALTER TABLE agent_conversations ADD COLUMN reasoning_effort TEXT;`);
+        },
     ];
     for (let i = 0; i < migrations.length; i++) {
         const version = i + 1;
@@ -444,6 +456,9 @@ function addProject(db, project) {
 }
 function removeProject(db, id) {
     db.prepare('DELETE FROM projects WHERE id = ?').run(id);
+    // No FK on agent_conversations.pinned_project_id — unpin so orphaned agent
+    // conversations fold into Home instead of dangling on a dead project id.
+    db.prepare('UPDATE agent_conversations SET pinned_project_id = NULL WHERE pinned_project_id = ?').run(id);
 }
 function touchProject(db, id) {
     db.prepare("UPDATE projects SET last_seen_at = datetime('now') WHERE id = ?").run(id);

package/server/dist/loop-factory.js

@@ -31,12 +31,22 @@ exports.FACTORY_LOOPS = [
     },
     {
         id: 'factory:ultracode',
-        name: 'Ultracode',
-        description: 'Autonomous per-ticket implementation (no pipeline), then verify + refine until green. Claude only.',
+        // Renamed from "Ultracode": the mode hands the spec straight to the model
+        // with full freedom — no pipeline, it works like a regular coding agent.
+        // The id/mode strings stay 'ultracode' (wire + rail back-compat).
+        name: 'Freestyle',
+        description: 'Hands the spec straight to the model with full freedom — no pipeline, it works like a regular coding agent, then verify + refine until green. Claude only.',
         mode: 'ultracode',
         claudeOnly: true,
         graph: (0, loop_templates_1.fixLoopGraph)(['{{cmd:ultracode}}'], GREEN_GOAL, FACTORY_MAX_ITERATIONS, FACTORY_LOOP_TIMEOUT_MIN, FACTORY_AI_STEP_TIMEOUT_MIN),
     },
+    {
+        id: 'factory:openspec',
+        name: 'OpenSpec Lifecycle',
+        description: 'Ticket-to-archive OpenSpec lifecycle: generate artifacts (opsx:ff) → implement (opsx:apply) → verify (opsx:verify); on FAIL loop back and amend the same change, on PASS archive it unattended.',
+        mode: 'loop',
+        graph: (0, loop_templates_1.opsxLifecycleGraph)(),
+    },
 ];
 const FACTORY_BY_ID = new Map(exports.FACTORY_LOOPS.map((f) => [f.id, f]));
 function getFactoryLoop(id) {