specrails-desktop 2.44.1 → 2.44.2

package/docs/internals/verification-handoff-regression.md

@@ -0,0 +1,70 @@
+# Verification handoff and framework activation regression
+
+The September 10, 2026 implementation incident ended with an agent reporting
+success while Core reported `implementation=complete`, `validation=blocked`,
+`archive=done`, and `delivery=pending-host`. The repository's 127 tests passed;
+inspection rejected the receipt with `Verification environment changed: npm`.
+
+A second Windows execution reproduced the same terminal contradiction after
+the coordinator reported successful unit and browser checks, completed archive,
+and skipped host-owned shipping/CI phases. It refreshed verification and moved
+archive execution into the coordinator's session to avoid handoff drift, but
+the host still reported blocked validation. This corroborates the cross-process
+failure pattern; the transcript alone does not identify the differing variables
+or establish a cloud-synced project path as the cause. Runtime diagnostics now
+report added/removed environment key names without values. If only values differ,
+the aggregate hash cannot identify the individual key.
+
+Three independent problems made recovery unreliable:
+
+1. The installed app bundled Core 5.2.2, but `framework/current` still resolved to
+   5.2.1. Desktop materialized the providers in its project catalog, omitting Kimi
+   already represented in `current`. Core correctly refused to activate the
+   incomplete destination. The session-identity fix in 5.2.2 was never active.
+2. Verification included agent-session metadata and automatically generated
+   untracked memory in its evidence. A process handoff or a final memory write
+   could invalidate verification after a successful check. Ignoring metadata in
+   the fingerprint alone also left those unrecorded inputs visible to tests.
+3. A successful provider process could become a successful implementation step
+   without a final deterministic check of Core's state.
+
+## Required invariants
+
+- Framework materialization must satisfy the same provider union as Core's
+  activation gate: requested providers, the shared registry, and provider
+  directories or completion stamps represented in `current`. Failure leaves the
+  previous version active.
+- Core removes known session/launcher metadata from verification subprocesses
+  as well as from their environment fingerprint. Explicit command overrides are
+  retained and bound without storing their values. Application configuration,
+  PATH, NODE_OPTIONS, custom variables and SPECRAILS configuration still count.
+  Windows environment names are normalized without changing POSIX semantics.
+- Only untracked files under known provider `agent-memory/` roots are excluded
+  as generated notes. Tracked memory, settings, skills and other source inputs
+  remain part of the candidate.
+- Old environment-policy receipts require a fresh full verification. Do not
+  edit receipts or phase records to turn an old failure into success.
+- Desktop checks installed Core after Implement/Batch steps, for both interactive
+  and one-shot execution. Blocked validation, incomplete phases, an invalid full
+  receipt, a failed status call or mismatched run identity prevents success.
+  `pending-host` describes delivery ownership and does not invalidate otherwise
+  verified implementation work.
+
+## Regression coverage and rollout
+
+Core's `pipeline-state.test.ts` exercises real subprocess handoffs, archive
+completion followed by a host inspection, explicit overrides, environment/input
+changes, generated versus tracked memory and Windows environment normalization.
+Desktop's `loop-core-completion.test.ts` runs the completion-status subprocess
+through the loop engine and verifies the stored result. Framework tests cover
+the omitted-provider activation failure and preservation of the previous version.
+An offline test with the actual 5.2.1 and bundled 5.2.2 packages also validated
+the provider-union update in an isolated home.
+
+Activating the existing 5.2.2 bundle repairs the missed previous update. The
+additional environment, memory, completion and materialization changes require
+new Core and Desktop releases. These changes have been ported onto Core 5.2.2
+and Desktop 2.44.1 for review. Never replace a newer installed runtime with an
+older checkout build, and verify both
+the selected package version and the actual `framework/current` target after
+activation. Refresh copied workspace files through the normal reseed lifecycle.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.44.1",
+  "version": "2.44.2",
   "license": "MIT",
   "repository": {
     "type": "git",

package/server/dist/background-windows-bootstrap.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WINDOWS_BACKGROUND_BOOTSTRAP = void 0;
+exports.WINDOWS_BACKGROUND_BOOTSTRAP = exports.WINDOWS_JOB_PREPARATION_TIMEOUT_MS = void 0;
 exports.spawnWindowsBackgroundBootstrap = spawnWindowsBackgroundBootstrap;
 const child_process_1 = require("child_process");
 const node_net_1 = require("node:net");
@@ -14,6 +14,9 @@ const node_crypto_1 = require("node:crypto");
 const path_resolver_1 = require("./path-resolver");
 const win_spawn_1 = require("./util/win-spawn");
 const windows_job_supervisor_1 = require("./windows-job-supervisor");
+// PowerShell startup and Add-Type compilation can exceed 15s on cold Windows
+// ARM runners. Keep preparation bounded without admitting any application code.
+exports.WINDOWS_JOB_PREPARATION_TIMEOUT_MS = 60_000;
 // Keep the owned Windows root alive until its creation identity is captured.
 // User commands never enter argv and cannot start before the parent opens stdin.
 exports.WINDOWS_BACKGROUND_BOOTSTRAP = String.raw `
@@ -130,12 +133,12 @@ function spawnWindowsBackgroundBootstrap(command, cwd) {
     }
     catch { /* no child */ } });
     const startupTimer = setTimeout(() => {
-        fail(new Error('Windows job containment preparation timed out; no application was admitted.'));
+        fail(new Error(`Windows job containment preparation timed out after ${exports.WINDOWS_JOB_PREPARATION_TIMEOUT_MS}ms (${socket ? 'control pipe connected, awaiting job assignment' : 'awaiting supervisor control pipe'}); no application was admitted.`));
         try {
             child?.kill();
         }
         catch { /* already gone */ }
-    }, 15_000);
+    }, exports.WINDOWS_JOB_PREPARATION_TIMEOUT_MS);
     startupTimer.unref?.();
     const cleanup = () => {
         clearTimeout(startupTimer);

package/server/dist/core-execution.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.prepareCoreExecution = prepareCoreExecution;
 exports.coreVerificationContext = coreVerificationContext;
+exports.checkCoreCompletion = checkCoreCompletion;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -110,3 +111,47 @@ function coreVerificationContext(contextPath, cwd, env, runId) {
         return '';
     }
 }
+/** A successful provider turn is not a completed implementation. Ask Core to
+ * revalidate the journal on disk before Desktop accepts the implementation step,
+ * including when an agent claims PASS after its final receipt went stale. */
+function checkCoreCompletion(contextPath, cwd, env, runId) {
+    const helper = (0, node_path_1.join)(cwd, '.specrails', 'runtime', 'pipeline.mjs');
+    if (!(0, node_fs_1.existsSync)(helper))
+        return { valid: false, reason: 'Core completion cannot be validated: pipeline runtime is missing' };
+    try {
+        const stdout = (0, node_child_process_1.execFileSync)((0, path_resolver_1.resolveBundledNodeExe)() ?? process.execPath, [helper, 'status', '--context', contextPath], {
+            cwd, env, encoding: 'utf8', timeout: 15_000, maxBuffer: 4 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const status = JSON.parse(stdout);
+        if (status.schemaVersion !== 1 || status.runId !== runId)
+            return { valid: false, reason: 'Core completion returned an invalid or mismatched run identity' };
+        const reasons = [];
+        // Core 5.1 exposes phases/verification; newer runtimes also provide an
+        // explicit completion verdict. Never override a newer blocked verdict with
+        // older phase statuses or an agent-authored summary.
+        if (status.completion) {
+            for (const [key, expected] of [['implementation', 'complete'], ['archive', 'done']]) {
+                if (status.completion[key] !== expected)
+                    reasons.push(`${key}=${status.completion[key] ?? 'missing'}`);
+            }
+            if (!['verified', 'with-exceptions'].includes(status.completion.validation ?? ''))
+                reasons.push(`validation=${status.completion.validation ?? 'missing'}`);
+            if (reasons.length)
+                reasons.push(...(status.completion.reasons ?? []));
+        }
+        for (const phase of ['architect', 'developer', 'reviewer', 'archive']) {
+            if (status.phases?.[phase]?.status !== 'done')
+                reasons.push(`${phase} phase is incomplete`);
+        }
+        if (status.resumePhase && ['architect', 'developer', 'reviewer', 'archive'].includes(status.resumePhase))
+            reasons.push(`resume from ${status.resumePhase}`);
+        const receipt = status.verification?.receipt;
+        if (status.verification?.valid !== true || receipt?.kind !== 'full' || !receipt.commands?.length || receipt.commands.some(command => command.exitCode !== 0)) {
+            reasons.push(...(status.verification?.reasons?.length ? status.verification.reasons : ['No valid full verification receipt']));
+        }
+        return reasons.length ? { valid: false, reason: `Core completion blocked: ${[...new Set(reasons)].join('; ')}` } : { valid: true };
+    }
+    catch {
+        return { valid: false, reason: 'Core completion cannot be validated: pipeline status failed or returned invalid JSON' };
+    }
+}

package/server/dist/framework-manager.js

@@ -44,6 +44,28 @@ function realpathOrSelf(p) {
         return p;
     }
 }
+/** Match Core's swap-current provider requirement: a project removed from the
+ * Desktop catalog can still have live links through current. A subtree OR its
+ * completion stamp is enough to require that provider in the next version. */
+function requiredFrameworkProviders(fwDir, requested, home) {
+    const directories = {
+        claude: '.claude', codex: '.codex', gemini: '.gemini', kimi: '.kimi-code',
+    };
+    const required = new Set(requested);
+    for (const entry of Object.values((0, artifact_registry_1.readRegistryOrEmpty)(home).projects)) {
+        for (const provider of [...(entry.providers ?? []), entry.primaryProvider]) {
+            if (Object.hasOwn(directories, provider))
+                required.add(provider);
+        }
+    }
+    for (const [provider, directory] of Object.entries(directories)) {
+        if (fs_1.default.existsSync(path_1.default.join(fwDir, 'current', directory))
+            || fs_1.default.existsSync(path_1.default.join(fwDir, 'current', `.framework-stamp${directory}.json`))) {
+            required.add(provider);
+        }
+    }
+    return [...required];
+}
 class FrameworkManager {
     home;
     broadcast;
@@ -101,7 +123,7 @@ class FrameworkManager {
         fs_1.default.mkdirSync(fwDir, { recursive: true });
         const errors = [];
         const done = [];
-        for (const provider of dedupe(providers)) {
+        for (const provider of requiredFrameworkProviders(fwDir, providers, this.home)) {
             const res = (0, child_process_1.spawnSync)(nodeInterpreter(), [
                 cli,
                 'install-framework',
@@ -357,6 +379,3 @@ class FrameworkManager {
     }
 }
 exports.FrameworkManager = FrameworkManager;
-function dedupe(values) {
-    return Array.from(new Set(values));
-}

package/server/dist/loop-executors.js

@@ -489,6 +489,12 @@ function createLoopExecutors(opts = {}) {
                 ...(effectiveIdleTimeoutMs > 0 ? { idleTimeoutMs: effectiveIdleTimeoutMs } : {}),
             };
         },
+        validateCoreCompletion({ coreRun, provider, model, effort, profileName, cwd, repoDir, executionManifest }) {
+            const baseStepEnv = withProfileEnv(aiStepEnv(resolveEnv(), repoDir, executionManifest), provider, profileName);
+            const core = (0, core_execution_1.prepareCoreExecution)({ run: coreRun, cwd, repoDir, manifest: executionManifest, env: baseStepEnv });
+            const env = (0, runtime_1.buildProviderEnv)((0, providers_1.getAdapter)(provider), { prompt: '', model, reasoning_effort: effort }, core.env);
+            return (0, core_execution_1.checkCoreCompletion)(core.contextPath, cwd, env, coreRun.runId);
+        },
         async runShell({ command, cwd, repoDir, onLine, onSpawn, timeoutMs }) {
             const env = resolveEnv();
             return runShellCommand(command, repoDir ?? cwd, repoDir ? { ...env, SPECRAILS_REPO_DIR: repoDir } : env, timeoutMs ?? SHELL_TIMEOUT_MS, onLine, onSpawn);

package/server/dist/loop-run-manager.js

@@ -1058,6 +1058,8 @@ class LoopRunManager {
                         // --yes`, codex `$implement #<id> --yes`) — then resolve `{{spec.*}}`
                         // data tokens and finally `{{const:*}}` library constants.
                         const rawTemplate = String(node.data?.prompt ?? '');
