specrails-desktop 2.36.0 → 2.42.2

package/server/dist/setup-manager.js

@@ -26,7 +26,7 @@ const ai_invocations_1 = require("./ai-invocations");
 const crypto_1 = require("crypto");
 const artifact_registry_1 = require("./artifact-registry");
 const install_config_path_1 = require("./install-config-path");
-const bundled_core_1 = require("./bundled-core");
+const core_runtime_1 = require("./core-runtime");
 const path_resolver_1 = require("./path-resolver");
 const offline_assemble_1 = require("./offline-assemble");
 const framework_manager_1 = require("./framework-manager");
@@ -627,9 +627,10 @@ async function validateCoreContract() {
         return;
     }
     if (contract.checkpoints) {
-        const missingCheckpoints = contract.checkpoints.filter((c) => !exports.CHECKPOINTS.some((cp) => cp.key === c));
-        const extraCheckpoints = exports.CHECKPOINTS
-            .filter((cp) => !contract.checkpoints.includes(cp.key))
+        const keys = Array.isArray(contract.checkpoints) ? contract.checkpoints : Object.keys(contract.checkpoints);
+        const missingCheckpoints = keys.filter((c) => !exports.CHECKPOINTS.some((cp) => cp.key === c));
+        const extraCheckpoints = Number(contract.schemaVersion?.split('.')[0] ?? 0) >= 4 ? [] : exports.CHECKPOINTS
+            .filter((cp) => !keys.includes(cp.key))
             .map((cp) => cp.key);
         if (missingCheckpoints.length > 0 || extraCheckpoints.length > 0) {
             console.warn('[Specrails] ⚠️  specrails-core contract checkpoint mismatch:');
@@ -771,7 +772,13 @@ class SetupManager {
             providers: list,
             continueOnError: true,
             onProviderStart: (p) => emit(p, 'running'),
-            onProviderResult: (r) => emit(r.provider, r.ok ? 'done' : 'failed', r.error),
+            onProviderResult: (r) => {
+                // The WS event carries the reason to the app; the server log must too,
+                // or a packaged-app failure (installer smoke, support bundle) is blind.
+                if (!r.ok)
+                    console.warn(`[SetupManager] silent assemble: ${r.provider} failed for ${projectId}: ${r.error ?? 'unknown error'}`);
+                emit(r.provider, r.ok ? 'done' : 'failed', r.error);
+            },
         })
             .then((results) => {
             const failed = results.filter((r) => !r.ok).map((r) => r.provider);
@@ -874,7 +881,12 @@ class SetupManager {
         // assemble by symlink; openspec init is the only remaining network step) —
         // NO `npx specrails-core` round-trip. When NO bundled core is present we fall
         // through to the legacy npx probe + spawn, byte-identical to today.
-        const useBundledCore = (0, bundled_core_1.getBundledCoreCli)() !== null;
+        const selectedCore = (0, core_runtime_1.getCoreRuntimeStatus)();
+        if (selectedCore.error) {
+            this._broadcast({ type: 'setup_error', projectId, error: selectedCore.error });
+            return;
+        }
+        const useBundledCore = selectedCore.runtime !== null;
         if (useBundledCore) {
             // Materialize the framework for the selected provider (idempotent). The
             // subsequent bundled `init` finds it already present (ensureFramework
@@ -886,7 +898,7 @@ class SetupManager {
                 const fm = new framework_manager_1.FrameworkManager({
                     broadcast: (msg) => this._broadcast(msg),
                 });
-                const mat = fm.materialize((0, bundled_core_1.getBundledCoreVersion)() ?? undefined, [provider]);
+                const mat = fm.materialize(undefined, [provider]);
                 if (mat.ran && mat.errors.length > 0) {
                     console.warn(`[SetupManager] framework materialize had errors: ${mat.errors.map((e) => `${e.provider}: ${e.message}`).join('; ')}`);
                 }
@@ -935,7 +947,7 @@ class SetupManager {
         // entry realpath) is diagnosable without server-console access.
         const diagHeader = [];
         if (useBundledCore) {
-            diagHeader.push(`[diag] node=${(0, path_resolver_1.resolveBundledNodeExe)() ?? process.execPath}`, `[diag] cli=${(0, bundled_core_1.getBundledCoreCli)() ?? '<none>'}`, `[diag] cwd=${projectPath}`, `[diag] args=${initArgs.join(' ')}`, `[diag] SPECRAILS_BUNDLED_RUNTIMES_PATH=${process.env.SPECRAILS_BUNDLED_RUNTIMES_PATH ?? '<unset>'}`, `[diag] SPECRAILS_BUNDLED_CORE_PATH=${process.env.SPECRAILS_BUNDLED_CORE_PATH ?? '<unset>'}`);
+            diagHeader.push(`[diag] node=${(0, path_resolver_1.resolveBundledNodeExe)() ?? process.execPath}`, `[diag] cli=${selectedCore.runtime?.cli ?? '<none>'}`, `[diag] cwd=${projectPath}`, `[diag] args=${initArgs.join(' ')}`, `[diag] SPECRAILS_BUNDLED_RUNTIMES_PATH=${process.env.SPECRAILS_BUNDLED_RUNTIMES_PATH ?? '<unset>'}`, `[diag] SPECRAILS_BUNDLED_CORE_PATH=${process.env.SPECRAILS_BUNDLED_CORE_PATH ?? '<unset>'}`);
         }
         // Bundled core (offline, node <cli> init) when available, else legacy npx.
         const child = useBundledCore
@@ -1041,8 +1053,38 @@ class SetupManager {
             }
         });
     }
+    _completeDeterministicSetup(projectId, projectPath, provider) {
+        const root = this._artifactRoot(projectId, projectPath);
+        let installedVersion = null;
+        try {
+            const marker = (0, path_1.join)(root, '.specrails', 'specrails-version');
+            if ((0, fs_1.existsSync)(marker))
+                installedVersion = (0, fs_1.readFileSync)(marker, 'utf8').trim();
+        }
+        catch { /* not installed */ }
+        const runtime = (0, core_runtime_1.getCoreRuntimeStatus)().runtime;
+        if (!(Number((installedVersion ?? runtime?.version ?? '0').split('.')[0]) >= 5))
+            return false;
+        const validation = validateInstalledCore(root);
+        const selectedProvider = provider ?? this._projectProviders.get(projectId) ?? 'claude';
+        const summary = computeSummary(root, 'quick', selectedProvider);
+        if (!validation.ok || !installedVersion || summary.agents < 3 || summary.specrailsCommands < 1) {
+            this._broadcast({ type: 'setup_error', projectId, error: 'Core 5 uses deterministic installation. Run project installation to repair its framework; enrichment is no longer supported.' });
+            return true;
+        }
+        if (provider)
+            this._projectProviders.set(projectId, provider);
+        this._projectTiers.set(projectId, 'quick');
+        this._initCheckpoints(projectId);
+        this._syncFilesystemCheckpoints(projectId, projectPath);
+        this._broadcast({ type: 'setup_complete', projectId, summary });
+        this._onSetupDone?.(projectId);
+        return true;
+    }
     // ─── Enrich: claude -p "/specrails:enrich --from-config" ────────────────────
     startEnrich(projectId, projectPath, provider, projectName) {
+        if (this._completeDeterministicSetup(projectId, projectPath, provider))
+            return;
         this._abortedProjects.delete(projectId); // fresh run — clear any prior abort flag
         if (this._setupProcesses.has(projectId)) {
             console.warn(`[SetupManager] enrich already running for ${projectId}`);
@@ -1092,6 +1134,8 @@ class SetupManager {
         return this.startEnrich(projectId, projectPath, provider);
     }
     resumeEnrich(projectId, projectPath, sessionId, userMessage, provider) {
+        if (this._completeDeterministicSetup(projectId, projectPath, provider))
+            return;
         if (this._setupProcesses.has(projectId)) {
             console.warn(`[SetupManager] enrich already running for ${projectId}`);
             return;

package/server/dist/shell-integration/bash-shim.bash

@@ -0,0 +1,45 @@
+# Specrails — bash shell-integration shim
+# Loaded via --rcfile when the user spawns a terminal in the app.
+# Sources the user's real ~/.bashrc, then layers OSC 133 / OSC 1337 hooks on top.
+
+export SPECRAILS_SHELL_INTEGRATION_LOADED=1
+
+if [[ -r "$HOME/.bashrc" ]]; then
+  # shellcheck disable=SC1091
+  source "$HOME/.bashrc"
+fi
+
+# OSC helpers (\a = BEL terminator)
+__sr_osc_prompt_start() { printf '\e]133;A\a'; }
+__sr_osc_prompt_end()   { printf '\e]133;B\a'; }
+__sr_osc_pre_exec()     { printf '\e]133;C\a'; }
+__sr_osc_post_exec()    { printf '\e]133;D;%d\a' "${1:-0}"; }
+__sr_osc_cwd()          { printf '\e]1337;CurrentDir=%s\a' "$PWD"; }
+
+# DEBUG trap fires before each simple command.
+# Skip when inside the prompt itself (BASH_COMMAND == PROMPT_COMMAND) to avoid
+# treating the prompt as a user command.
+__sr_in_prompt=0
+__sr_debug_trap() {
+  if [[ "$__sr_in_prompt" == "1" ]]; then return; fi
+  __sr_osc_prompt_end
+  __sr_osc_pre_exec
+}
+trap '__sr_debug_trap' DEBUG
+
+# PROMPT_COMMAND wraps the user's existing PROMPT_COMMAND.
+__sr_prompt_command() {
+  local exit=$?
+  __sr_in_prompt=1
+  __sr_osc_post_exec "$exit"
+  __sr_osc_cwd
+  __sr_osc_prompt_start
+  __sr_in_prompt=0
+}
+
+if [[ -n "$PROMPT_COMMAND" ]]; then
+  PROMPT_COMMAND="__sr_prompt_command; $PROMPT_COMMAND"
+else
+  PROMPT_COMMAND="__sr_prompt_command"
+fi
+export PROMPT_COMMAND

package/server/dist/shell-integration/fish-shim.fish

@@ -0,0 +1,36 @@
+# Specrails — fish shell-integration shim
+# Sourced via `fish -C "source <this-file>"`, which runs after the user's
+# config.fish / conf.d, so the user's real fish config is preserved.
+
+set -gx SPECRAILS_SHELL_INTEGRATION_LOADED 1
+
+function __sr_osc_prompt_start
+    printf '\e]133;A\a'
+end
+
+function __sr_osc_prompt_end
+    printf '\e]133;B\a'
+end
+
+function __sr_osc_pre_exec
+    printf '\e]133;C\a'
+end
+
+function __sr_osc_post_exec
+    printf '\e]133;D;%d\a' $argv[1]
+end
+
+function __sr_osc_cwd
+    printf '\e]1337;CurrentDir=%s\a' (pwd)
+end
+
+function __sr_preexec --on-event fish_preexec
+    __sr_osc_prompt_end
+    __sr_osc_pre_exec
+end
+
+function __sr_postexec --on-event fish_postexec
+    __sr_osc_post_exec $status
+    __sr_osc_cwd
+    __sr_osc_prompt_start
+end

package/server/dist/shell-integration/powershell-shim.ps1

@@ -0,0 +1,48 @@
+# Specrails — PowerShell shell-integration shim
+# Loaded via -NoLogo -NoExit -File <shim.ps1>. Dot-sources the user's real
+# $PROFILE if it exists, then wraps the prompt function with OSC 133 marks.
+
+$env:SPECRAILS_SHELL_INTEGRATION_LOADED = '1'
+
+# Dot-source the user's real profile so their environment, aliases, modules load.
+$__srUserProfile = $PROFILE.CurrentUserAllHosts
+if (Test-Path -LiteralPath $__srUserProfile) {
+    . $__srUserProfile
+}
+
+# Capture the user's existing prompt function so we can chain to it.
+$__srOriginalPrompt = $function:prompt
+
+function global:__sr-OscEmit([string]$seq) {
+    [Console]::Write($seq)
+}
+
+# Override prompt with our wrapper.
+function global:prompt {
+    $exit = if ($global:LASTEXITCODE) { [int]$global:LASTEXITCODE } else { 0 }
+
+    # post-exec for the *previous* command, then cwd, then prompt-start.
+    __sr-OscEmit ("`e]133;D;{0}`a" -f $exit)
+    __sr-OscEmit ("`e]1337;CurrentDir={0}`a" -f (Get-Location).Path)
+    __sr-OscEmit "`e]133;A`a"
+
+    if ($__srOriginalPrompt) {
+        & $__srOriginalPrompt
+    } else {
+        "PS $((Get-Location).Path)> "
+    }
+
+    __sr-OscEmit "`e]133;B`a"
+}
+
+# Trace pre-exec via PSReadLine if available.
+if (Get-Module -Name PSReadLine -ListAvailable) {
+    try {
+        Set-PSReadLineKeyHandler -Key Enter -ScriptBlock {
+            [Microsoft.PowerShell.PSConsoleReadLine]::AcceptLine()
+            __sr-OscEmit "`e]133;C`a"
+        }
+    } catch {
+        # PSReadLine version may not support custom handlers; ignore.
+    }
+}

package/server/dist/shell-integration/zsh-shim.zsh

@@ -0,0 +1,47 @@
+# Specrails — zsh shell-integration shim
+# Loaded via ZDOTDIR override when the user spawns a terminal in the app.
+# Sources the user's real login files, then layers OSC 133 / OSC 1337 hooks on top.
+
+# Sentinel so the server can detect bootstrap success.
+export SPECRAILS_SHELL_INTEGRATION_LOADED=1
+
+# The ZDOTDIR override makes zsh read its startup files from the shim dir, so the
+# user's own ~/.zshenv/.zprofile/.zshrc/.zlogin are skipped — losing PATH,
+# Homebrew, nvm/fnm/asdf, etc. Source them ourselves from the user's real ZDOTDIR
+# (default $HOME), in zsh's normal login order, before installing our hooks so we
+# don't stomp on the user's precmd/preexec arrays.
+__sr_uz="${SPECRAILS_REAL_ZDOTDIR:-$HOME}"
+[[ -r "$__sr_uz/.zshenv" ]]  && source "$__sr_uz/.zshenv"
+[[ -r "$__sr_uz/.zprofile" ]] && source "$__sr_uz/.zprofile"
+[[ -r "$__sr_uz/.zshrc" ]]    && source "$__sr_uz/.zshrc"
+[[ -r "$__sr_uz/.zlogin" ]]   && source "$__sr_uz/.zlogin"
+unset __sr_uz
+
+# Helper: print OSC 133 sequences. \a is the BEL (ST) terminator.
+__sr_osc_prompt_start() { print -n -- $'\e]133;A\a' }
+__sr_osc_prompt_end()   { print -n -- $'\e]133;B\a' }
+__sr_osc_pre_exec()     { print -n -- $'\e]133;C\a' }
+__sr_osc_post_exec()    { print -n -- $'\e]133;D;'"${1:-0}"$'\a' }
+__sr_osc_cwd()          { print -n -- $'\e]1337;CurrentDir='"$PWD"$'\a' }
+
+# Track exit code of the last command for OSC 133;D.
+__sr_last_exit=0
+
+# precmd: runs before every prompt. Emits prompt-start and CWD.
+__sr_precmd() {
+  __sr_last_exit=$?
+  __sr_osc_post_exec "$__sr_last_exit"
+  __sr_osc_cwd
+  __sr_osc_prompt_start
+}
+
+# preexec: runs just before a command executes. Emits pre-exec and prompt-end.
+__sr_preexec() {
+  __sr_osc_prompt_end
+  __sr_osc_pre_exec
+}
+
+# Append (do not overwrite) so user-defined hooks are preserved.
+typeset -ga precmd_functions preexec_functions
+precmd_functions+=("__sr_precmd")
+preexec_functions+=("__sr_preexec")

package/server/dist/smash-runner.js

@@ -301,6 +301,7 @@ function applySmashToStore(filePath, epicId, children, nowIso, createdBy) {
             const id = s.next_id++;
             const description = composeChildDescription(child);
             const ticket = {
+                ...(target.repositoryIds ? { repositoryIds: [...target.repositoryIds] } : {}),
                 id,
                 title: child.title,
                 description,

package/server/dist/spawn-lifecycle.js

@@ -11,13 +11,10 @@
 // manages crash-respawn / idle-kill) stay with the caller via hooks + the
 // returned result. Adopting it is behaviour-preserving: the caller keeps every
 // post-close decision it had, just without re-implementing the plumbing.
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runAiCliInvocation = runAiCliInvocation;
 const node_readline_1 = require("node:readline");
-const tree_kill_1 = __importDefault(require("tree-kill"));
+const win_spawn_1 = require("./util/win-spawn");
 const cli_prompt_1 = require("./util/cli-prompt");
 const runtime_1 = require("./providers/runtime");
 const STDERR_TAIL_CAP = 64 * 1024;
@@ -42,6 +39,40 @@ function runAiCliInvocation(hooks) {
     return new Promise((resolve) => {
         let settled = false;
         let timer = null;
+        let inactivityTimer = null;
+        let child;
+        const terminateForTimeout = () => {
+            if (child.pid) {
+                (0, win_spawn_1.treeKillSafe)(child.pid, 'SIGTERM');
+                const pid = child.pid;
+                const killTimer = setTimeout(() => {
+                    try {
+                        (0, win_spawn_1.treeKillSafe)(pid, 'SIGKILL', () => { });
+                    }
+                    catch { /* gone */ }
+                }, 2000);
+                killTimer.unref?.();
+                child.once('close', () => clearTimeout(killTimer));
+            }
+            else {
+                try {
+                    child.kill('SIGTERM');
+                }
+                catch { /* already gone */ }
+            }
+        };
+        const armInactivityTimer = () => {
+            if (hooks.inactivityTimeoutMs == null || hooks.inactivityTimeoutMs <= 0 || settled)
+                return;
+            if (inactivityTimer)
+                clearTimeout(inactivityTimer);
+            inactivityTimer = setTimeout(() => {
+                hooks.onInactivityTimeout?.();
+                terminateForTimeout();
+                settle({ code: null, timedOut: true, spawnFailed: false, child });
+            }, hooks.inactivityTimeoutMs);
+            inactivityTimer.unref?.();
+        };
         const settle = (partial) => {
             if (settled)
                 return;
@@ -50,9 +81,12 @@ function runAiCliInvocation(hooks) {
                 clearTimeout(timer);
                 timer = null;
             }
+            if (inactivityTimer) {
+                clearTimeout(inactivityTimer);
+                inactivityTimer = null;
+            }
             resolve({ ...partial, events, lastResultEvent, sessionId, stderrTail });
         };
-        let child;
         try {
             child = spawn(binary, args, {
                 env,
@@ -66,6 +100,7 @@ function runAiCliInvocation(hooks) {
             return;
         }
         hooks.onSpawn?.(child);
+        armInactivityTimer();
         if (hooks.timeoutMs != null && hooks.timeoutMs > 0) {
             timer = setTimeout(() => {
                 hooks.onTimeout?.();
@@ -73,31 +108,13 @@ function runAiCliInvocation(hooks) {
                 // then escalate to SIGKILL after a grace window if the child ignores
                 // SIGTERM — otherwise a hung, signal-swallowing CLI is orphaned for the
                 // host's lifetime. (Mirrors QueueManager._kill.)
-                if (child.pid) {
-                    (0, tree_kill_1.default)(child.pid, 'SIGTERM');
-                    const pid = child.pid;
-                    const killTimer = setTimeout(() => {
-                        try {
-                            (0, tree_kill_1.default)(pid, 'SIGKILL', () => { });
-                        }
-                        catch { /* gone */ }
-                    }, 2000);
-                    killTimer.unref?.();
-                    child.once('close', () => clearTimeout(killTimer));
-                }
-                else {
-                    try {
-                        child.kill('SIGTERM');
-                    }
-                    catch { /* already gone */ }
-                }
+                terminateForTimeout();
                 settle({ code: null, timedOut: true, spawnFailed: false, child });
             }, hooks.timeoutMs);
         }
         if (child.stdout) {
             const reader = (0, node_readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
-            if (hooks.onData)
-                child.stdout.on('data', () => hooks.onData('stdout'));
+            child.stdout.on('data', () => { armInactivityTimer(); hooks.onData?.('stdout'); });
             reader.on('line', (line) => {
                 // A malformed line or a buggy adapter parser must NEVER crash the whole
                 // server process — a throw in this readline handler is otherwise an
@@ -127,12 +144,12 @@ function runAiCliInvocation(hooks) {
         if (child.stderr) {
             if (hooks.onStderrLine) {
                 const errReader = (0, node_readline_1.createInterface)({ input: child.stderr, crlfDelay: Infinity });
-                if (hooks.onData)
-                    child.stderr.on('data', () => hooks.onData('stderr'));
+                child.stderr.on('data', () => { armInactivityTimer(); hooks.onData?.('stderr'); });
                 errReader.on('line', (line) => hooks.onStderrLine(line));
             }
             else {
                 child.stderr.on('data', (chunk) => {
+                    armInactivityTimer();
                     if (hooks.onData)
                         hooks.onData('stderr');
                     if (stderrTail.length < STDERR_TAIL_CAP)

package/server/dist/spec-contract-prompt.js

@@ -0,0 +1,143 @@
+"use strict";
+// ─── The ONE premium spec contract (premium-milestone-progress D6) ─────────
+//
+// Every AI author of detailed specs derives its spec-content instructions
+// from here: the day-0 Project Builder (blueprint-operator-prompt.ts), M2+
+// milestone generation (chat-manager.ts _buildMilestoneSystemPrompt) and the
+// agent's super-spec mode (agent-operator-prompt.ts). The DEPTH bar is shared;
+// only the grounding rule differs per author (`day0` = everything introduced
+// is labelled *planned*, nothing existing may be claimed; `verified` = only
+// paths/identifiers actually read may be named).
+//
+// BYTE-STABILITY: every export is a static string / object (no timestamps,
+// no live data) so provider prompt caching keeps working across turns.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREMIUM_SCAFFOLD_EXAMPLE = exports.SPEC_DEPTH_FLOORS = void 0;
+exports.premiumSpecContract = premiumSpecContract;
+exports.premiumSpecContractCompact = premiumSpecContractCompact;
+/** Deterministic floors the quality gate enforces (server + client mirror). */
+exports.SPEC_DEPTH_FLOORS = {
+    problemMinChars: 200,
+    solutionMinChars: 500,
+    outOfScopeMinBullets: 3,
+    technicalMinBullets: 5,
+    criteriaMin: 6,
+    criteriaMax: 10,
+    criterionMinChars: 20,
+};
+const GROUNDING = {
+    day0: {
+        intro: 'No repository exists yet. Ground every technical detail in the selected stack, the planned components, the intended contracts and data shapes, the known risks and the dependencies between specs.',
+        modules: 'name the modules, components, routes, tables and files this spec will CREATE, each explicitly marked as planned (for example "src/features/pantry/PantryList.tsx (planned)") with one line of responsibility — never claim that any of them already exists',
+        technical: 'anchor bullets on the planned artifacts above and on the selected stack; never invent or imply an existing repository path, module, function, migration or test file',
+    },
+    verified: {
+        intro: 'Ground every technical detail in the real codebase you read during this conversation, never in plausible-sounding memory.',
+        modules: 'name the REAL modules, components, routes, tables and files the change builds on or extends — only ones you actually opened — plus the new ones it will create, each marked as planned',
+        technical: 'anchor bullets on EXACT file paths and identifiers you verified; if you did not read it, do not name it',
+    },
+};
+/**
+ * The full contract, as a markdown section body (no leading heading) — for
+ * instruction files and prompt bodies.
+ */
+function premiumSpecContract(mode) {
+    const g = GROUNDING[mode];
+    const f = exports.SPEC_DEPTH_FLOORS;
+    return `${g.intro} Write every spec as if a senior engineer who has never spoken to the user must implement it unattended and a non-technical reviewer must understand what they are approving: no section is a restated title, every section carries decisions.
+
+Every detailed spec MUST satisfy all of these rules:
+
+- \`kind\` is exactly \`scaffold\`, \`feature\`, or \`verification\`.
+- \`title\` is concise, imperative, unique in the batch, and in English.
+- \`shortSummary\` is one useful English sentence, no more than 240 characters.
+- \`description\` is English markdown with exactly these five \`##\` headings, once each and in this order (sub-blocks use \`###\`, never \`##\`):
+  1. \`## Problem Statement\` — 3–5 sentences (at least ${f.problemMinChars} characters): the persona, the moment the pain happens, what hurts today and why, why this belongs in THIS milestone, and what a good outcome looks like. A narrative, not a restated title.
+  2. \`## Proposed Solution\` — at least ${f.solutionMinChars} characters. Open with a numbered user journey (what the user does and sees, step by step), then these \`###\` sub-blocks:
+     - \`### User experience\` — the screens/commands involved and their states: empty, loading, error, success; copy tone; what is remembered between visits.
+     - \`### Data model\` — the entities with their fields, types, constraints and relationships (as planned).
+     - \`### Interfaces & contracts\` — routes/commands/events with request and response shapes, validation rules and error responses.
+     - \`### Planned modules\` — ${g.modules}.
+     - \`### Key decisions\` — 2–3 decisions with the alternative considered and why it was rejected.
+  3. \`## Out of Scope\` — at least ${f.outOfScopeMinBullets} bullets; each names what is deferred, why, and where it lands (a later spec or milestone by title).
+  4. \`## Technical Considerations\` — at least ${f.technicalMinBullets} labelled bullets chosen from: **Architecture**, **Data & contracts**, **Failure handling & edge cases**, **Security & privacy**, **Performance & limits**, **Observability**, **Testing strategy** (unit / integration / end-to-end with named scenarios), **Dependencies** (earlier specs by title), **Risks & mitigations**; ${g.technical}.
+  5. \`## Estimated Complexity\` — Low, Medium, High, or Very High, then 1–2 sentences on what drives the estimate and the main uncertainty.
+- Do NOT put an \`## Acceptance Criteria\` heading in \`description\`. Criteria live only in the separate \`acceptanceCriteria\` array; the app folds them into the ticket deterministically at commit time.
+- \`acceptanceCriteria\` contains ${f.criteriaMin}–${f.criteriaMax} independent, testable outcomes (each at least ${f.criterionMinChars} characters), written as observable behaviour — "Given … when … then …" or "When X, the system Y" — never implementation steps. Across the set cover: the happy path, at least one failure or edge case (invalid input, empty state, permission denied, offline, timeout), at least one automated verification (the unit/integration/e2e test that proves it), and for user-facing specs an empty-state or accessibility outcome.
+- \`priority\` is exactly \`low\`, \`medium\`, \`high\`, or \`critical\` and reflects delivery urgency/risk rather than implementation complexity.
+- \`labels\` includes the milestone label plus at least one concise domain label such as \`frontend\`, \`api\`, \`data\`, \`auth\`, \`testing\`, or \`infra\`.`;
+}
+/** One-paragraph form for \`--system-prompt\` channels (same rules, no markdown). */
+function premiumSpecContractCompact(mode) {
+    const g = GROUNDING[mode];
+    const f = exports.SPEC_DEPTH_FLOORS;
+    return `Spec depth bar (premium): ${g.intro} Each spec has kind (scaffold|feature|verification), a unique imperative English title, a one-sentence shortSummary <=240 characters, and a description with exactly these ## headings once and in order: ## Problem Statement (3-5 sentences, >=${f.problemMinChars} chars: persona, trigger, pain, why this milestone, what good looks like), ## Proposed Solution (>=${f.solutionMinChars} chars: a numbered user journey, then ### User experience with empty/loading/error/success states, ### Data model with fields and types, ### Interfaces & contracts with request/response shapes and errors, ### Planned modules — ${g.modules} — and ### Key decisions with the rejected alternative), ## Out of Scope (>=${f.outOfScopeMinBullets} bullets: what, why deferred, where it lands), ## Technical Considerations (>=${f.technicalMinBullets} labelled bullets from Architecture, Data & contracts, Failure handling & edge cases, Security & privacy, Performance & limits, Observability, Testing strategy with named scenarios, Dependencies by spec title, Risks & mitigations; ${g.technical}), ## Estimated Complexity (level plus 1-2 sentences and the main uncertainty). Never an ## Acceptance Criteria section in description. A separate acceptanceCriteria array of ${f.criteriaMin}-${f.criteriaMax} observable outcomes (>=${f.criterionMinChars} chars each, Given/When/Then style) covering the happy path, at least one failure/edge case, at least one automated verification and an empty-state/accessibility outcome for user-facing specs. priority low|medium|high|critical by urgency/risk; labels include the milestone label plus a domain label.`;
+}
+/**
+ * A complete premium example (the mandatory M1 scaffold) — rendered into the
+ * Builder prompt so the model mirrors the DEPTH, not just the shape.
+ */
+exports.PREMIUM_SCAFFOLD_EXAMPLE = {
+    kind: 'scaffold',
+    title: 'Scaffold the runnable project foundation',
+    shortSummary: 'Turn the README-only repository into an installable, runnable, testable application shell with CI, so every later slice lands on a verified foundation.',
+    description: [
+        '## Problem Statement',
+        'A contributor who clones the repository today finds a README and nothing else: there is no dependency manifest, no command that starts the app, no test to prove anything works and no CI to catch a broken change. Every Milestone-1 slice would otherwise begin by improvising its own setup, producing three incompatible foundations by week one. The walking skeleton needs this first because each later spec is defined as "runs on top of the scaffold". A good outcome is a clean checkout that installs, starts, tests and passes CI with documented commands, with zero product behaviour beyond a visible placeholder.',
+        '',
+        '## Proposed Solution',
+        '1. The contributor runs the documented install command and gets a reproducible dependency tree.',
+        '2. They run the development command and see the placeholder home screen respond on the documented port.',
+        '3. They run the test command and one smoke test passes.',
+        '4. They open a pull request and CI runs the same install, lint, build and test steps.',
+        '',
+        '### User experience',
+        'A single placeholder route/screen showing the product name and a short "foundation ready" message; no other UI. States: success (page renders), error (the process exits with a clear message when the port is taken or a dependency is missing). Nothing is remembered between visits.',
+        '',
+        '### Data model',
+        'None yet. The persistence layer is initialised (connection/config only) so later specs add entities without re-scaffolding.',
+        '',
+        '### Interfaces & contracts',
+        '`GET /health` → `{ "status": "ok", "version": "<package version>" }` (200). Development, build and test commands documented in the README with their exit-code semantics.',
+        '',
+        '### Planned modules',
+        '- `package manifest + lockfile (planned)` — pinned runtime and dependency versions.',
+        '- `src/app entry (planned)` — process bootstrap, port/config loading, the placeholder route.',
+        '- `src/config (planned)` — typed environment loading with defaults.',
+        '- `tests/smoke (planned)` — one end-to-end smoke test hitting `/health`.',
+        '- `CI workflow (planned)` — install → lint → build → test on every push and pull request.',
+        '',
+        '### Key decisions',
+        '- Keep the placeholder minimal instead of seeding a real feature: a feature here would blur the boundary later specs build on. Rejected: scaffolding the first product screen now.',
+        '- Pin exact dependency versions from day one; floating ranges were rejected because the first CI break would be a dependency drift, not a product bug.',
+        '',
+        '## Out of Scope',
+        '- Any product feature beyond the placeholder — every slice of the core flow lands in the later Milestone-1 specs.',
+        '- Production deployment, hosting and environment provisioning — deferred to a later milestone once the skeleton runs end to end.',
+        '- Authentication, authorization and user accounts — a dedicated Milestone-1 or Milestone-2 spec owns them.',
+        '',
+        '## Technical Considerations',
+        '- **Architecture**: one process, one entry module, configuration read once at boot; later specs add modules under the planned layout rather than reshaping it.',
+        '- **Data & contracts**: `/health` is the only contract; its response shape is frozen so CI and later monitoring can rely on it.',
+        '- **Failure handling & edge cases**: a missing runtime or an occupied port fails fast with an actionable message; the smoke test fails when `/health` is not 200.',
+        '- **Security & privacy**: no secrets committed; `.env.example` documents variables; the health endpoint exposes no internal detail beyond the version.',
+        '- **Performance & limits**: cold start under a few seconds on a laptop; no performance work beyond that.',
+        '- **Observability**: structured startup log line with port and version; CI logs are the audit trail.',
+        '- **Testing strategy**: unit — config loading with and without overrides; e2e — the smoke test starts the app and asserts `/health`; CI runs both on every change.',
+        '- **Dependencies**: none (first spec); every later Milestone-1 spec depends on this one.',
+        '- **Risks & mitigations**: toolchain drift between contributors — mitigated by the pinned lockfile and CI running from a clean checkout.',
+        '',
+        '## Estimated Complexity',
+        'Medium — the foundation must align local development, automated tests and CI without implementing product behaviour; the main uncertainty is CI runtime setup for the chosen stack.',
+    ].join('\n'),
+    acceptanceCriteria: [
+        'Given a clean checkout, when the contributor runs the documented install command, then it completes without errors and produces the pinned dependency tree.',
+        'When the development command runs, the placeholder screen renders and GET /health returns 200 with { status: "ok", version } within a few seconds.',
+        'When the test command runs from a clean checkout, the smoke test passes and the process exits with code 0.',
+        'When the configured port is already in use, the process exits non-zero with a message naming the port instead of hanging.',
+        'When a pull request is opened, CI runs install, lint, build and test and reports a red status on any failure.',
+        'The README documents the install, run and test commands and a contributor can follow them without asking anyone.',
+    ],
+    priority: 'high',
+    labels: ['M1', 'foundation', 'infra'],
+};

package/server/dist/spec-draft-parser.js

@@ -29,6 +29,9 @@ function validateBlock(parsed) {
         partial.title = obj.title;
     if (typeof obj.description === 'string')
         partial.description = obj.description;
+    if (Array.isArray(obj.repositoryIds) && obj.repositoryIds.length > 0 && obj.repositoryIds.every((id) => typeof id === 'string' && id.trim()) && new Set(obj.repositoryIds).size === obj.repositoryIds.length) {
+        partial.repositoryIds = [...obj.repositoryIds];
+    }
     const labels = coerceStringArray(obj.labels);
     if (labels)
         partial.labels = labels;
@@ -87,6 +90,8 @@ function mergeDraft(prev, next) {
         out.title = next.title;
     if (typeof next.description === 'string' && next.description !== '')
         out.description = next.description;
+    if (Array.isArray(next.repositoryIds) && next.repositoryIds.length > 0 && next.repositoryIds.every((id) => typeof id === 'string' && id.trim()) && new Set(next.repositoryIds).size === next.repositoryIds.length)
+        out.repositoryIds = next.repositoryIds.slice();
     if (Array.isArray(next.labels))
         out.labels = next.labels.slice();
     if (Array.isArray(next.acceptanceCriteria))
@@ -108,7 +113,7 @@ function applyBlocks(prev, blocks) {
     for (const block of blocks) {
         const before = nextDraft;
         nextDraft = mergeDraft(before, block.partial);
-        for (const key of ['title', 'description', 'labels', 'priority', 'acceptanceCriteria']) {
+        for (const key of ['title', 'description', 'labels', 'priority', 'acceptanceCriteria', 'repositoryIds']) {
             if (!shallowEqual(before[key], nextDraft[key]))
                 changed.add(key);
         }

package/server/dist/spec-models.js

@@ -12,6 +12,7 @@ exports.CLAUDE_MODELS = [
     { value: 'haiku', label: 'Claude Haiku' },
 ];
 exports.CODEX_MODELS = [
+    { value: 'gpt-6-astra', label: 'GPT-6 Astra' },
     { value: 'gpt-5.6-sol', label: 'GPT-5.6 Sol' },
     { value: 'gpt-5.6-terra', label: 'GPT-5.6 Terra' },
     { value: 'gpt-5.6-luna', label: 'GPT-5.6 Luna' },

package/server/dist/stuck-run-detector.js

@@ -117,6 +117,7 @@ class StuckRunDetector {
                 jobId: candidate.runId,
                 stepKey: candidate.stepKey,
                 staleMs: candidate.staleMs,
+                actions: ['stop'],
                 timestamp: new Date(this.io.now?.() ?? Date.now()).toISOString(),
             };
             try {