@treeseed/sdk 0.12.43 → 0.12.45

package/dist/operations/services/package-artifacts.js

@@ -0,0 +1,99 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { runTreeseedGitText } from "./git-runner.js";
+function readPackageJson(packageRoot) {
+  const path = resolve(packageRoot, "package.json");
+  if (!existsSync(path)) throw new Error(`Package artifact build requires ${path}.`);
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+function fileDigest(path) {
+  const bytes = readFileSync(path);
+  return {
+    sha256: createHash("sha256").update(bytes).digest("hex"),
+    size: bytes.byteLength
+  };
+}
+function buildTreeseedPackageArtifact(input) {
+  const packageRoot = resolve(input.packageRoot);
+  const outputDir = resolve(input.outputDir);
+  const pkg = readPackageJson(packageRoot);
+  const packageName = typeof pkg.name === "string" ? pkg.name : "";
+  const packageVersion = typeof pkg.version === "string" ? pkg.version : "";
+  if (!packageName || !packageVersion) throw new Error("Package artifact build requires package name and version.");
+  mkdirSync(outputDir, { recursive: true });
+  const result = spawnSync("npm", ["pack", "--json", "--ignore-scripts", "--pack-destination", outputDir], {
+    cwd: packageRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    env: process.env
+  });
+  if ((result.status ?? 1) !== 0) throw new Error(`npm pack failed for ${packageName}.
+${result.stderr || result.stdout}`);
+  const output = JSON.parse(result.stdout);
+  const filename = output[0]?.filename;
+  if (!filename) throw new Error(`npm pack did not report an artifact for ${packageName}.`);
+  const artifactPath = resolve(outputDir, basename(filename));
+  if (!existsSync(artifactPath)) throw new Error(`npm pack artifact is missing: ${artifactPath}`);
+  const sourceSha = runTreeseedGitText(["rev-parse", "HEAD"], { cwd: packageRoot, mode: "read" }).trim();
+  const digest = fileDigest(artifactPath);
+  const manifest = {
+    schemaVersion: 1,
+    kind: "treeseed.package-artifact",
+    packageName,
+    packageVersion,
+    sourceSha,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    file: basename(artifactPath),
+    sha256: digest.sha256,
+    size: digest.size
+  };
+  const manifestPath = resolve(outputDir, "manifest.json");
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`, "utf8");
+  return { artifactPath, manifestPath, manifest };
+}
+function verifyTreeseedPackageArtifact(input) {
+  const manifestPath = resolve(input.manifestPath);
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  if (manifest.schemaVersion !== 1 || manifest.kind !== "treeseed.package-artifact") {
+    throw new Error(`Unsupported package artifact manifest: ${manifestPath}`);
+  }
+  const artifactPath = resolve(input.artifactPath ?? resolve(dirname(manifestPath), manifest.file));
+  if (!existsSync(artifactPath)) throw new Error(`Package artifact is missing: ${artifactPath}`);
+  const digest = fileDigest(artifactPath);
+  if (digest.sha256 !== manifest.sha256 || digest.size !== manifest.size) {
+    throw new Error(`Package artifact integrity check failed for ${artifactPath}.`);
+  }
+  return { ok: true, artifactPath, manifestPath, manifest };
+}
+function hydrateTreeseedPackageArtifacts(input) {
+  const artifactsRoot = resolve(input.artifactsRoot);
+  const projectRoot = resolve(input.projectRoot);
+  const manifests = readdirSync(artifactsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory() && existsSync(resolve(artifactsRoot, entry.name, "manifest.json"))).map((entry) => verifyTreeseedPackageArtifact({ manifestPath: resolve(artifactsRoot, entry.name, "manifest.json") })).sort((left, right) => left.manifest.packageName.localeCompare(right.manifest.packageName));
+  if (manifests.length === 0) throw new Error(`No package artifact manifests found under ${artifactsRoot}.`);
+  for (const entry of manifests) {
+    const packagePath = resolve(projectRoot, "node_modules", ...entry.manifest.packageName.split("/"));
+    rmSync(packagePath, { recursive: true, force: true });
+    mkdirSync(packagePath, { recursive: true });
+    const result = spawnSync("tar", ["-xzf", entry.artifactPath, "--strip-components=1", "-C", packagePath], {
+      cwd: projectRoot,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      env: process.env
+    });
+    if ((result.status ?? 1) !== 0) throw new Error(`Candidate artifact extraction failed for ${entry.manifest.packageName}.
+${result.stderr || result.stdout}`);
+    const installed = readPackageJson(packagePath);
+    if (installed.version !== entry.manifest.packageVersion) {
+      throw new Error(`Hydrated ${entry.manifest.packageName} version mismatch: expected ${entry.manifest.packageVersion}, observed ${String(installed.version)}.`);
+    }
+  }
+  return { ok: true, projectRoot, artifactsRoot, packages: manifests.map((entry) => entry.manifest) };
+}
+export {
+  buildTreeseedPackageArtifact,
+  hydrateTreeseedPackageArtifacts,
+  verifyTreeseedPackageArtifact
+};

package/dist/operations/services/railway-deploy.js

@@ -6,6 +6,7 @@ import { resolveTreeseedMachineEnvironmentValues } from "./config-runtime.js";
 import { createPersistentDeployTarget, resolveTreeseedResourceIdentity } from "./deploy.js";
 import { classifyTreeseedGitMode, runTreeseedGitText } from "./git-runner.js";
 import { discoverTreeseedApplications } from "../../hosting/apps.js";
+import { apiRailwayDefaultDockerfilePath, apiRailwayDefaultSourceRepo, assertApiRailwaySourcePolicy, isApiRailwaySourcePolicyService } from "./railway-source-policy.js";
 import { runPrefixedCommand, sleep } from "./bootstrap-runner.js";
 import {
   ensureRailwayEnvironment,
@@ -142,6 +143,15 @@ function configuredEnvValue(env, name) {
   const value = env?.[name];
   return typeof value === "string" && value.trim() ? value.trim() : "";
 }
+function configuredApiPublicBaseUrl(deployConfig, scope) {
+  const apiSurface = deployConfig.surfaces?.api;
+  if (!apiSurface || typeof apiSurface !== "object") return null;
+  const environment = apiSurface.environments?.[scope];
+  const configured = environment?.baseUrl ?? environment?.domain ?? (scope === "local" ? apiSurface.localBaseUrl : null) ?? apiSurface.publicBaseUrl ?? null;
+  if (typeof configured !== "string" || !configured.trim()) return null;
+  const value = configured.trim().replace(/\/+$/u, "");
+  return /^https?:\/\//iu.test(value) ? value : `https://${value}`;
+}
 function railwayDeployTransport(env) {
   const configured = configuredEnvValue(env, "TREESEED_RAILWAY_DEPLOY_TRANSPORT").toLowerCase();
   return configured === "cli-fallback" ? "cli-fallback" : "api";
@@ -672,7 +682,7 @@ function configuredRailwayServicesForConfig(tenantRoot, scope, deployConfig, app
       normalizedScope,
       service.environments?.[normalizedScope]?.railwayEnvironment
     );
-    const publicBaseUrl = service.environments?.[normalizedScope]?.baseUrl ?? service.publicBaseUrl ?? null;
+    const publicBaseUrl = service.environments?.[normalizedScope]?.baseUrl ?? service.publicBaseUrl ?? (serviceKey === "api" ? configuredApiPublicBaseUrl(deployConfig, normalizedScope) : null);
     const configuredServiceName = service.railway?.serviceName ?? (serviceKey === "workerRunner" ? deriveRailwayWorkerRunnerServiceName(identity.deploymentKey) : `${identity.deploymentKey}-${railwayServiceNameSuffix(serviceKey)}`);
     const configuredRunnerPool = service.railway?.runnerPool && typeof service.railway.runnerPool === "object" ? service.railway.runnerPool : null;
     const runnerPool = serviceKey === "operationsRunner" || serviceKey === "capacityProviderRunner" ? {
@@ -721,7 +731,7 @@ function configuredRailwayServicesForConfig(tenantRoot, scope, deployConfig, app
         sourceBranch: sourcePolicy.sourceBranch,
         sourceCommit: sourcePolicy.sourceCommit,
         sourceRootDirectory: sourcePolicy.sourceRootDirectory,
-        dockerfilePath: sourcePolicy.sourceMode === "git" ? service.railway?.dockerfilePath ?? null : null,
+        dockerfilePath: sourcePolicy.sourceMode === "git" ? service.railway?.dockerfilePath ?? apiRailwayDefaultDockerfilePath({ key: serviceKey, serviceName }) : null,
         healthcheckPath: service.railway?.healthcheckPath ?? null,
         healthcheckTimeoutSeconds: service.railway?.healthcheckTimeoutSeconds ?? null,
         healthcheckIntervalSeconds: service.railway?.healthcheckIntervalSeconds ?? null,
@@ -764,6 +774,9 @@ function configuredPublicTreeDxRailwayServices({ tenantRoot, scope, deployConfig
   const configuredSource = railway.source && typeof railway.source === "object" && !Array.isArray(railway.source) ? railway.source : {};
   const treeDxRoot = resolve(workspaceRoot ?? tenantRoot, "packages", "treedx");
   const configuredMode = typeof railway.sourceMode === "string" ? railway.sourceMode : null;
+  if (scope === "staging" && configuredMode === "image") {
+    throw new Error("public-treedx-node-01: API Railway staging services must use GitHub Dockerfile source builds (configured sourceMode image is not allowed).");
+  }
   const sourceMode = scope === "prod" ? "image" : configuredMode === "git" || configuredMode === "image" ? configuredMode : "git";
   const repository = typeof railway.sourceRepo === "string" ? railway.sourceRepo : typeof configuredSource.repository === "string" ? configuredSource.repository : typeof configuredSource.repo === "string" ? configuredSource.repo : readTreeseedPackageRepository(treeDxRoot) ?? "treeseed-ai/treedx";
   const sourceBranch = typeof railway.sourceBranch === "string" ? railway.sourceBranch : typeof configuredSource.branch === "string" ? configuredSource.branch : scope === "staging" ? "staging" : null;
@@ -774,8 +787,22 @@ function configuredPublicTreeDxRailwayServices({ tenantRoot, scope, deployConfig
   return Array.from({ length: bootstrapCount }, (_, offset) => {
     const index = offset + 1;
     const serviceName = `${PUBLIC_TREEDX_NODE_SERVICE_KEY_PREFIX}${String(index).padStart(2, "0")}`;
-    return {
+    const service = {
       key: serviceName,
+      serviceName,
+      sourceMode,
+      sourceRepo: sourceMode === "git" ? repository : null,
+      sourceBranch: sourceMode === "git" ? sourceBranch : null,
+      sourceCommit: sourceMode === "git" ? typeof railway.sourceCommit === "string" ? railway.sourceCommit : typeof configuredSource.commit === "string" ? configuredSource.commit : headCommitSafe(treeDxRoot) ?? headCommitSafe(tenantRoot) : null,
+      sourceRootDirectory: sourceMode === "git" ? sourceRootDirectory : null,
+      imageRef: sourceMode === "image" ? baseImageRef : null,
+      dockerfilePath: sourceMode === "git" ? railway.dockerfilePath ?? "/Dockerfile" : null,
+      buildCommand: sourceMode === "git" ? railway.buildCommand ?? null : null,
+      startCommand: sourceMode === "git" ? railway.startCommand ?? null : null
+    };
+    assertApiRailwaySourcePolicy(scope, service);
+    return {
+      key: service.key,
       instanceKey: serviceName,
       runnerIndex: null,
       serviceConfig: null,
@@ -783,20 +810,20 @@ function configuredPublicTreeDxRailwayServices({ tenantRoot, scope, deployConfig
       projectId: typeof railway.projectId === "string" ? railway.projectId : null,
       projectName,
       serviceId: typeof railway.serviceId === "string" && bootstrapCount === 1 ? railway.serviceId : null,
-      serviceName,
+      serviceName: service.serviceName,
       runnerId: null,
       rootDir: treeDxRoot,
       publicBaseUrl: null,
       railwayEnvironment,
-      buildCommand: sourceMode === "git" ? railway.buildCommand ?? null : null,
-      startCommand: sourceMode === "git" ? railway.startCommand ?? null : null,
-      imageRef: sourceMode === "image" ? baseImageRef : null,
-      sourceMode,
-      sourceRepo: sourceMode === "git" ? repository : null,
-      sourceBranch: sourceMode === "git" ? sourceBranch : null,
-      sourceCommit: sourceMode === "git" ? headCommitSafe(treeDxRoot) ?? headCommitSafe(tenantRoot) : null,
-      sourceRootDirectory: sourceMode === "git" ? sourceRootDirectory : null,
-      dockerfilePath: sourceMode === "git" ? railway.dockerfilePath ?? "/Dockerfile" : null,
+      buildCommand: service.buildCommand,
+      startCommand: service.startCommand,
+      imageRef: service.imageRef,
+      sourceMode: service.sourceMode,
+      sourceRepo: service.sourceRepo,
+      sourceBranch: service.sourceBranch,
+      sourceCommit: service.sourceCommit,
+      sourceRootDirectory: service.sourceRootDirectory,
+      dockerfilePath: service.dockerfilePath,
       healthcheckPath: railway.healthcheckPath ?? null,
       healthcheckTimeoutSeconds: railway.healthcheckTimeoutSeconds ?? null,
       healthcheckIntervalSeconds: railway.healthcheckIntervalSeconds ?? null,
@@ -870,25 +897,48 @@ function resolveRailwayServiceSourcePolicy({ tenantRoot, scope, serviceKey, serv
   const configuredMode = typeof service.railway?.sourceMode === "string" ? service.railway.sourceMode : null;
   const configuredSource = service.railway?.source && typeof service.railway.source === "object" && !Array.isArray(service.railway.source) ? service.railway.source : {};
   const configuredRepo = typeof service.railway?.sourceRepo === "string" ? service.railway.sourceRepo : typeof configuredSource.repository === "string" ? configuredSource.repository : typeof configuredSource.repo === "string" ? configuredSource.repo : null;
-  const packageRepository = configuredRepo ?? readTreeseedPackageRepository(serviceRoot) ?? readTreeseedPackageRepository(tenantRoot);
+  const serviceName = service.railway?.serviceName ?? null;
+  const packageRepository = configuredRepo ?? readTreeseedPackageRepository(serviceRoot) ?? readTreeseedPackageRepository(tenantRoot) ?? apiRailwayDefaultSourceRepo({ key: serviceKey, serviceName });
+  const dockerfilePath = service.railway?.dockerfilePath ?? apiRailwayDefaultDockerfilePath({ key: serviceKey, serviceName });
   const apiPackageSourceEligible = ["api", "operationsRunner"].includes(serviceKey);
+  if (scope === "staging" && isApiRailwaySourcePolicyService({ key: serviceKey, serviceName }) && (configuredMode === "image" || service.railway?.imageRef)) {
+    throw new Error(`${serviceName ?? serviceKey}: API Railway staging services must use GitHub Dockerfile source builds (configured image source is not allowed).`);
+  }
   const sourceMode = scope === "prod" ? "image" : scope === "staging" && apiPackageSourceEligible ? "git" : configuredMode === "git" || configuredMode === "image" ? configuredMode : imageRef ? "image" : "git";
   if (sourceMode !== "git") {
-    return {
+    const policy2 = {
       sourceMode: "image",
       sourceRepo: null,
       sourceBranch: null,
       sourceCommit: null,
       sourceRootDirectory: null
     };
+    assertApiRailwaySourcePolicy(scope, {
+      key: serviceKey,
+      serviceName,
+      imageRef,
+      dockerfilePath: null,
+      buildCommand: null,
+      startCommand: null,
+      ...policy2
+    });
+    return policy2;
   }
-  return {
+  const policy = {
     sourceMode: "git",
     sourceRepo: packageRepository,
     sourceBranch: typeof service.railway?.sourceBranch === "string" ? service.railway.sourceBranch : typeof configuredSource.branch === "string" ? configuredSource.branch : scope === "staging" ? "staging" : null,
-    sourceCommit: headCommitSafe(serviceRoot),
+    sourceCommit: typeof service.railway?.sourceCommit === "string" ? service.railway.sourceCommit : typeof configuredSource.commit === "string" ? configuredSource.commit : headCommitSafe(serviceRoot),
     sourceRootDirectory: typeof service.railway?.sourceRootDirectory === "string" ? service.railway.sourceRootDirectory : typeof configuredSource.rootDirectory === "string" ? configuredSource.rootDirectory : "."
   };
+  assertApiRailwaySourcePolicy(scope, {
+    key: serviceKey,
+    serviceName,
+    imageRef: null,
+    dockerfilePath,
+    ...policy
+  });
+  return policy;
 }
 function resolveRailwayCapacityProviderRoot(tenantRoot, service) {
   if (service.railway?.rootDir) {
@@ -1533,6 +1583,17 @@ async function syncRailwayServiceRuntimeConfigurationAfterDeploy(tenantRoot, ser
     serviceId: railwayService.id,
     variables: {
       TREESEED_SKIP_PACKAGE_PREPARE: "1",
+      ...["api", "operationsRunner"].includes(service.key) ? {
+        ...configuredEnvValue(env, "TREESEED_PLATFORM_RUNNER_SECRET") ? {
+          TREESEED_PLATFORM_RUNNER_SECRET: configuredEnvValue(env, "TREESEED_PLATFORM_RUNNER_SECRET")
+        } : {},
+        ...configuredEnvValue(env, "TREESEED_CREDENTIAL_SESSION_SECRET") ? {
+          TREESEED_CREDENTIAL_SESSION_SECRET: configuredEnvValue(env, "TREESEED_CREDENTIAL_SESSION_SECRET")
+        } : {},
+        ...configuredEnvValue(env, "TREESEED_WEB_SERVICE_SECRET") ? {
+          TREESEED_WEB_SERVICE_SECRET: configuredEnvValue(env, "TREESEED_WEB_SERVICE_SECRET")
+        } : {}
+      } : {},
       ...service.sourceMode === "git" ? {
         TREESEED_DEPLOY_SOURCE_MODE: "git",
         ...service.sourceRepo ? { TREESEED_DEPLOY_SOURCE_REPOSITORY: service.sourceRepo } : {},
@@ -1550,7 +1611,6 @@ async function syncRailwayServiceRuntimeConfigurationAfterDeploy(tenantRoot, ser
         TREESEED_MANAGER_ID: normalizeScope(service.scope),
         ...configuredEnvValue(env, "TREESEED_RAILWAY_API_TOKEN") ? { TREESEED_RAILWAY_API_TOKEN: configuredEnvValue(env, "TREESEED_RAILWAY_API_TOKEN") } : {},
         ...configuredEnvValue(env, "TREESEED_RAILWAY_WORKSPACE") ? { TREESEED_RAILWAY_WORKSPACE: configuredEnvValue(env, "TREESEED_RAILWAY_WORKSPACE") } : {},
-        ...configuredEnvValue(env, "TREESEED_PLATFORM_RUNNER_SECRET") ? { TREESEED_PLATFORM_RUNNER_SECRET: configuredEnvValue(env, "TREESEED_PLATFORM_RUNNER_SECRET") } : {},
         ...configuredEnvValue(env, "TREESEED_API_BASE_URL") || configuredEnvValue(env, "TREESEED_URL") ? {
           TREESEED_API_BASE_URL: configuredEnvValue(env, "TREESEED_API_BASE_URL") || configuredEnvValue(env, "TREESEED_URL")
         } : {}

package/dist/operations/services/railway-source-policy.d.ts

@@ -0,0 +1,19 @@
+export type TreeseedRailwaySourcePolicyScope = 'local' | 'staging' | 'prod';
+export type TreeseedRailwaySourcePolicyService = {
+    key?: string | null;
+    serviceName?: string | null;
+    sourceMode?: string | null;
+    sourceRepo?: string | null;
+    sourceBranch?: string | null;
+    sourceCommit?: string | null;
+    sourceRootDirectory?: string | null;
+    imageRef?: string | null;
+    dockerfilePath?: string | null;
+    buildCommand?: string | null;
+    startCommand?: string | null;
+};
+export declare function isApiRailwaySourcePolicyService(service: TreeseedRailwaySourcePolicyService): boolean;
+export declare function isImmutableRailwayImageRef(value: unknown): boolean;
+export declare function apiRailwayDefaultSourceRepo(service: TreeseedRailwaySourcePolicyService): "treeseed-ai/treedx" | "treeseed-ai/api" | null;
+export declare function apiRailwayDefaultDockerfilePath(service: TreeseedRailwaySourcePolicyService): "/Dockerfile.api" | "/Dockerfile.operations-runner" | "/Dockerfile" | null;
+export declare function assertApiRailwaySourcePolicy(scope: TreeseedRailwaySourcePolicyScope | string, service: TreeseedRailwaySourcePolicyService): void;

package/dist/operations/services/railway-source-policy.js

@@ -0,0 +1,66 @@
+function isApiRailwaySourcePolicyService(service) {
+  const key = String(service.key ?? "").trim();
+  const serviceName = String(service.serviceName ?? "").trim();
+  return key.startsWith("public-treedx-node-") || serviceName === "treeseed-api" || /^treeseed-api-operations-runner-\d+$/u.test(serviceName) || /^public-treedx-node-\d+$/u.test(serviceName);
+}
+function isImmutableRailwayImageRef(value) {
+  const imageRef = typeof value === "string" ? value.trim() : "";
+  if (!imageRef || !imageRef.includes(":")) return false;
+  const tag = imageRef.split(":").pop()?.trim() ?? "";
+  return Boolean(tag) && !["latest", "staging", "dev", "local"].includes(tag);
+}
+function apiRailwayDefaultSourceRepo(service) {
+  const serviceName = String(service.serviceName ?? "").trim();
+  if (serviceName === "treeseed-api" || /^treeseed-api-operations-runner-\d+$/u.test(serviceName)) return "treeseed-ai/api";
+  if (/^public-treedx-node-\d+$/u.test(serviceName) || String(service.key ?? "").startsWith("public-treedx-node-")) return "treeseed-ai/treedx";
+  return null;
+}
+function apiRailwayDefaultDockerfilePath(service) {
+  const serviceName = String(service.serviceName ?? "").trim();
+  if (serviceName === "treeseed-api") return "/Dockerfile.api";
+  if (/^treeseed-api-operations-runner-\d+$/u.test(serviceName)) return "/Dockerfile.operations-runner";
+  if (/^public-treedx-node-\d+$/u.test(serviceName) || String(service.key ?? "").startsWith("public-treedx-node-")) return "/Dockerfile";
+  return null;
+}
+function assertApiRailwaySourcePolicy(scope, service) {
+  if (!isApiRailwaySourcePolicyService(service)) return;
+  const normalizedScope = scope === "prod" ? "prod" : scope === "staging" ? "staging" : "local";
+  const label = service.serviceName ?? service.key ?? "Railway service";
+  if (normalizedScope === "staging") {
+    const issues = [
+      service.sourceMode === "git" ? null : "sourceMode must be git",
+      service.imageRef ? "imageRef must be empty" : null,
+      service.sourceRepo ? null : "sourceRepo must be set",
+      service.sourceBranch === "staging" ? null : "sourceBranch must be staging",
+      service.sourceRootDirectory ? null : "sourceRootDirectory must be set",
+      service.dockerfilePath ? null : "dockerfilePath must be set"
+    ].filter((issue) => Boolean(issue));
+    if (issues.length > 0) {
+      throw new Error(`${label}: API Railway staging services must use GitHub Dockerfile source builds (${issues.join("; ")}).`);
+    }
+    return;
+  }
+  if (normalizedScope === "prod") {
+    const issues = [
+      service.sourceMode === "image" ? null : "sourceMode must be image",
+      isImmutableRailwayImageRef(service.imageRef) ? null : "imageRef must be an immutable released image tag",
+      service.sourceRepo ? "sourceRepo must be empty" : null,
+      service.sourceBranch ? "sourceBranch must be empty" : null,
+      service.sourceCommit ? "sourceCommit must be empty" : null,
+      service.sourceRootDirectory ? "sourceRootDirectory must be empty" : null,
+      service.dockerfilePath ? "dockerfilePath must be empty" : null,
+      service.buildCommand ? "buildCommand must be empty" : null,
+      service.startCommand ? "startCommand must be empty" : null
+    ].filter((issue) => Boolean(issue));
+    if (issues.length > 0) {
+      throw new Error(`${label}: API Railway production services must use released Docker image sources (${issues.join("; ")}).`);
+    }
+  }
+}
+export {
+  apiRailwayDefaultDockerfilePath,
+  apiRailwayDefaultSourceRepo,
+  assertApiRailwaySourcePolicy,
+  isApiRailwaySourcePolicyService,
+  isImmutableRailwayImageRef
+};

package/dist/operations/services/repository-save-orchestrator.js

@@ -117,7 +117,7 @@ function npmCacheForCwd(cwd) {
   return cacheDir;
 }
 function npmWorkflowEnv(env = {}, cwd = process.cwd()) {
-  const npmCache = env.npm_config_cache ?? env.NPM_CONFIG_CACHE ?? process.env.npm_config_cache ?? process.env.NPM_CONFIG_CACHE ?? npmCacheForCwd(cwd);
+  const npmCache = env.npm_config_cache ?? env.NPM_CONFIG_CACHE ?? npmCacheForCwd(cwd);
   return withShortProcessTempEnv({
     ...env,
     NPM_CONFIG_CACHE: npmCache,
@@ -777,7 +777,7 @@ function applyPackageVersion(node, version) {
   return true;
 }
 function shouldSkipNetworkInstall() {
-  return process.env.TREESEED_SAVE_NPM_INSTALL_MODE === "skip";
+  return process.env.TREESEED_SAVE_NPM_INSTALL_MODE !== "allow";
 }
 function shouldSkipGitDependencySmoke(options) {
   return shouldSkipNetworkInstall() || process.env.TREESEED_GIT_DEPENDENCY_SMOKE === "skip" || options?.verifyMode === "skip";
@@ -948,6 +948,11 @@ function lockfileValidationCommand(node, options) {
   const args = rootWorkspaceInstall ? ["ci", "--ignore-scripts", "--plan"] : ["ci", "--ignore-scripts", "--plan", "--workspaces=false"];
   return { command: "npm", args };
 }
+function lockfileValidationTimeoutMs(node, options) {
+  const packageJson = node.packageJson ?? (existsSync(resolve(node.path, "package.json")) ? readJson(resolve(node.path, "package.json")) : null);
+  const rootWorkspaceInstall = node.path === options.root && Array.isArray(packageJson?.workspaces);
+  return rootWorkspaceInstall ? 18e5 : 6e5;
+}
 async function validateRepositoryLockfile(node, options) {
   if (!hasNpmLockfile(node.path)) {
     return { status: "skipped", command: null, issues: [], error: "no npm lockfile" };
@@ -973,7 +978,7 @@ async function validateRepositoryLockfile(node, options) {
     return { status: "skipped", command: commandText, issues: [], error: "disabled" };
   }
   try {
-    runCapturedCommand(node, options, "lockfile", command, args, { timeoutMs: 6e5, emitOutputOnSuccess: false });
+    runCapturedCommand(node, options, "lockfile", command, args, { timeoutMs: lockfileValidationTimeoutMs(node, options), emitOutputOnSuccess: false });
     const packageCount = npmLockfilePackageCount(node.path);
     const countText = packageCount === null ? "package-lock entries" : `${packageCount} package${packageCount === 1 ? "" : "s"}`;
     emitProgress(options, node, "lockfile", `Lockfile validation passed: ${countText} checked, 0 issues.`);
@@ -1124,7 +1129,8 @@ function pullRebaseFromOrigin(node, options, branch) {
     };
   }
   try {
-    runCapturedCommand(node, options, "rebase", "git", ["pull", "--rebase", "--recurse-submodules=no", "origin", branch]);
+    runCapturedCommand(node, options, "rebase", "git", ["fetch", "origin", `refs/heads/${branch}:refs/remotes/origin/${branch}`]);
+    runCapturedCommand(node, options, "rebase", "git", ["rebase", `refs/remotes/origin/${branch}`]);
     return {
       remoteBranchExisted: true,
       pulledRebase: true
@@ -1161,7 +1167,7 @@ function pushCurrentBranch(node, options, branch, tagName) {
 async function finishRepositorySavePublish(node, options, state, report, input) {
   const reference = input.reference ?? null;
   const tagName = input.tagName ?? reference?.tagName ?? null;
-  const shouldDeferPush = options.deferPushUntilVerified === true && node.id === ".";
+  const shouldDeferPush = options.deferPushUntilVerified === true;
   if (shouldDeferPush) {
     state.deferredPushes.push({
       node,
@@ -1828,6 +1834,7 @@ async function saveOneRepository(node, options, state) {
     return report;
   }
   report.committed = true;
+  report.commitSha = headCommit(node.path);
   const rebase = pullRebaseFromOrigin(node, options, branch);
   const verifyMode = options.verifyMode ?? "action-first";
   if (node.kind === "project" && node.path === options.root && Array.isArray(node.packageJson?.workspaces)) {

package/dist/platform/desired-state.js

@@ -652,9 +652,8 @@ function localDevelopmentResources(tenantRoot, environment, localContent) {
       dependencies: [composeId],
       spec: {
         mode: "local",
-        roles: ["api", "manager", "runner"],
-        volumePolicy: "shared-local",
-        healthEndpoint: "http://127.0.0.1:4783/healthz"
+        roles: ["manager", "runner"],
+        volumePolicy: "shared-local"
       },
       source: { type: "package-adapter", id: "@treeseed/agent" }
     },

package/dist/reconcile/builtin-adapters.js

@@ -3952,7 +3952,11 @@ async function syncRailwayEnvironmentForScope(input, { planOnly = false, service
         volumes: rendered.volumeNames,
         database: rendered.databaseName,
         scope,
-        serviceSourceModes: Object.fromEntries(effectiveIacInput.services.map((service) => [service.serviceName, service.sourceMode ?? null]))
+        serviceSourceModes: Object.fromEntries(effectiveIacInput.services.map((service) => [service.serviceName, service.sourceMode ?? null])),
+        serviceSourceRefs: Object.fromEntries(effectiveIacInput.services.map((service) => [
+          service.serviceName,
+          service.sourceMode === "git" && service.sourceRepo ? `github:${service.sourceRepo}:${service.sourceBranch ?? ""}:${service.sourceRootDirectory ?? ""}:${service.sourceCommit ?? ""}` : service.sourceMode === "image" && service.imageRef ? `image:${service.imageRef}` : null
+        ]))
       });
       if (!validation.ok && effectiveIacInput.database && !effectiveIacInput.database.useNativePostgres && railwayIacPlanDeletesResource(plan.changeSet, effectiveIacInput.database.serviceName)) {
         traceRailwayReconcile(topology.env, "sync:iac-native-postgres-adopt", `${project.name}/${environment.name}:${effectiveIacInput.database.serviceName}`);
@@ -3975,7 +3979,11 @@ async function syncRailwayEnvironmentForScope(input, { planOnly = false, service
           volumes: rendered.volumeNames,
           database: rendered.databaseName,
           scope,
-          serviceSourceModes: Object.fromEntries(effectiveIacInput.services.map((service) => [service.serviceName, service.sourceMode ?? null]))
+          serviceSourceModes: Object.fromEntries(effectiveIacInput.services.map((service) => [service.serviceName, service.sourceMode ?? null])),
+          serviceSourceRefs: Object.fromEntries(effectiveIacInput.services.map((service) => [
+            service.serviceName,
+            service.sourceMode === "git" && service.sourceRepo ? `github:${service.sourceRepo}:${service.sourceBranch ?? ""}:${service.sourceRootDirectory ?? ""}:${service.sourceCommit ?? ""}` : service.sourceMode === "image" && service.imageRef ? `image:${service.imageRef}` : null
+          ]))
         });
       }
       if (!validation.ok) {

package/dist/reconcile/providers/railway-iac.d.ts

@@ -28,6 +28,7 @@ export type TreeseedRailwayIacDatabase = {
 };
 export type TreeseedRailwayIacProjectInput = {
     tenantRoot: string;
+    scope?: string | null;
     projectName: string;
     projectId: string;
     environmentName: string;
@@ -61,6 +62,7 @@ export declare function validateRailwayIacChangeSet(changeSet: RailwayChangeSet
     database: string | null;
     scope: string;
     serviceSourceModes?: Record<string, string | null | undefined>;
+    serviceSourceRefs?: Record<string, string | null | undefined>;
 }): RailwayIacValidationResult;
 export declare function planRailwayIacProject(input: TreeseedRailwayIacProjectInput, rendered?: TreeseedRailwayIacRenderResult): Promise<RailwayIacPlanResponse>;
 export declare function applyRailwayIacProject(input: TreeseedRailwayIacProjectInput, rendered?: TreeseedRailwayIacRenderResult): Promise<RailwayIacApplyResponse>;

package/dist/reconcile/providers/railway-iac.js

@@ -1,6 +1,7 @@
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { runRailwayIac } from "railway/iac";
+import { assertApiRailwaySourcePolicy, isApiRailwaySourcePolicyService } from "../../operations/services/railway-source-policy.js";
 function js(value) {
   return JSON.stringify(value);
 }
@@ -97,7 +98,13 @@ function renderPostgresEnv() {
     ["RAILWAY_DEPLOYMENT_DRAINING_SECONDS", js("60")]
   ]);
 }
+function normalizeIacScope(input) {
+  if (input.scope === "prod" || input.scope === "staging") return input.scope;
+  const environmentName = String(input.environmentName ?? "").trim().toLowerCase();
+  return environmentName === "production" || environmentName === "prod" ? "prod" : environmentName === "staging" ? "staging" : "local";
+}
 function renderRailwayIacProject(input) {
+  const scope = normalizeIacScope(input);
   const region = input.region?.trim() || "us-east4-eqdc4a";
   const tempParent = resolve(input.tenantRoot, ".treeseed", "tmp");
   mkdirSync(tempParent, { recursive: true });
@@ -145,6 +152,7 @@ function renderRailwayIacProject(input) {
     }
   }
   input.services.forEach((service, index) => {
+    assertApiRailwaySourcePolicy(scope, service);
     const serviceVar = id("svc", index);
     const invalidVariables = validateGeneratedVariables(service);
     if (invalidVariables.length > 0) {
@@ -232,7 +240,15 @@ function validateRailwayIacChangeSet(changeSet, desiredNames) {
   const created = new Set((changeSet?.changes ?? []).filter((change) => change.kind === "resource.create").map((change) => changeName(change)));
   for (const change of changeSet?.changes ?? []) {
     const name = changeName(change);
-    const sourceMode = desiredNames.serviceSourceModes?.[name] ?? desiredNames.serviceSourceModes?.[name.replace(/^(service|database)\./u, "")] ?? null;
+    const serviceName = name.replace(/^(service|database)\./u, "");
+    const sourceMode = desiredNames.serviceSourceModes?.[name] ?? desiredNames.serviceSourceModes?.[serviceName] ?? null;
+    const sourceRef = desiredNames.serviceSourceRefs?.[name] ?? desiredNames.serviceSourceRefs?.[serviceName] ?? null;
+    const sourceChanged = change.kind === "resource.update" && isRailwaySourceChange(change);
+    const imageSourceChange = sourceChanged && isRailwayImageSourceChange(change);
+    const gitSourceChange = sourceChanged && isRailwayGitSourceChange(change);
+    const desiredGitSource = sourceMode === "git" && typeof sourceRef === "string" && sourceRef.startsWith("github:");
+    const desiredImageSource = sourceMode === "image" && typeof sourceRef === "string" && sourceRef.startsWith("image:");
+    const apiPolicyService = isApiRailwaySourcePolicyService({ serviceName });
     if (change.kind === "resource.delete") {
       destructiveChanges.push(change.summary);
       blockedReasons.push(`Railway IaC plan would delete resource ${name || change.summary}; hosting reconciliation only updates or creates resources. Use the explicit destroy workflow for deletions.`);
@@ -240,12 +256,24 @@ function validateRailwayIacChangeSet(changeSet, desiredNames) {
         blockedReasons.push(`Railway IaC plan would delete desired resource ${name}.`);
       }
     }
-    if (desiredNames.scope === "staging" && change.kind === "resource.update" && isRailwayImageSourceChange(change) && (!sourceMode || sourceMode === "image")) {
+    if (desiredNames.scope === "staging" && sourceChanged && apiPolicyService && sourceMode === "git" && !gitSourceChange && !desiredGitSource) {
+      blockedReasons.push(`Railway IaC plan would change staging API resource ${name} source without confirming a GitHub source.`);
+    }
+    if (desiredNames.scope === "staging" && sourceChanged && imageSourceChange && !(apiPolicyService && sourceMode === "git" && (gitSourceChange || desiredGitSource))) {
       blockedReasons.push(`Railway IaC plan would switch staging resource ${name} to an image source.`);
     }
-    if (desiredNames.scope === "prod" && change.kind === "resource.update" && isRailwayGitSourceChange(change) && (!sourceMode || sourceMode === "git")) {
+    if (desiredNames.scope === "staging" && sourceChanged && (!sourceMode || sourceMode === "image")) {
+      blockedReasons.push(`Railway IaC plan would apply an image-backed desired source to staging resource ${name}.`);
+    }
+    if (desiredNames.scope === "prod" && sourceChanged && apiPolicyService && sourceMode === "image" && !imageSourceChange && !desiredImageSource) {
+      blockedReasons.push(`Railway IaC plan would change production API resource ${name} source without confirming an image source.`);
+    }
+    if (desiredNames.scope === "prod" && sourceChanged && gitSourceChange) {
       blockedReasons.push(`Railway IaC plan would switch production resource ${name} to a Git source.`);
     }
+    if (desiredNames.scope === "prod" && sourceChanged && (!sourceMode || sourceMode === "git")) {
+      blockedReasons.push(`Railway IaC plan would apply a Git-backed desired source to production resource ${name}.`);
+    }
   }
   return {
     ok: blockedReasons.length === 0,