+                        const requiresCoreCompletion = /\{\{\s*cmd:(?:implement|batch)\s*\}\}/.test(rawTemplate)
+                            || /^\s*(?:\/specrails:|\/skill:specrails-|\$)(?:implement|batch-implement)(?:\s|$)/.test(rawTemplate);
                         const expanded = (0, loop_constants_1.resolveConstants)(resolveRunVars((0, loop_graph_1.interpolateSpec)((0, loop_command_catalog_1.expandCommands)(rawTemplate, { provider: nodeProvider, ticketIds: req.spec?.ticketIds, specId: req.spec?.id }), req.spec), runVars), constMap);
                         const base = [(0, multi_repo_execution_store_1.executionManifestPrompt)(req.executionManifest), withReviewContinuationContext(expanded, rawTemplate, req.spec)].filter(Boolean).join('\n\n');
                         // Inject the cross-iteration history only when there's no live session
@@ -1220,6 +1222,19 @@ class LoopRunManager {
                             settled = true;
                             break;
                         }
+                        if (!res.failed && !zeroWork && !this._cancelled.has(runId)
+                            && requiresCoreCompletion
+                            && this.executors.validateCoreCompletion) {
+                            const completion = this.executors.validateCoreCompletion({
+                                coreRun: { runId, spec: req.spec, goal: req.spec ? undefined : JSON.stringify({ loop: req.loopName, graph: req.graph }), repositoryId: req.repositoryId },
+                                provider: nodeProvider, model: nodeModel, effort: nodeEffort, profileName: req.profileName,
+                                cwd: req.cwd, repoDir: req.repoDir, executionManifest: req.executionManifest,
+                            });
+                            if (!completion.valid) {
+                                res = { ...res, failed: true, errorText: completion.reason ?? 'Core implementation is incomplete' };
+                                logLine(`✖ ${res.errorText}`, 'stderr');
+                            }
+                        }
                         const blockedReason = aiStepBlockedReason(res.text);
                         const requiresVerification = node.data?.requireVerificationPass === true
                             || /\{\{cmd:(?:verify|revision-verify|opsx:verify)\}\}/.test(rawTemplate);
