specrails-desktop 2.57.0 → 2.57.1

package/docs/internals/programmatic-agent-runtime.md

@@ -64,6 +64,8 @@ Desktop negotiates `runtime api` and sends configuration to `runtime validate --
 
 Settings are saved at `<project execution .specrails directory>/agent-runtime.json`. Missing configuration uses the default agent runtime. The retired enabled flag cannot select another engine. Malformed configuration blocks admission; it is not ignored. Saving verifies that Core exposes the expected API. Connections are stored globally in `~/.specrails/runtime-providers.json`; project files retain role references, models, limits and verification. Existing embedded connections migrate once, with stable disambiguated IDs on endpoint conflicts. New runs freeze the resolved configuration, while saved runs retain their original snapshot.
 
+**A package of a larger checkout.** A repository registered as a subdirectory of its git checkout (for example `apps/web` inside a monorepo) is isolated in a worktree of the whole checkout, so Desktop passes that directory to Core as the repository `scope` in `desktop-context.json` (Core capability `repositoryScope`). Configured checks run inside the package: a check without `cwd`, or with a `cwd` relative to the registered directory, never runs at the checkout root, where a monorepo test script fans out to every workspace. Core keeps the change inside the scope: after each developer or fixer turn it undoes edits outside it, the reviewer judges only the git change set measured against the run's base, a check that fails for missing credentials, variables or registry access stops the run for the host instead of starting a correction round, and a correction loop that stops converging stops with the reason instead of repeating the same checks. Runs admitted before scopes existed keep their frozen whole-checkout context.
+
 Core owns role instructions and permissions. The developer role edits and runs commands inside its CLI sandbox (the same autonomy as the legacy Implement step); architect and reviewer are read-only. A legacy rail profile/model selection does not override the runtime's per-role provider configuration. The JSON schema is [server/schemas/agent-runtime.schema.json](../../server/schemas/agent-runtime.schema.json), mirrored from Core. For a complete configuration, custom executor examples, Kimi capabilities and API tooling details, see [Core's runtime guide](https://github.com/fjpulidop/specrails-core/blob/main/docs/agent-runtime.md) in the paired revision.
 
 The built-in Claude adapter supports its native dollar cap. Built-in Codex, Gemini, Kimi and OpenAI-compatible adapters reject `maxCostUsd`; remove that limit for mixed-provider/local runs. Kimi also rejects token caps because its usage is unavailable. Unknown cost/tokens remain unknown in accounting, rather than becoming zero. Attempt, timeout and tool limits remain available. Existing provider services, licenses and inference costs are separate from the free open-source orchestration runtime.

package/package.json

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

package/server/dist/core-execution.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkoutSubdirectory = checkoutSubdirectory;
 exports.prepareCoreExecution = prepareCoreExecution;
 exports.coreVerificationContext = coreVerificationContext;
 exports.checkCoreCompletion = checkCoreCompletion;
@@ -25,6 +26,45 @@ function canonicalPath(path) {
         return (0, node_path_1.join)(canonicalPath(parent), (0, node_path_1.basename)(path));
     }
 }
+/** Where a directory sits inside its git checkout: '' for the checkout root or a directory outside git. */
+function checkoutSubdirectory(directory) {
+    let start;
+    try {
+        start = (0, node_fs_1.realpathSync)(directory);
+    }
+    catch {
+        return '';
+    }
+    for (let current = start;; current = (0, node_path_1.dirname)(current)) {
+        if ((0, node_fs_1.existsSync)((0, node_path_1.join)(current, '.git')))
+            return (0, node_path_1.relative)(current, start).split(node_path_1.sep).join('/');
+        if ((0, node_path_1.dirname)(current) === current)
+            return '';
+    }
+}
+/**
+ * A registered repository may be one package of a larger git checkout (a
+ * monorepo app). An isolated worktree always mounts the whole checkout, so the
+ * registered directory travels to Core as the repository scope; otherwise Core
+ * verifies, edits and reviews every workspace of the checkout.
+ */
+function registeredScope(checkout, sourcePath) {
+    if (!sourcePath)
+        return undefined;
+    const prefix = checkoutSubdirectory(sourcePath);
+    // Core already receives the registered directory itself when it is not a checkout root.
+    if (!prefix || checkoutSubdirectory(checkout) !== '')
+        return undefined;
+    try {
+        return (0, node_fs_1.statSync)((0, node_path_1.join)(checkout, ...prefix.split('/'))).isDirectory() ? [prefix] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function withoutScope(context) {
+    return { ...context, repositories: context.repositories.map(({ scope: _scope, ...repository }) => repository) };
+}
 /** Stable run identity and frozen inputs are shared by every provider and retry.
  * No cwd/global singleton: two rails in the same workspace get separate files.
  */
@@ -34,9 +74,13 @@ function prepareCoreExecution(input) {
         throw new Error('Invalid Core execution run id');
     const cwd = (0, node_fs_1.realpathSync)(input.cwd);
     (0, core_update_state_1.assertWorkspaceCoreReady)(cwd);
+    const scoped = (repository, sourcePath) => {
+        const scope = registeredScope(repository.path, sourcePath);
+        return scope ? { ...repository, scope } : repository;
+    };
     const repositories = manifest
-        ? manifest.repositories.map(repo => ({ id: repo.repositoryId, name: repo.name, path: (0, node_fs_1.realpathSync)(repo.worktreePath), baseSha: repo.baseSha }))
-        : [{ id: run.repositoryId ?? (run.spec?.repositoryIds?.length === 1 ? run.spec.repositoryIds[0] : run.projectId ? `primary-${run.projectId}` : 'primary'), name: (0, node_path_1.basename)(input.repoDir ?? cwd), path: (0, node_fs_1.realpathSync)(input.repoDir ?? cwd) }];
+        ? manifest.repositories.map(repo => scoped({ id: repo.repositoryId, name: repo.name, path: (0, node_fs_1.realpathSync)(repo.worktreePath), baseSha: repo.baseSha }, repo.sourcePath))
+        : [scoped({ id: run.repositoryId ?? (run.spec?.repositoryIds?.length === 1 ? run.spec.repositoryIds[0] : run.projectId ? `primary-${run.projectId}` : 'primary'), name: (0, node_path_1.basename)(input.repoDir ?? cwd), path: (0, node_fs_1.realpathSync)(input.repoDir ?? cwd) }, input.sourcePath)];
     if (!repositories.length || repositories.some(repo => !SAFE_ID.test(repo.id)))
         throw new Error('Invalid Core repository scope');
     const artifactRepositoryId = manifest?.artifactRepositoryId ?? repositories[0].id;
@@ -76,7 +120,9 @@ function prepareCoreExecution(input) {
     catch (error) {
         if (error.code !== 'EEXIST')
             throw error;
-        if ((0, node_fs_1.readFileSync)(contextPath, 'utf8') !== serialized)
+        const frozen = (0, node_fs_1.readFileSync)(contextPath, 'utf8');
+        // A run admitted before repository scopes existed keeps its frozen whole-checkout context.
+        if (frozen !== serialized && frozen !== JSON.stringify(withoutScope(context), null, 2) + '\n')
             throw new Error('Core execution context changed during an active run; start a new run for changed scope');
     }
     const env = { ...input.env, SPECRAILS_EXECUTION_CONTEXT: contextPath };

package/server/dist/modules/agent-runtime/runtime/agent-runtime-bridge.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RUNTIME_HOST_ENV_KEYS = void 0;
 exports.runtimeChangeName = runtimeChangeName;
+exports.scopedHostChecks = scopedHostChecks;
 exports.runAgentRuntimeInvocation = runAgentRuntimeInvocation;
 const agent_runtime_history_1 = require("./agent-runtime-history");
 const agent_runtime_repositories_1 = require("./agent-runtime-repositories");
@@ -20,6 +21,22 @@ const win_spawn_1 = require("../../../util/win-spawn");
 function runtimeChangeName(runId) {
     return 'runtime-' + (0, node_crypto_1.createHash)('sha256').update(runId).digest('hex').slice(0, 20);
 }
+/**
+ * Host checks belong to the directory the user registered: for a package of a
+ * larger checkout (Core scope) they run in that package, never at the checkout
+ * root where a monorepo test script fans out to every workspace. An explicit
+ * cwd is relative to the registered directory; one already inside the scope is kept.
+ */
+function scopedHostChecks(checks, repositories = []) {
+    return checks.map(check => {
+        const scope = repositories.find(repository => repository.id === check.repositoryId)?.scope?.[0];
+        if (!scope || (check.cwd !== undefined && (0, node_path_1.isAbsolute)(check.cwd)))
+            return check;
+        const cwd = (check.cwd ?? '.').replace(/\\/g, '/');
+        const inside = cwd === scope || cwd.startsWith(scope + '/');
+        return { ...check, cwd: inside ? cwd : node_path_1.posix.normalize(node_path_1.posix.join(scope, cwd)) };
+    });
+}
 exports.RUNTIME_HOST_ENV_KEYS = [
     'SPECRAILS_REPO_DIR', 'SPECRAILS_GIT_AUTO', 'SPECRAILS_REPO_MAP_PATH',
     'SPECRAILS_EXECUTION_CONTEXT', 'SPECRAILS_EXECUTION_MANIFEST', 'SPECRAILS_REPOSITORIES',
@@ -61,6 +78,7 @@ async function runAgentRuntimeInvocation(options) {
         const { config, origins } = (0, agent_runtime_effective_config_1.resolveEffectiveRuntimeConfig)((0, agent_runtime_settings_1.loadRuntimeConfigFile)(options.configPath, options.defaultProvider), {
             repositoryIds: admittedContext.repositories.map(repo => repo.id), source, providerOverride: options.providerOverride,
         });
+        config.verification = scopedHostChecks(config.verification, admittedContext.repositories);
         config.rolePrompts = { ...(await (0, agent_runtime_loader_1.loadCoreAgentRuntime)()).rolePromptDefaults(), ...(0, agent_runtime_settings_1.loadRuntimeRolePrompts)() };
         // Core rejects unknown connection keys: drop the desktop-only local-engine
         // fields (label/defaultModel/rates/supportsReasoningEffort) before Core sees it.

package/server/dist/modules/loops/runtime/loop-executors.js

@@ -237,7 +237,7 @@ function createLoopExecutors(opts = {}) {
             const existingContext = coreRun ? runtimeContextPath(cwd, coreRun.runId, baseEnv) : undefined;
             const programmatic = coreRun && existingContext && (coreRun.implementation || (coreRun.verificationStep && existsRuntimeRequest(existingContext)));
             const baseStepEnv = programmatic ? programmaticStepEnv(baseEnv, repoDir, executionManifest) : withProfileEnv(aiStepEnv(baseEnv, repoDir, executionManifest), provider, profileName);
-            const core = coreRun ? (0, core_execution_1.prepareCoreExecution)({ run: coreRun, cwd, repoDir, manifest: executionManifest, env: baseStepEnv }) : undefined;
+            const core = coreRun ? (0, core_execution_1.prepareCoreExecution)({ run: coreRun, cwd, repoDir, manifest: executionManifest, env: baseStepEnv, sourcePath: executionManifest ? undefined : opts.sourcePath?.() }) : undefined;
             const stepEnv = core?.env ?? baseStepEnv;
             if (coreRun?.implementation && core) {
                 completionContexts.set(coreRun.runId, { cwd, contextPath: core.contextPath, env: stepEnv, runId: coreRun.runId });
@@ -476,7 +476,7 @@ function createLoopExecutors(opts = {}) {
             if (!adapter.capabilities.persistentStdin)
                 return null;
             const baseStepEnv = withProfileEnv(aiStepEnv(resolveEnv(), repoDir, executionManifest), provider, profileName);
-            const core = coreRun ? (0, core_execution_1.prepareCoreExecution)({ run: coreRun, cwd, repoDir, manifest: executionManifest, env: baseStepEnv }) : undefined;
+            const core = coreRun ? (0, core_execution_1.prepareCoreExecution)({ run: coreRun, cwd, repoDir, manifest: executionManifest, env: baseStepEnv, sourcePath: executionManifest ? undefined : opts.sourcePath?.() }) : undefined;
             const stepEnv = core?.env ?? baseStepEnv;
             const extraArgs = aiStepExtraArgs(adapter, cwd, repoDir, executionManifest);
             if (repoDir) {
@@ -532,7 +532,7 @@ function createLoopExecutors(opts = {}) {
             const baseEnv = resolveEnv();
             const programmatic = existsRuntimeRequest(runtimeContextPath(cwd, coreRun.runId, baseEnv));
             const baseStepEnv = programmatic ? programmaticStepEnv(baseEnv, repoDir, executionManifest) : withProfileEnv(aiStepEnv(baseEnv, repoDir, executionManifest), provider, profileName);
-            const core = (0, core_execution_1.prepareCoreExecution)({ run: coreRun, cwd, repoDir, manifest: executionManifest, env: baseStepEnv });
+            const core = (0, core_execution_1.prepareCoreExecution)({ run: coreRun, cwd, repoDir, manifest: executionManifest, env: baseStepEnv, sourcePath: executionManifest ? undefined : opts.sourcePath?.() });
             if (existsRuntimeRequest(core.contextPath))
                 return (0, core_execution_1.checkCoreCompletion)(core.contextPath, cwd, { ...programmaticStepEnv(resolveEnv(), repoDir, executionManifest), SPECRAILS_EXECUTION_CONTEXT: core.contextPath }, coreRun.runId);
             const env = (0, runtime_1.buildProviderEnv)((0, providers_1.getAdapter)(provider), { prompt: '', model, reasoning_effort: effort }, core.env);

package/server/dist/project-registry.js

@@ -1106,6 +1106,8 @@ class ProjectRegistry {
         // See resolveLoopBaseEnv.
         const loopRunManager = new loop_run_manager_1.LoopRunManager(db, boundBroadcast, (0, loop_executors_1.createLoopExecutors)({
             pluginScope: () => ({ stateRoot: (0, workspace_resolution_1.resolveProjectExecution)(project).cwd, legacyProviderId: project.provider }),
+            // A project registered as a package of a larger checkout scopes Core to that package in isolated worktrees.
+            sourcePath: () => project.path,
             env: () => (0, workspace_resolution_1.resolveLoopBaseEnv)({ slug: project.slug, path: project.path }, undefined, (0, project_env_1.applyWorktreeEnvPassthrough)(db, process.env)),
             // Named rail profiles and global per-agent defaults ride the same
             // SPECRAILS_PROFILE_PATH snapshot in both AI transports. An explicit null