specrails-desktop 2.29.4 → 2.30.0

package/server/dist/contract-refine-runner.js

@@ -5,8 +5,9 @@
  * Standalone runner that spawns a single Claude turn to produce the
  * Contract Layer for a just-committed Explore Spec ticket. Lives outside the
  * ChatManager lifecycle for now (design.md D3 — "thin sibling helper" option):
- * the refine is fire-and-forget, single-attempt, 60 s budget, no idle-kill /
- * crash-respawn semantics.
+ * the refine is fire-and-forget with a 60 s budget per invocation and no
+ * idle-kill / crash-respawn semantics. Only the exact relocated missing-session
+ * diagnostic permits one fresh compatibility retry.
  *
  * See openspec/changes/explore-spec-contract-refine.
  */
@@ -35,6 +36,7 @@ const workspace_resolution_1 = require("./workspace-resolution");
 const process_admission_1 = require("./process-admission");
 const transient_children_1 = require("./transient-children");
 const REFINE_TIMEOUT_MS = 60_000;
+const CLAUDE_MISSING_SESSION_DIAGNOSTIC = 'No conversation found with session ID';
 /**
  * Relocate-artifacts: resolve the ticket store path honouring the gate.
  * Relocated ⇒ the registry entry's tickets path (workspace); legacy ⇒
@@ -83,6 +85,46 @@ function buildRefineArgs(model, systemPrompt, sessionId) {
         '-p', explore_contract_refine_1.CONTRACT_MARKER_USER_MESSAGE,
     ];
 }
+/** Build the pure-output, no-resume invocation used by Quick Refine and by the
+ * one-time compatibility recovery for cwd-scoped Explore sessions. */
+function buildFreshRefineArgs(model, title, description) {
+    const systemPrompt = [
+        (0, explore_contract_refine_1.buildContractRefineSystemPrompt)(),
+        '',
+        '## Spec under refinement',
+        '',
+        '### Title',
+        title,
+        '',
+        '### Description',
+        description,
+    ].join('\n');
+    return [
+        '--model', model,
+        '--tools', '__none__',
+        '--output-format', 'stream-json',
+        '--verbose',
+        '--system-prompt', systemPrompt,
+        '--max-turns', '1',
+        '-p', explore_contract_refine_1.CONTRACT_MARKER_USER_MESSAGE,
+    ];
+}
+/** Match only Claude's missing cwd-scoped session diagnostic. The CLI has
+ * emitted it both as stderr and inside structured result payloads, so inspect
+ * all captured provider output while keeping unrelated failures ineligible. */
+function containsMissingClaudeSessionDiagnostic(value) {
+    if (typeof value === 'string') {
+        return value.includes(CLAUDE_MISSING_SESSION_DIAGNOSTIC);
+    }
+    if (value == null)
+        return false;
+    try {
+        return JSON.stringify(value).includes(CLAUDE_MISSING_SESSION_DIAGNOSTIC);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Build the spawn argv + cwd for the refine turn. Exported for tests.
  */
@@ -103,19 +145,26 @@ function prepareContractRefineSpawn(deps, conversation) {
     // different per-cwd session store and fails with "No conversation found with
     // session ID …" (the Desktop-tier bug). chat-manager `_resolveSpawnCwd` for an
     // Explore turn uses:
-    //   - mcp ON  → `project.path` (NOT the relocated workspace),
+    //   - mcp ON  → the relocate-artifacts gate (workspace when relocated, else
+    //     `project.path`); `SPECRAILS_EXPLORE_LEGACY_CWD=1` forces `project.path`,
     //   - mcp OFF → the app-managed explore-cwd.
     // We mirror that EXACTLY here. The refine uses no tools (`--tools __none__`)
     // and its prompt rides on `--system-prompt`, so it needs
-    // neither the workspace's `.mcp.json` nor its `.claude/commands`. Env still
-    // carries SPECRAILS_REPO_DIR when relocated (harmless; no tools consume it).
+    // neither the workspace's `.mcp.json` nor its `.claude/commands`. The env is
+    // mirrored too so the legacy-cwd escape hatch remains byte-identical.
     const exec = (0, workspace_resolution_1.resolveProjectExecution)({ slug: deps.projectSlug, path: deps.projectPath });
-    let env = exec.relocated ? { ...process.env, ...exec.env } : undefined;
+    let env;
     let cwd;
     if (mcpEnabled) {
-        // Match the Explore mcp-on spawn cwd (`this._cwd` = project.path), even when
-        // relocated (where exec.cwd would be the workspace ≠ project.path).
-        cwd = deps.projectPath;
+        // Match the Explore mcp-on spawn cwd through the same gate + escape hatch.
+        if (process.env.SPECRAILS_EXPLORE_LEGACY_CWD === '1') {
+            cwd = deps.projectPath;
+        }
+        else {
+            cwd = exec.cwd;
+            if (exec.relocated)
+                env = { ...process.env, ...exec.env };
+        }
     }
     else {
         try {
@@ -126,7 +175,9 @@ function prepareContractRefineSpawn(deps, conversation) {
             });
         }
         catch {
-            cwd = exec.cwd;
+            // Match ChatManager's fail-closed fallback for an unavailable
+            // app-managed Explore cwd.
+            cwd = deps.projectPath;
         }
     }
     const args = buildRefineArgs(conversation.model ?? 'sonnet', systemPrompt, conversation.session_id ?? '');
@@ -280,7 +331,8 @@ function applyContractLayerToTicket(filePath, ticketId, layer, nowIso) {
     return updated;
 }
 /**
- * Fire a single Contract Refine attempt for the given conversation + ticket.
+ * Run Contract Refine for the given conversation + ticket (normally one
+ * invocation; at most two for the narrow missing-session compatibility path).
  *
  * Returns a Promise that resolves with the outcome. Side effects:
  *  - On success: patches the ticket's description, broadcasts `ticket_updated`
@@ -353,59 +405,97 @@ async function runContractRefine(deps, conversationId, ticketId) {
     const startedAt = now().toISOString();
     // Spawn/stream/timeout/settlement is owned by the shared spawn-lifecycle; the
     // contract-refine-specific raw parse (fullText from assistant text blocks,
-    // the raw result event) and ALL finalize/record/broadcast logic stay here,
-    // byte-for-byte, so behaviour is unchanged (it still records via the legacy
-    // recordSafely path).
-    let fullText = '';
-    let resultEvent = null;
-    const run = await (0, spawn_lifecycle_1.runAiCliInvocation)({
-        adapter: (0, registry_1.getAdapter)('claude'),
-        binary: 'claude',
-        argv: args,
-        cwd,
-        env: refineEnv ?? process.env,
-        spawn,
-        timeoutMs,
-        onSpawn: (child) => (0, transient_children_1.trackTransientChild)(deps.projectId, child),
-        onStdoutLine: (line) => {
-            let parsed = null;
-            try {
-                parsed = JSON.parse(line);
-            }
-            catch {
-                return;
-            }
-            if (!parsed)
-                return;
-            const type = parsed.type;
-            if (type === 'result') {
-                resultEvent = parsed;
-            }
-            else if (type === 'assistant') {
-                const message = parsed.message;
-                for (const b of (message?.content ?? [])) {
-                    if (b.type === 'text' && typeof b.text === 'string')
-                        fullText += b.text;
+    // the raw result event) and all finalize/record/broadcast logic stay here.
+    // Keeping the invocation result in one shape also lets the narrowly-gated
+    // missing-session recovery re-enter the exact same finalization path.
+    const invoke = async (invocationArgs) => {
+        let fullText = '';
+        let resultEvent = null;
+        const run = await (0, spawn_lifecycle_1.runAiCliInvocation)({
+            adapter: (0, registry_1.getAdapter)('claude'),
+            binary: 'claude',
+            argv: invocationArgs,
+            cwd,
+            env: refineEnv ?? process.env,
+            spawn,
+            timeoutMs,
+            onSpawn: (child) => (0, transient_children_1.trackTransientChild)(deps.projectId, child),
+            onStdoutLine: (line) => {
+                let parsed = null;
+                try {
+                    parsed = JSON.parse(line);
                 }
-            }
-        },
-    });
+                catch {
+                    return;
+                }
+                if (!parsed)
+                    return;
+                const type = parsed.type;
+                if (type === 'result') {
+                    resultEvent = parsed;
+                }
+                else if (type === 'assistant') {
+                    const message = parsed.message;
+                    for (const b of (message?.content ?? [])) {
+                        if (b.type === 'text' && typeof b.text === 'string')
+                            fullText += b.text;
+                    }
+                }
+            },
+        });
+        return {
+            fullText,
+            resultEvent,
+            code: run.code,
+            timedOut: run.timedOut,
+            spawnFailed: run.spawnFailed,
+            stderrTail: run.stderrTail,
+        };
+    };
+    let result = await invoke(args);
     if (!admission.isCurrent()) {
         return { ok: false, reason: 'aborted', ticketId, conversationId };
     }
-    if (run.spawnFailed) {
-        recordSafely(deps, conversationId, ticketId, conversation.model, startedAt, now().toISOString(), 'failed', null);
+    // A pre-relocation Explore session was created under the repo cwd and cannot
+    // be resumed after the corrected mcp=true route moves to the workspace.
+    // Recover only that exact provider failure, once, and never by returning to
+    // the repo. The fresh turn is explicitly seeded because it has no resumed
+    // conversation context.
+    const resumedFromRelocatedWorkspace = refineEnv?.SPECRAILS_WORKSPACE_DIR === cwd && cwd !== deps.projectPath;
+    const resumeFailed = !result.spawnFailed &&
+        !result.timedOut &&
+        (result.code !== 0 || !result.resultEvent || isResultErrorEvent(result.resultEvent));
+    const missingSessionDiagnostic = containsMissingClaudeSessionDiagnostic(result.fullText) ||
+        containsMissingClaudeSessionDiagnostic(result.resultEvent) ||
+        containsMissingClaudeSessionDiagnostic(result.stderrTail);
+    if (resumedFromRelocatedWorkspace && resumeFailed && missingSessionDiagnostic) {
+        let ticket = null;
+        try {
+            ticket = (0, ticket_store_1.readStore)(resolveContractTicketsPath(deps.projectPath)).tickets[String(ticketId)] ?? null;
+        }
+        catch (err) {
+            console.error('[contract-refine-runner] unable to read ticket for missing-session recovery:', err);
+        }
+        if (ticket) {
+            console.warn(`[contract-refine-runner] resume session unavailable; retrying once fresh from workspace ticket=${ticketId}`);
+            result = await invoke(buildFreshRefineArgs(conversation.model ?? 'sonnet', ticket.title, ticket.description));
+            if (!admission.isCurrent()) {
+                return { ok: false, reason: 'aborted', ticketId, conversationId };
+            }
+        }
+    }
+    const finishedAt = now().toISOString();
+    if (result.spawnFailed) {
+        recordSafely(deps, conversationId, ticketId, conversation.model, startedAt, finishedAt, 'failed', null);
         deps.broadcast({
             type: 'explore.contract_refine_failed',
             projectId: deps.projectId,
             ticketId,
             reason: 'crashed',
-            timestamp: now().toISOString(),
+            timestamp: finishedAt,
         });
         return { ok: false, reason: 'crashed', ticketId, conversationId };
     }
-    const result = { fullText, resultEvent, code: run.code, timedOut: run.timedOut };
-    const finishedAt = now().toISOString();
     console.log(`[contract-refine-runner] spawn done code=${result.code} timedOut=${result.timedOut} hasResult=${!!result.resultEvent} textBytes=${result.fullText.length}`);
     if (result.timedOut) {
         recordSafely(deps, conversationId, ticketId, conversation.model, startedAt, finishedAt, 'aborted', result.resultEvent);
@@ -515,26 +605,7 @@ async function runContractRefineForQuick(deps, ticketId, generatedTitle, generat
         return { ok: false, reason: 'disabled', ticketId, conversationId: '' };
     }
     const admission = (0, process_admission_1.captureProcessAdmission)(deps.projectId);
-    const systemPrompt = [
-        (0, explore_contract_refine_1.buildContractRefineSystemPrompt)(),
-        '',
-        '## Spec under refinement',
-        '',
-        `### Title`,
-        generatedTitle,
-        '',
-        `### Description`,
-        generatedDescription,
-    ].join('\n');
-    const args = [
-        '--model', model ?? 'sonnet',
-        '--tools', '__none__',
-        '--output-format', 'stream-json',
-        '--verbose',
-        '--system-prompt', systemPrompt,
-        '--max-turns', '1',
-        '-p', explore_contract_refine_1.CONTRACT_MARKER_USER_MESSAGE,
-    ];
+    const args = buildFreshRefineArgs(model ?? 'sonnet', generatedTitle, generatedDescription);
     const startedAt = now().toISOString();
     deps.broadcast({
         type: 'explore.contract_refine_started',

package/server/dist/desktop-db.js

@@ -436,6 +436,33 @@ function applyDesktopMigrations(db) {
         () => {
             db.exec(`ALTER TABLE agent_messages ADD COLUMN context_refs TEXT;`);
         },
+        // 22: Project Builder day-0 conversations (add-project-builder D1). The
+        // Builder runs BEFORE any project exists, so its conversations live in the
+        // app registry DB — same shape as agent_conversations but a separate pair
+        // of tables: the Builder has no tier ladder and no pinned project, and its
+        // lifecycle (discarded after commit or abandoned) should never mix with
+        // agent-chat history.
+        () => {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS blueprint_conversations (
+          id         TEXT PRIMARY KEY,
+          title      TEXT,
+          provider   TEXT NOT NULL DEFAULT 'claude',
+          model      TEXT,
+          session_id TEXT,
+          created_at TEXT NOT NULL DEFAULT (datetime('now')),
+          updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+        CREATE TABLE IF NOT EXISTS blueprint_messages (
+          id              TEXT PRIMARY KEY,
+          conversation_id TEXT NOT NULL REFERENCES blueprint_conversations(id) ON DELETE CASCADE,
+          role            TEXT NOT NULL,
+          content         TEXT NOT NULL,
+          created_at      TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+        CREATE INDEX IF NOT EXISTS idx_blueprint_messages_conv ON blueprint_messages(conversation_id, created_at);
+      `);
+        },
     ];
     for (let i = 0; i < migrations.length; i++) {
         const version = i + 1;

package/server/dist/index.js

@@ -26,6 +26,9 @@ const mobile_1 = require("./mobile");
 const mcp_1 = require("./mcp");
 const agent_chat_manager_1 = require("./agent-chat-manager");
 const agent_chat_router_1 = require("./agent-chat-router");
+const blueprint_chat_manager_1 = require("./blueprint-chat-manager");
+const blueprint_router_1 = require("./blueprint-router");
+const blueprint_commit_1 = require("./blueprint-commit");
 const agent_chat_registry_1 = require("./agent-chat-registry");
 const browser_playwright_1 = require("./browser-playwright");
 const telemetry_receiver_1 = require("./telemetry-receiver");
@@ -254,6 +257,7 @@ let _registry = null;
 let _mobileGateway = null;
 let _mcpManager = null;
 let _agentChatManager = null;
+let _blueprintChatManager = null;
 let _headroomManager = null;
 server.on('upgrade', (request, socket, head) => {
     const urlStr = request.url ?? '/';
@@ -579,6 +583,16 @@ function applyPtyWsRateLimiting(ws) {
     // disabled — the rails callers are null-safe and simply skip the card.
     (0, agent_chat_registry_1.setAgentChatManager)((0, agent_chat_router_1.isAgentChatEnabled)() ? agentChatManager : null);
     app.use('/api/agent', (0, agent_chat_router_1.createAgentChatRouter)({ manager: agentChatManager, desktopDb: registry.desktopDb }));
+    // Project Builder day-0 chat + orchestrated commit (add-project-builder).
+    // App-level like agent chat — a Builder conversation runs before any project
+    // exists. Route-gated by SPECRAILS_PROJECT_BUILDER inside the router.
+    const blueprintChatManager = new blueprint_chat_manager_1.BlueprintChatManager(broadcast, registry.desktopDb);
+    _blueprintChatManager = blueprintChatManager;
+    app.use('/api/blueprint', (0, blueprint_router_1.createBlueprintRouter)({
+        manager: blueprintChatManager,
+        desktopDb: registry.desktopDb,
+        runCommit: (0, blueprint_commit_1.createBlueprintCommitRunner)({ registry, broadcast }),
+    }));
     // App-level routes. CRITICAL mount order: the desktop router is mounted at
     // '/api' BEFORE the project router below so its exact routes (e.g.
     // GET /api/projects, DELETE /api/projects/:id) are handled here, while
@@ -689,6 +703,7 @@ async function shutdown() {
         Promise.resolve().then(() => _mobileGateway?.stop()),
         Promise.resolve().then(() => _mcpManager?.stop()),
         Promise.resolve().then(() => _agentChatManager?.shutdown()),
+        Promise.resolve().then(() => _blueprintChatManager?.shutdown()),
     ]);
     try {
         await _headroomManager?.shutdown();

package/server/dist/offline-assemble.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnBundledCoreInit = spawnBundledCoreInit;
+exports.hasOfflineCore = hasOfflineCore;
+exports.spawnNpxCoreInit = spawnNpxCoreInit;
+exports.canAssembleProject = canAssembleProject;
+exports.assembleProjectOffline = assembleProjectOffline;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const win_spawn_1 = require("./util/win-spawn");
+const bundled_core_1 = require("./bundled-core");
+const bundled_openspec_1 = require("./bundled-openspec");
+const path_resolver_1 = require("./path-resolver");
+const framework_manager_1 = require("./framework-manager");
+const artifact_registry_1 = require("./artifact-registry");
+const install_config_path_1 = require("./install-config-path");
+const workspace_manager_1 = require("./workspace-manager");
+const core_package_1 = require("./core-package");
+// ─── Offline workspace assemble (add-project-builder D4) ─────────────────────
+//
+// The single shared "assemble a project workspace from the BUNDLED framework"
+// primitive, extracted from SetupManager's bundled-core fast path so the
+// Project Builder's orchestrated commit can assemble WITHOUT the wizard's
+// streaming/phase shell. Extract-don't-fork: SetupManager keeps its shell and
+// its npx fallback. The Builder PREFERS the bundle (offline day 0) but falls
+// back to `npx specrails-core` when no bundle is present — so `npm run dev` and
+// any runtimes-less build still work. Only a DESKTOP build with a MISSING/
+// corrupted bundle hard-fails (see `canAssembleProject`).
+/**
+ * Spawn the BUNDLED specrails-core `init` (offline framework + assemble).
+ * Runs `node <bundled-cli> init <args>` with `SPECRAILS_CORE_SCRIPT_DIR`
+ * pointed at the bundle so core's template/command sources resolve from the
+ * app bundle, NOT a global install or npm registry. Forces RELOCATION (the
+ * desktop keeps the user's repo pristine). When the app also ships
+ * @fission-ai/openspec, `SPECRAILS_OPENSPEC_BIN`/`_NODE` make the last network
+ * step offline too.
+ *
+ * Returns null when no bundled core is present. Callers may then use the npx
+ * fallback outside the packaged desktop app.
+ */
+function spawnBundledCoreInit(args, cwd) {
+    const cli = (0, bundled_core_1.getBundledCoreCli)();
+    const coreRoot = (0, bundled_core_1.getBundledCoreRoot)();
+    if (!cli || !coreRoot)
+        return null;
+    const fullArgs = [cli, 'init', ...args];
+    const env = { ...(0, win_spawn_1.windowsSpawnEnv)(), SPECRAILS_CORE_SCRIPT_DIR: coreRoot, SPECRAILS_RELOCATE: '1' };
+    const openspecCli = (0, bundled_openspec_1.getBundledOpenspecCli)();
+    if (openspecCli) {
+        env.SPECRAILS_OPENSPEC_BIN = openspecCli;
+        // MUST be a REAL node executable — NOT process.execPath (the packaged
+        // `specrails-server` pkg binary cannot run openspec's ESM CLI).
+        env.SPECRAILS_OPENSPEC_NODE = (0, path_resolver_1.resolveBundledNodeExe)() ?? 'node';
+    }
+    // Run the core CLI with the REAL bundled node — process.execPath only in
+    // dev/tests where it IS node.
+    const nodeBin = (0, path_resolver_1.resolveBundledNodeExe)() ?? process.execPath;
+    console.log(`[offline-assemble] spawning BUNDLED core: ${nodeBin} ${fullArgs.join(' ')} (cwd=${cwd})` +
+        (openspecCli ? ' [bundled openspec: offline]' : ' [openspec: npx fallback]'));
+    return (0, win_spawn_1.spawnCli)(nodeBin, fullArgs, {
+        cwd,
+        env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+}
+/** True when the bundled specrails-core is present (offline assemble possible). */
+function hasOfflineCore() {
+    return (0, bundled_core_1.getBundledCoreCli)() !== null;
+}
+const WHICH_CMD = process.platform === 'win32' ? 'where' : 'which';
+/** Resolve a core binary override to an absolute path (mirrors SetupManager). */
+function resolveCoreBinary(bin) {
+    if ((0, path_1.isAbsolute)(bin))
+        return bin;
+    if (bin.includes('/') || bin.includes('\\'))
+        return (0, path_1.resolve)(bin);
+    const result = (0, child_process_1.spawnSync)(WHICH_CMD, [bin], {
+        env: (0, win_spawn_1.windowsSpawnEnv)(), shell: process.platform === 'win32', encoding: 'utf-8', timeout: 5_000,
+    });
+    if (result.error || (result.status ?? 1) !== 0)
+        return bin;
+    const first = `${result.stdout ?? ''}`.trim().split(/\r?\n/)[0]?.trim();
+    return first && first.length > 0 ? first : bin;
+}
+/**
+ * Spawn `npx specrails-core init` (or the `SPECRAILS_CORE_BIN` override) —
+ * the network fallback SetupManager uses when no bundle is present. Forces
+ * RELOCATION so the user's repo stays pristine.
+ */
+function spawnNpxCoreInit(args, cwd) {
+    const override = process.env.SPECRAILS_CORE_BIN;
+    const bin = override ? resolveCoreBinary(override) : 'npx';
+    const fullArgs = override ? ['init', ...args] : ['--yes', '--prefer-online', core_package_1.CORE_PACKAGE_SPEC, 'init', ...args];
+    console.log(`[offline-assemble] spawning npx core: ${bin} ${fullArgs.join(' ')} (cwd=${cwd})`);
+    return (0, win_spawn_1.spawnCli)(bin, fullArgs, {
+        cwd,
+        env: { ...(0, win_spawn_1.windowsSpawnEnv)(), SPECRAILS_RELOCATE: '1' },
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+}
+/**
+ * Whether the Project Builder can assemble a workspace at all. True when the
+ * bundle is present (offline path) OR we're NOT in a packaged desktop build
+ * (dev / runtimes-less server → npx fallback). Only a DESKTOP build with a
+ * missing/corrupted bundle returns false → the "reinstall the app" error.
+ */
+function canAssembleProject() {
+    return (0, bundled_core_1.getBundledCoreCli)() !== null || process.env.SPECRAILS_IS_DESKTOP !== '1';
+}
+function buildQuickInstallConfigYaml(provider, defaultModel) {
+    // Matches serializeInstallConfigYaml's shape (specrails-core tui-installer
+    // format) for a quick/template install with the default agent set.
+    return [
+        '# specrails install config — generated by Specrails Project Builder',
+        'version: 1',
+        `provider: ${provider}`,
+        'tier: quick',
+        'agents:',
+        '  selected: []',
+        '  excluded: []',
+        'models:',
+        '  preset: balanced',
+        `  defaults: { model: ${defaultModel} }`,
+        '  overrides: {}',
+        'agent_teams: false',
+        '',
+    ].join('\n');
+}
+/**
+ * Assemble a project workspace from the bundled framework when available, or
+ * from the npx fallback in development/runtimes-less builds: registry mirror
+ * → framework materialize (idempotent) → one `init` per provider. Throws on
+ * any failure — the caller surfaces it as a failed step; nothing here registers
+ * the project.
+ */
+async function assembleProjectOffline(opts) {
+    const { projectPath, slug, desktopProjectId, providers } = opts;
+    if (!canAssembleProject() && !opts.io?.spawnInit) {
+        throw new Error('specrails-core is not available — reinstall the Specrails app');
+    }
+    if (providers.length === 0)
+        throw new Error('at least one provider is required');
+    // Bundle present ⇒ offline bundled init; otherwise (dev / no bundle) ⇒ npx.
+    const useBundled = hasOfflineCore();
+    // Registry entry BEFORE core's init so core resolves its workspace from the
+    // registry and relocates under the desktop's slug (same reasoning as
+    // SetupManager.startInstall's pre-install mirror).
+    (0, artifact_registry_1.mirrorProjectEntry)({
+        repoPath: projectPath,
+        slug,
+        providers,
+        primaryProvider: providers[0],
+        desktopProjectId,
+    });
+    // Materialize the bundled framework for the selected providers (idempotent —
+    // core's ensureFramework skips when already present). Best-effort: the
+    // bundled init re-runs ensureFramework, so it self-heals.
+    const materialize = opts.io?.materialize ?? ((provs) => {
+        try {
+            const fm = new framework_manager_1.FrameworkManager({ broadcast: () => { } });
+            const mat = fm.materialize((0, bundled_core_1.getBundledCoreVersion)() ?? undefined, provs);
+            if (mat.ran && mat.errors.length > 0) {
+                console.warn(`[offline-assemble] framework materialize had errors: ${mat.errors.map((e) => `${e.provider}: ${e.message}`).join('; ')}`);
+            }
+        }
+        catch (err) {
+            console.warn(`[offline-assemble] framework materialize threw (non-fatal): ${err.message}`);
+        }
+    });
+    materialize(providers);
+    const spawnInit = opts.io?.spawnInit ?? (useBundled ? spawnBundledCoreInit : spawnNpxCoreInit);
+    const coreLabel = useBundled ? 'bundled core' : 'npx core';
+    for (const provider of providers) {
+        const configPath = (0, install_config_path_1.installConfigPathForProvider)({ slug, path: projectPath }, provider);
+        (0, fs_1.mkdirSync)((0, path_1.dirname)(configPath), { recursive: true });
+        (0, fs_1.writeFileSync)(configPath, buildQuickInstallConfigYaml(provider, opts.defaultModel ?? 'sonnet'), 'utf-8');
+        const child = spawnInit(['--yes', '--from-config', configPath], projectPath);
+        if (!child) {
+            throw new Error('specrails-core is not available — reinstall the Specrails app');
+        }
+        const stderrChunks = [];
+        child.stderr?.on('data', (chunk) => {
+            stderrChunks.push(chunk.toString());
+        });
+        child.stdout?.resume(); // drain so the child never blocks on a full pipe
+        const code = await new Promise((resolve, reject) => {
+            child.once('error', (err) => reject(new Error(`failed to launch ${coreLabel}: ${err.message}`)));
+            child.once('close', (exitCode) => resolve(exitCode));
+        });
+        if (code !== 0) {
+            const tail = stderrChunks.join('').split('\n').filter(Boolean).slice(-5).join(' ').slice(0, 500);
+            throw new Error(`${coreLabel} init failed for ${provider} (exit ${code})${tail ? `: ${tail}` : ''}`);
+        }
+    }
+    // The activation gate (workspace-resolution) requires a populated workspace;
+    // verify assemble actually produced one so a silent core no-op cannot leave
+    // a half-created project that would spawn from a repo cwd.
+    const workspace = (0, workspace_manager_1.workspacePathFor)(slug);
+    if (!(0, fs_1.existsSync)(workspace)) {
+        throw new Error(`assemble completed but workspace was not created at ${workspace}`);
+    }
+}

package/server/dist/pricing.js

@@ -29,6 +29,11 @@ const registry_1 = require("./providers/registry");
 /** Key shape: `<providerId>:<model>` (case-sensitive). */
 exports.PRICING = {
     // Codex (OpenAI). Reference: https://openai.com/pricing
+    // GPT-5.6 family (GA 2026-07-09): cache reads keep the 90% discount; 5.6+
+    // ALSO bills cache WRITES at 1.25x the uncached input rate (new semantics).
+    'codex:gpt-5.6-sol': { inputPer1M: 5.00, outputPer1M: 30.00, cacheReadPer1M: 0.50, cacheWritePer1M: 6.25, lastReviewedAt: '2026-07-17' },
+    'codex:gpt-5.6-terra': { inputPer1M: 2.50, outputPer1M: 15.00, cacheReadPer1M: 0.25, cacheWritePer1M: 3.125, lastReviewedAt: '2026-07-17' },
+    'codex:gpt-5.6-luna': { inputPer1M: 1.00, outputPer1M: 6.00, cacheReadPer1M: 0.10, cacheWritePer1M: 1.25, lastReviewedAt: '2026-07-17' },
     'codex:gpt-5.5': { inputPer1M: 1.25, outputPer1M: 10.00, cacheReadPer1M: 0.125, lastReviewedAt: '2026-05-17' },
     'codex:gpt-5.4': { inputPer1M: 2.50, outputPer1M: 10.00, cacheReadPer1M: 0.25, lastReviewedAt: '2026-05-17' },
     'codex:gpt-5.4-mini': { inputPer1M: 0.25, outputPer1M: 2.00, cacheReadPer1M: 0.025, lastReviewedAt: '2026-05-17' },

package/server/dist/project-router-chat.js

@@ -45,13 +45,25 @@ function registerChatRoutes(deps) {
             return;
         }
         const rawKind = req.body?.kind;
-        const kind = rawKind === 'explore' ? 'explore' : 'sidebar';
+        const kind = rawKind === 'explore' ? 'explore' : rawKind === 'milestone' ? 'milestone' : 'sidebar';
         const id = (0, ids_1.newId)();
         const rawScope = req.body?.contextScope;
         if (rawScope !== undefined && kind !== 'explore') {
             res.status(400).json({ error: 'contextScope is only allowed for kind=explore' });
             return;
         }
+        // Milestone generation (add-project-builder D7): the target milestone id
+        // rides context_scope as a minimal `{ milestone }` object so ChatManager
+        // can seed its milestone system prompt from the workspace blueprint.
+        let milestoneScope;
+        if (kind === 'milestone') {
+            const rawMilestone = req.body?.milestone;
+            if (typeof rawMilestone !== 'string' || !/^m[0-9]{1,3}$/i.test(rawMilestone)) {
+                res.status(400).json({ error: 'milestone (e.g. "m2") is required for kind=milestone' });
+                return;
+            }
+            milestoneScope = { milestone: rawMilestone.toLowerCase() };
+        }
         let scope;
         if (kind === 'explore') {
             const fallback = (0, context_scope_1.getLastContextScope)(db, 'explore');
@@ -69,7 +81,7 @@ function registerChatRoutes(deps) {
         // Only persist provider when the project is multi-provider; single-provider
         // projects leave it NULL so behaviour is byte-identical to before.
         const persistProvider = (0, provider_selection_1.isMultiProvider)(project) ? provider : null;
-        (0, db_1.createConversation)(db, { id, model, kind, contextScope: scope, provider: persistProvider });
+        (0, db_1.createConversation)(db, { id, model, kind, contextScope: scope ?? milestoneScope, provider: persistProvider });
         const conversation = (0, db_1.getConversation)(db, id);
         res.status(201).json({ conversation });
     });