@@ -1613,8 +1628,6 @@ class LoopRunManager {
         catch (err) {
             console.error(`[loop] staged accounting reconciliation failed for ${runId}:`, err);
         }
-        console.log(`[loop] settle run=${runId} outcome=${outcome} iterations=${iteration} ` +
-            (usageTelemetryAvailable ? `cost=$${totalCost.toFixed(4)}` : 'usage=unavailable'));
         // Execution and acceptance are separate facts. Persist the runtime's own
         // terminal snapshot alongside counters so history does not depend on prose.
         let coreCompletion = null;
@@ -1625,6 +1638,8 @@ class LoopRunManager {
         const executionOutcome = outcome;
         if (outcome === 'success' && coreCompletion && (coreCompletion.completion.implementation !== 'complete' || !['verified', 'with-exceptions'].includes(coreCompletion.completion.validation)))
             outcome = 'blocked';
+        console.log(`[loop] settle run=${runId} outcome=${outcome} iterations=${iteration} ` +
+            (usageTelemetryAvailable ? `cost=$${totalCost.toFixed(4)}` : 'usage=unavailable'));
         emitRunEvent('loop_completion', {
             version: 1, execution: executionOutcome, steps: stepNum, deciderEvaluations: iteration,
             turns: finalJobUsage.numTurns, costUsd: usageTelemetryAvailable ? totalCost : null,
@@ -1642,7 +1657,7 @@ class LoopRunManager {
         // `≥` when any cost-bearing step ended unpriced (timeout/crash) — the figure
         // is a lower bound, not exact. Providers without usage telemetry get an
         // explicit unavailable marker, never a fabricated "$0.0000".
-        logLine(`\n■ Loop execution finished: ${executionOutcome} — ${stepNum} step${stepNum === 1 ? '' : 's'}, ${iteration} decider evaluation${iteration === 1 ? '' : 's'}, ${finalJobUsage.numTurns ?? 'unknown'} agent turns, ` +
+        logLine(`\n■ Loop execution finished: ${outcome} — ${stepNum} step${stepNum === 1 ? '' : 's'}, ${iteration} decider evaluation${iteration === 1 ? '' : 's'}, ${finalJobUsage.numTurns ?? 'unknown'} agent turns, ` +
             (usageTelemetryAvailable
                 ? `${costUncertain ? '≥ ' : ''}$${totalCost.toFixed(4)}`
                 : 'usage/cost unavailable'));