specrails-desktop 2.29.4 → 2.30.0

package/server/dist/blueprint-chat-manager.js

@@ -0,0 +1,335 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlueprintChatManager = void 0;
+const crypto_1 = require("crypto");
+const tree_kill_1 = __importDefault(require("tree-kill"));
+const providers_1 = require("./providers");
+const spawn_lifecycle_1 = require("./spawn-lifecycle");
+const cli_prompt_1 = require("./util/cli-prompt");
+const result_event_1 = require("./result-event");
+const desktop_db_1 = require("./desktop-db");
+const builder_cwd_manager_1 = require("./builder-cwd-manager");
+const blueprint_operator_prompt_1 = require("./blueprint-operator-prompt");
+const blueprint_draft_parser_1 = require("./blueprint-draft-parser");
+const explore_draft_title_1 = require("./explore-draft-title");
+const blueprint_store_1 = require("./blueprint-store");
+class BlueprintChatManager {
+    _broadcast;
+    _db;
+    _active = new Map();
+    _abortedTurns = new Set();
+    _terminationTimers = new Map();
+    _disposed = false;
+    _resolveDisposed;
+    _disposedSignal = new Promise((resolve) => {
+        this._resolveDisposed = resolve;
+    });
+    constructor(broadcast, db) {
+        this._broadcast = broadcast;
+        this._db = db;
+    }
+    async _awaitWhileLive(work) {
+        if (this._disposed)
+            return { disposed: true };
+        return Promise.race([
+            work.then((value) => ({ disposed: false, value })),
+            this._disposedSignal.then(() => ({ disposed: true })),
+        ]);
+    }
+    /** Own a dedicated POSIX process group so descendants remain killable after
+     * the root CLI exits (mirrors AgentChatManager). */
+    _spawnOwned(binary, args, options = {}) {
+        if (process.platform === 'win32')
+            return (0, cli_prompt_1.spawnAiCli)(binary, args, options);
+        return (0, cli_prompt_1.spawnAiCli)(binary, args, { ...options, detached: true });
+    }
+    _terminate(child) {
+        if (this._terminationTimers.has(child))
+            return;
+        try {
+            if (!child.pid) {
+                child.kill('SIGTERM');
+                return;
+            }
+            const pid = child.pid;
+            (0, tree_kill_1.default)(pid, 'SIGTERM');
+            const timer = setTimeout(() => {
+                this._terminationTimers.delete(child);
+                if (process.platform !== 'win32') {
+                    try {
+                        process.kill(-pid, 'SIGKILL');
+                    }
+                    catch { /* group already gone */ }
+                }
+                else {
+                    try {
+                        (0, tree_kill_1.default)(pid, 'SIGKILL', () => { });
+                    }
+                    catch { /* gone */ }
+                }
+            }, 2000);
+            timer.unref?.();
+            this._terminationTimers.set(child, timer);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    isStreaming(conversationId) {
+        return !this._disposed && this._active.has(conversationId);
+    }
+    /** Stop the in-flight turn (partial text is kept; never surfaced as error). */
+    abort(conversationId) {
+        const child = this._active.get(conversationId);
+        if (!child)
+            return;
+        this._abortedTurns.add(conversationId);
+        this._active.delete(conversationId);
+        this._terminate(child);
+    }
+    _emitError(conversationId, error) {
+        if (this._disposed)
+            return;
+        this._broadcast({ type: 'blueprint.error', conversationId, error, timestamp: new Date().toISOString() });
+    }
+    /**
+     * Runs one Builder turn: persists the user message, spawns the AI CLI from
+     * the builder cwd, streams deltas as `blueprint.stream`, then persists the
+     * STRIPPED assistant reply (blueprint-draft fences removed) and broadcasts
+     * `blueprint.done` with the last valid blueprint snapshot.
+     */
+    async sendMessage(conversationId, userText, options = {}) {
+        if (this._disposed)
+            return;
+        const conversation = (0, blueprint_store_1.getBlueprintConversation)(this._db, conversationId);
+        if (!conversation) {
+            this._emitError(conversationId, 'Unknown conversation');
+            return;
+        }
+        if (this._active.has(conversationId)) {
+            this._emitError(conversationId, 'A turn is already streaming for this conversation.');
+            return;
+        }
+        try {
+            await this._runTurn(conversation, userText, options);
+        }
+        catch (err) {
+            if (this._disposed)
+                return;
+            console.error(`[blueprint-chat] turn failed (${conversationId}):`, err);
+            this._emitError(conversationId, err instanceof Error ? err.message : 'The Builder turn failed.');
+        }
+        finally {
+            this._abortedTurns.delete(conversationId);
+        }
+    }
+    async _runTurn(conversation, userText, options) {
+        const conversationId = conversation.id;
+        const adapter = (0, providers_1.getAdapter)(conversation.provider);
+        const catalog = new Set(adapter.modelCatalog().map((m) => m.value));
+        const requested = options.model || conversation.model;
+        const model = requested && catalog.has(requested) ? requested : adapter.defaultModel();
+        // Reasoning effort: only for providers with the knob, only when the value
+        // is in their catalog (else undefined = provider default).
+        const efforts = adapter.capabilities.reasoningEfforts ?? [];
+        const requestedEffort = options.reasoningEffort;
+        const reasoningEffort = requestedEffort
+            && efforts.includes(requestedEffort)
+            ? requestedEffort
+            : undefined;
+        const cwd = (0, builder_cwd_manager_1.ensureBuilderCwd)();
+        const timestamp = () => new Date().toISOString();
+        (0, blueprint_store_1.addBlueprintMessage)(this._db, { conversationId, role: 'user', content: userText });
+        // Deterministic title from the first user prompt (no AI spend).
+        if (!conversation.title) {
+            const title = (0, explore_draft_title_1.generateAutoTitle)([{ role: 'user', content: userText }]);
+            if (title) {
+                (0, blueprint_store_1.updateBlueprintConversation)(this._db, conversationId, { title });
+            }
+        }
+        const invoke = async (useResume) => {
+            const action = useResume ? 'chat-resume' : 'chat-turn';
+            const startedAt = new Date().toISOString();
+            let streamed = '';
+            let capturedSessionId = useResume ? conversation.session_id ?? null : null;
+            let capturedError = null;
+            console.log(`[blueprint-chat] turn start conv=${conversationId} provider=${adapter.id} action=${action} model=${model}`);
+            const invocation = this._awaitWhileLive((0, spawn_lifecycle_1.runAiCliInvocation)({
+                adapter,
+                action,
+                cwd,
+                env: { ...process.env },
+                spawn: this._spawnOwned.bind(this),
+                buildOpts: {
+                    prompt: userText,
+                    systemPrompt: adapter.capabilities.systemPromptArg ? blueprint_operator_prompt_1.BUILDER_SYSTEM_PROMPT : undefined,
+                    model,
+                    sessionId: useResume ? conversation.session_id ?? undefined : undefined,
+                    reasoning_effort: reasoningEffort,
+                },
+                onSpawn: (child) => {
+                    if (this._disposed) {
+                        this._terminate(child);
+                        return;
+                    }
+                    this._active.set(conversationId, child);
+                },
+                onEvent: (ev) => {
+                    if (this._disposed)
+                        return;
+                    switch (ev.kind) {
+                        case 'text-delta':
+                            streamed += ev.text;
+                            // Suppress broadcasts once the child left _active (abort keeps
+                            // flushing buffered stdout) so stragglers can't resurrect
+                            // client-side streaming state.
+                            if (this._active.has(conversationId)) {
+                                this._broadcast({ type: 'blueprint.stream', conversationId, delta: ev.text, timestamp: timestamp() });
+                            }
+                            break;
+                        case 'session-started':
+                            if (ev.sessionId)
+                                capturedSessionId = ev.sessionId;
+                            break;
+                        case 'result': {
+                            const sid = ev.payload.session_id;
+                            if (sid)
+                                capturedSessionId = sid;
+                            break;
+                        }
+                        case 'error':
+                            capturedError = ev.message;
+                            break;
+                        default:
+                            break;
+                    }
+                },
+            }));
+            const invocationResult = await invocation;
+            if (invocationResult.disposed) {
+                this._active.delete(conversationId);
+                return { disposed: true, text: '', sessionId: capturedSessionId, error: null, code: null, spawnFailed: false, stderrTail: '', events: [], startedAt };
+            }
+            const result = invocationResult.value;
+            this._active.delete(conversationId);
+            const text = streamed.trim();
+            if (result.stderrTail && (result.spawnFailed || (result.code ?? 0) !== 0 || !text)) {
+                console.error(`[blueprint-chat] ${adapter.id} stderr:\n${result.stderrTail}`);
+            }
+            return { disposed: false, text, sessionId: capturedSessionId, error: capturedError, code: result.code, spawnFailed: result.spawnFailed, stderrTail: result.stderrTail, events: result.events, startedAt };
+        };
+        const persistSession = (sessionId) => {
+            if (this._disposed)
+                return;
+            if ((0, blueprint_store_1.getBlueprintConversation)(this._db, conversationId)) {
+                (0, blueprint_store_1.updateBlueprintConversation)(this._db, conversationId, { session_id: sessionId });
+            }
+        };
+        // One agent_invocations row per settled turn, project_id NULL (day-0 spend).
+        const record = (outcome, status) => {
+            if (this._disposed || outcome.disposed)
+                return;
+            this._recordTurn(conversation, adapter, model, outcome, status);
+        };
+        const settleText = (r) => {
+            const { stripped, blueprint, rawBlueprint } = (0, blueprint_draft_parser_1.parseBlueprintDraftBlocks)(r.text);
+            const content = stripped.trim();
+            if ((0, blueprint_store_1.getBlueprintConversation)(this._db, conversationId)) {
+                (0, blueprint_store_1.addBlueprintMessage)(this._db, { conversationId, role: 'assistant', content: content || r.text });
+                persistSession(r.sessionId);
+            }
+            this._broadcast({
+                type: 'blueprint.done',
+                conversationId,
+                fullText: content || r.text,
+                blueprint,
+                rawBlueprint,
+                timestamp: timestamp(),
+            });
+        };
+        const canResume = !!conversation.session_id && adapter.capabilities.nativeResume;
+        let r = await invoke(canResume);
+        if (this._disposed || r.disposed)
+            return;
+        if (!(0, blueprint_store_1.getBlueprintConversation)(this._db, conversationId)) {
+            record(r, 'aborted'); // deleted mid-turn; the spawn still billed
+            return;
+        }
+        if (this._abortedTurns.delete(conversationId)) {
+            if (r.text)
+                settleText(r);
+            record(r, 'aborted');
+            return;
+        }
+        // Auto-heal a stale session: a resume with no text retries once fresh.
+        if (canResume && !r.spawnFailed && !r.text) {
+            (0, blueprint_store_1.updateBlueprintConversation)(this._db, conversationId, { session_id: null });
+            r = await invoke(false);
+            if (this._disposed || r.disposed)
+                return;
+            if (!(0, blueprint_store_1.getBlueprintConversation)(this._db, conversationId)) {
+                record(r, 'aborted');
+                return;
+            }
+            if (this._abortedTurns.delete(conversationId)) {
+                if (r.text)
+                    settleText(r);
+                record(r, 'aborted');
+                return;
+            }
+        }
+        if (r.spawnFailed) {
+            this._emitError(conversationId, `Failed to launch ${adapter.binary}. Is it installed and on PATH?`);
+            record(r, 'failed');
+            return;
+        }
+        if (r.text) {
+            settleText(r);
+            record(r, 'success');
+            return;
+        }
+        persistSession(null);
+        const reason = r.error ||
+            (r.stderrTail ? r.stderrTail.split('\n').filter(Boolean).slice(-3).join(' ').slice(0, 300) : '') ||
+            (r.code !== 0 ? `${adapter.binary} exited with code ${r.code}` : 'The Builder returned no output.');
+        this._emitError(conversationId, reason);
+        record(r, 'failed');
+    }
+    _recordTurn(conversation, adapter, model, outcome, status) {
+        if (this._disposed)
+            return;
+        try {
+            const { result, estimated } = (0, result_event_1.finaliseInvocationResult)(adapter, outcome.events, {
+                fallbackModel: model,
+            });
+            (0, desktop_db_1.recordAgentInvocation)(this._db, {
+                id: (0, crypto_1.randomUUID)(),
+                conversation_id: conversation.id,
+                project_id: null,
+                provider: adapter.id,
+                status,
+                started_at: outcome.startedAt,
+                finished_at: new Date().toISOString(),
+                total_cost_usd_estimated: estimated,
+                ...result,
+            });
+        }
+        catch (err) {
+            console.error(`[blueprint-chat] recordAgentInvocation failed (${conversation.id}):`, err);
+        }
+    }
+    /** Kills all live children and permanently gates DB access. */
+    shutdown() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        this._resolveDisposed();
+        for (const child of this._active.values())
+            this._terminate(child);
+        this._active.clear();
+    }
+}
+exports.BlueprintChatManager = BlueprintChatManager;

package/server/dist/blueprint-commit.js

@@ -0,0 +1,335 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyGhCreateError = classifyGhCreateError;
+exports.renderReadme = renderReadme;
+exports.createBlueprintCommitRunner = createBlueprintCommitRunner;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = require("crypto");
+const win_spawn_1 = require("./util/win-spawn");
+const desktop_db_1 = require("./desktop-db");
+const providers_1 = require("./providers");
+const blueprint_draft_parser_1 = require("./blueprint-draft-parser");
+const blueprint_types_1 = require("./blueprint-types");
+const blueprint_spec_quality_1 = require("./blueprint-spec-quality");
+const blueprint_render_1 = require("./blueprint-render");
+const offline_assemble_1 = require("./offline-assemble");
+const artifact_registry_1 = require("./artifact-registry");
+const workspace_manager_1 = require("./workspace-manager");
+const ticket_store_1 = require("./ticket-store");
+const project_router_helpers_1 = require("./project-router-helpers");
+function execCli(bin, args, cwd) {
+    return new Promise((resolve) => {
+        const opts = { cwd, env: (0, win_spawn_1.windowsSpawnEnv)(), stdio: ['ignore', 'pipe', 'pipe'] };
+        const child = (0, win_spawn_1.spawnCli)(bin, args, opts);
+        const stderrChunks = [];
+        child.stderr?.on('data', (chunk) => stderrChunks.push(chunk.toString()));
+        child.stdout?.resume();
+        child.once('error', (err) => resolve({ code: null, stderr: err.message }));
+        child.once('close', (code) => {
+            resolve({ code, stderr: stderrChunks.join('').split('\n').filter(Boolean).slice(-5).join(' ').slice(0, 500) });
+        });
+    });
+}
+/** Classify `gh repo create` stderr into a stable code the client can i18n. */
+function classifyGhCreateError(stderr) {
+    const s = stderr.toLowerCase();
+    if (/not logged in|gh auth login|authentication|http 401/.test(s))
+        return 'gh_not_authenticated';
+    if (/http 403|forbidden|scope|permission/.test(s))
+        return 'gh_scope';
+    if (/already exists/.test(s))
+        return 'gh_repo_exists';
+    if (/could not resolve|dial tcp|timeout|connection|network|no such host/.test(s))
+        return 'gh_network';
+    return 'gh_failed';
+}
+function expandLocation(raw) {
+    const home = process.env.SPECRAILS_REGISTRY_HOME || os_1.default.homedir();
+    const expanded = raw === '~' ? home : raw.startsWith('~/') || raw.startsWith('~\\') ? path_1.default.join(home, raw.slice(2)) : raw;
+    return path_1.default.resolve(expanded);
+}
+/** Deterministic README from the blueprint pitch — the commit must stay
+ *  offline-capable, so no AI call here (design open question, pinned). */
+function renderReadme(blueprint, name) {
+    const lines = [`# ${name}`, ''];
+    if (blueprint.product.pitch)
+        lines.push(blueprint.product.pitch, '');
+    if (blueprint.coreFlow)
+        lines.push(`**Core flow:** ${blueprint.coreFlow}`, '');
+    const stackBits = [blueprint.stack.language, blueprint.stack.framework, blueprint.stack.db].filter(Boolean);
+    if (stackBits.length > 0)
+        lines.push(`**Stack:** ${stackBits.join(' · ')}`, '');
+    lines.push('---', '', '_Bootstrapped with the Specrails Project Builder._', '');
+    return lines.join('\n');
+}
+/** Mirrors desktop-router's slugify/allocateSlug (kept local — same contract). */
+function slugifyName(name) {
+    return name
+        .toLowerCase()
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+function allocateSlug(name, existing) {
+    let base = slugifyName(name);
+    if (base === '')
+        base = 'project';
+    if (!existing.has(base))
+        return base;
+    let n = 2;
+    while (existing.has(`${base}-${n}`))
+        n += 1;
+    return `${base}-${n}`;
+}
+function dirMissingOrEmpty(dir) {
+    try {
+        const entries = fs_1.default.readdirSync(dir);
+        return entries.length === 0;
+    }
+    catch (err) {
+        return err.code === 'ENOENT';
+    }
+}
+function createBlueprintCommitRunner(deps) {
+    const io = {
+        hasCore: deps.io?.hasCore ?? offline_assemble_1.canAssembleProject,
+        mkdir: deps.io?.mkdir ?? ((dir) => fs_1.default.mkdirSync(dir, { recursive: true })),
+        exec: deps.io?.exec ?? execCli,
+        assemble: deps.io?.assemble ?? (async (opts) => (0, offline_assemble_1.assembleProjectOffline)(opts)),
+        writePair: deps.io?.writePair ?? blueprint_render_1.writeBlueprintPair,
+        mutateTickets: deps.io?.mutateTickets ?? ((filePath, fn) => { (0, ticket_store_1.mutateStore)(filePath, fn); }),
+        registerProject: deps.io?.registerProject ??
+            ((opts) => {
+                const ctx = deps.registry.addProject({
+                    id: opts.id,
+                    slug: opts.slug,
+                    name: opts.name,
+                    path: opts.path,
+                    provider: opts.providers[0],
+                    providers: opts.providers,
+                });
+                deps.broadcast({
+                    type: 'desktop.project_added',
+                    project: ctx.project,
+                    timestamp: new Date().toISOString(),
+                });
+            }),
+    };
+    const validate = (input) => {
+        const name = typeof input.name === 'string' ? input.name.trim() : '';
+        if (!name)
+            return { ok: false, error: 'invalid_name' };
+        if (typeof input.location !== 'string' || !input.location.trim()) {
+            return { ok: false, error: 'invalid_location' };
+        }
+        const location = expandLocation(input.location.trim());
+        const providers = Array.isArray(input.providers)
+            ? [...new Set(input.providers.filter((p) => typeof p === 'string' && p.length > 0))]
+            : [];
+        if (providers.length === 0)
+            return { ok: false, error: 'providers_required' };
+        for (const p of providers) {
+            if (!(0, providers_1.hasAdapter)(p))
+                return { ok: false, error: 'unknown_provider', detail: p };
+        }
+        const blueprint = (0, blueprint_draft_parser_1.coerceBlueprint)(input.blueprint);
+        if (!blueprint)
+            return { ok: false, error: 'invalid_blueprint' };
+        if (blueprint.m1Specs.length === 0) {
+            return { ok: false, error: 'm1_specs_required' };
+        }
+        if (blueprint.m1Specs.length > blueprint_types_1.M1_SPECS_MAX) {
+            return { ok: false, error: 'm1_specs_over_cap', detail: `max ${blueprint_types_1.M1_SPECS_MAX}` };
+        }
+        const rawBlueprint = input.blueprint;
+        const quality = (0, blueprint_spec_quality_1.analyzeBuilderSpecBatch)({
+            specsComplete: rawBlueprint.specsComplete,
+            specs: Array.isArray(rawBlueprint.m1Specs) ? rawBlueprint.m1Specs : [],
+        }, { milestoneLabel: 'M1', minSpecs: blueprint_types_1.M1_SPECS_MIN, maxSpecs: blueprint_types_1.M1_SPECS_MAX, requireScaffold: true });
+        if (!quality.valid) {
+            return { ok: false, error: 'm1_spec_quality_invalid', detail: (0, blueprint_spec_quality_1.firstBuilderSpecQualityDetail)(quality) };
+        }
+        if (!io.hasCore()) {
+            // Only a packaged desktop build with a missing/corrupted bundle lands
+            // here (dev + runtimes-less servers fall back to npx — see
+            // canAssembleProject). Keep the "reinstall" message for that case.
+            return { ok: false, error: 'bundled_framework_missing', detail: 'The bundled framework is missing — reinstall the Specrails app.' };
+        }
+        if (!dirMissingOrEmpty(location)) {
+            return { ok: false, error: 'location_not_empty', detail: location };
+        }
+        // No existing registry entry may map this repo path (an entry means a
+        // workspace already belongs to some other project for this realpath).
+        try {
+            if (fs_1.default.existsSync(location) && (0, artifact_registry_1.resolveArtifacts)(location).entry) {
+                return { ok: false, error: 'location_already_registered', detail: location };
+            }
+        }
+        catch {
+            /* unreadable registry — never block on the projection; addProject re-mirrors */
+        }
+        return { ok: true, blueprint, name, location, providers, createGithubRepo: input.createGithubRepo === true };
+    };
+    const start = (input) => {
+        const validated = validate(input);
+        if (!validated.ok)
+            throw new Error(`invalid commit input: ${validated.error}`);
+        const commitId = (0, crypto_1.randomUUID)();
+        void run(commitId, validated);
+        return commitId;
+    };
+    const emit = (commitId, step, status, detail, code) => {
+        deps.broadcast({
+            type: 'blueprint.commit_progress',
+            commitId,
+            step,
+            status,
+            ...(detail ? { detail } : {}),
+            ...(code ? { code } : {}),
+            timestamp: new Date().toISOString(),
+        });
+    };
+    const run = async (commitId, v) => {
+        const { blueprint, name, location, providers } = v;
+        const projectId = (0, crypto_1.randomUUID)();
+        const existingSlugs = new Set((0, desktop_db_1.listProjects)(deps.registry.desktopDb).map((p) => p.slug));
+        const slug = allocateSlug(name, existingSlugs);
+        let step = 'create-dir';
+        try {
+            // 1. create target directory
+            emit(commitId, step, 'running');
+            io.mkdir(location);
+            emit(commitId, step, 'done');
+            // 2. git init -b main + deterministic README + initial commit
+            step = 'git-init';
+            emit(commitId, step, 'running');
+            const init = await io.exec('git', ['init', '-b', 'main'], location);
+            if (init.code !== 0)
+                throw new Error(`git init failed: ${init.stderr || `exit ${init.code}`}`);
+            fs_1.default.writeFileSync(path_1.default.join(location, 'README.md'), renderReadme(blueprint, name), 'utf-8');
+            const add = await io.exec('git', ['add', 'README.md'], location);
+            if (add.code !== 0)
+                throw new Error(`git add failed: ${add.stderr || `exit ${add.code}`}`);
+            const commit = await io.exec('git', ['-c', 'user.name=Specrails', '-c', 'user.email=builder@specrails.dev', 'commit', '-m', 'Initial commit'], location);
+            if (commit.code !== 0)
+                throw new Error(`git commit failed: ${commit.stderr || `exit ${commit.code}`}`);
+            emit(commitId, step, 'done');
+            // 3. registry allocation + offline workspace assemble (per provider)
+            step = 'assemble';
+            emit(commitId, step, 'running');
+            await io.assemble({ projectPath: location, slug, desktopProjectId: projectId, providers });
+            emit(commitId, step, 'done');
+            const workspace = (0, workspace_manager_1.workspacePathFor)(slug);
+            // 4. blueprint pair into the workspace (repo stays pristine)
+            step = 'blueprint';
+            emit(commitId, step, 'running');
+            io.writePair(workspace, blueprint);
+            emit(commitId, step, 'done');
+            // 5. insert M1 tickets (todo, label M1, scaffold first, advisory ids back)
+            step = 'tickets';
+            emit(commitId, step, 'running');
+            const insertedIds = [];
+            const ticketsPath = path_1.default.join(workspace, '.specrails', 'local-tickets.json');
+            io.mutateTickets(ticketsPath, (store) => {
+                const indexToId = new Map();
+                blueprint.m1Specs.forEach((spec, index) => {
+                    const id = store.next_id;
+                    store.next_id += 1;
+                    const now = new Date().toISOString();
+                    const labels = spec.labels.includes('M1') ? spec.labels.slice() : [...spec.labels, 'M1'];
+                    const prereqIndex = spec.dependsOnIndex;
+                    const prerequisites = prereqIndex !== undefined && indexToId.has(prereqIndex) ? [indexToId.get(prereqIndex)] : [];
+                    const ticket = {
+                        id,
+                        title: spec.title,
+                        description: (0, project_router_helpers_1.formatDescriptionWithCriteria)(spec.description, spec.acceptanceCriteria),
+                        status: 'todo',
+                        priority: spec.priority,
+                        labels,
+                        assignee: null,
+                        prerequisites,
+                        metadata: {},
+                        origin_conversation_id: null,
+                        is_epic: false,
+                        parent_epic_id: null,
+                        execution_order: index + 1,
+                        short_summary: spec.shortSummary,
+                        created_at: now,
+                        updated_at: now,
+                        created_by: 'project-builder',
+                        source: 'project-builder',
+                    };
+                    store.tickets[String(id)] = ticket;
+                    indexToId.set(index, id);
+                    insertedIds.push(id);
+                });
+            });
+            // Record advisory ids + flip M1 → committed, then re-render the pair.
+            const m1 = blueprint.milestones.find((m) => m.id === 'm1') ?? blueprint.milestones[0];
+            if (m1) {
+                m1.status = 'committed';
+                m1.ticketIds = insertedIds;
+            }
+            io.writePair(workspace, blueprint);
+            emit(commitId, step, 'done');
+            // 6. register the project — LAST mutation before the optional remote
+            step = 'register';
+            emit(commitId, step, 'running');
+            io.registerProject({ id: projectId, slug, name, path: location, providers });
+            emit(commitId, step, 'done');
+            // 7. best-effort GitHub remote — never aborts. Pre-flight guards against
+            // a stale client cache sending createGithubRepo with gh absent/unauthed.
+            if (v.createGithubRepo) {
+                step = 'github';
+                emit(commitId, step, 'running');
+                try {
+                    const auth = await io.exec('gh', ['auth', 'token'], location);
+                    if (auth.code === null) {
+                        emit(commitId, step, 'warning', auth.stderr || 'gh not found', 'gh_not_installed');
+                    }
+                    else if (auth.code !== 0) {
+                        emit(commitId, step, 'warning', auth.stderr || `gh auth token exited with ${auth.code}`, 'gh_not_authenticated');
+                    }
+                    else {
+                        const gh = await io.exec('gh', ['repo', 'create', slug, '--private', '--source', '.', '--push'], location);
+                        if (gh.code === 0) {
+                            emit(commitId, step, 'done');
+                        }
+                        else {
+                            const detail = gh.stderr || `gh exited with ${gh.code}`;
+                            emit(commitId, step, 'warning', detail, classifyGhCreateError(detail));
+                        }
+                    }
+                }
+                catch (err) {
+                    emit(commitId, step, 'warning', err.message, 'gh_failed');
+                }
+            }
+            deps.broadcast({
+                type: 'blueprint.commit_done',
+                commitId,
+                projectId,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[blueprint-commit] failed at ${step}:`, message);
+            emit(commitId, step, 'failed', message);
+            deps.broadcast({
+                type: 'blueprint.commit_failed',
+                commitId,
+                step,
+                error: message,
+                timestamp: new Date().toISOString(),
+            });
+        }
+    };
+    return { validate, start };
+}