@treeseed/sdk 0.10.22 → 0.10.24

package/dist/operations/services/project-platform.js

@@ -3,6 +3,7 @@ import { spawnSync } from "node:child_process";
 import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, extname, join, resolve } from "node:path";
+import { elapsedMs, formatTimingMarkdown, formatTimingSummary } from "../../timing.js";
 import {
   createControlPlaneReporter
 } from "../../control-plane.js";
@@ -52,6 +53,39 @@ const PROCESSING_PLATFORM_BOOTSTRAP_SYSTEMS = ["api", "agents"];
 function stableHash(value) {
   return createHash("sha256").update(value).digest("hex");
 }
+function recordTiming(timings, name, startMs, status = "success", metadata) {
+  const entry = {
+    name,
+    durationMs: elapsedMs(startMs),
+    status,
+    ...metadata ? { metadata } : {}
+  };
+  timings.push(entry);
+  return entry;
+}
+async function timedPhase(timings, name, run, metadata) {
+  const startMs = performance.now();
+  try {
+    const result = await Promise.resolve(run());
+    recordTiming(timings, name, startMs, "success", metadata);
+    return result;
+  } catch (error) {
+    recordTiming(timings, name, startMs, "failed", {
+      ...metadata ?? {},
+      error: error instanceof Error ? error.message : String(error)
+    });
+    throw error;
+  }
+}
+function writeProviderTimingSummary(options, timings) {
+  const text = formatTimingSummary(timings);
+  options.write?.(text);
+  const summaryPath = String(options.env?.TREESEED_PROVIDER_TIMING_SUMMARY_PATH ?? process.env.TREESEED_PROVIDER_TIMING_SUMMARY_PATH ?? "").trim();
+  if (!summaryPath) {
+    return;
+  }
+  writeFileSync(summaryPath, formatTimingMarkdown(timings), { flag: "a" });
+}
 function inferEnvironmentFromBranch(tenantRoot) {
   const branch = currentManagedBranch(tenantRoot);
   if (branch === STAGING_BRANCH) {
@@ -1024,25 +1058,30 @@ async function publishContent(options, reporter, publishOptions = {}) {
   }
 }
 async function provisionProjectPlatform(options) {
+  const timings = [];
   const reporter = resolveReporter(options.tenantRoot, options.reporter);
   const target = createPersistentDeployTarget(options.scope === "local" ? "staging" : options.scope);
   const siteConfig = loadCliDeployConfig(options.tenantRoot);
   const bootstrapSystems = resolveProjectPlatformBootstrapSystems(options, siteConfig);
   const selectedSystems = new Set(bootstrapSystems);
   const env = { ...process.env, ...options.env ?? {} };
-  const summary = await reconcileTreeseedTarget({
+  const summary = await timedPhase(timings, "provision:reconcile", () => reconcileTreeseedTarget({
     tenantRoot: options.tenantRoot,
     target,
     env,
-    systems: bootstrapSystems
-  });
-  const verification = await collectTreeseedReconcileStatus({
+    systems: bootstrapSystems,
+    write: options.write
+  }));
+  timings.push(...summary.timings ?? []);
+  const verification = await timedPhase(timings, "provision:collect-reconcile-status", () => collectTreeseedReconcileStatus({
     tenantRoot: options.tenantRoot,
     target,
     env,
     systems: bootstrapSystems
+  }));
+  await timedPhase(timings, "provision:ensure-wrangler-config", () => {
+    ensureGeneratedWranglerConfig(options.tenantRoot, { target });
   });
-  ensureGeneratedWranglerConfig(options.tenantRoot, { target });
   const shouldValidateRailway = selectedSystems.has("api") || selectedSystems.has("agents");
   const railwayValidation = shouldValidateRailway ? options.scope === "local" ? validateRailwayServiceConfiguration(options.tenantRoot, options.scope) : validateRailwayDeployPrerequisites(options.tenantRoot, options.scope, { env }) : { services: [] };
   const railwaySchedules = [];
@@ -1087,6 +1126,22 @@ async function provisionProjectPlatform(options) {
       locator: state.lastDeployedUrl ?? null,
       metadata: { workerName: state.workerName }
     },
+    {
+      environment: options.scope,
+      provider: "cloudflare",
+      resourceKind: "kv",
+      logicalName: state.kvNamespaces?.FORM_GUARD_KV?.name ?? "form-guard",
+      locator: state.kvNamespaces?.FORM_GUARD_KV?.id ?? null,
+      metadata: state.kvNamespaces?.FORM_GUARD_KV ?? {}
+    },
+    {
+      environment: options.scope,
+      provider: "cloudflare",
+      resourceKind: "turnstile-widget",
+      logicalName: state.turnstileWidgets?.formGuard?.name ?? "form-guard-turnstile",
+      locator: state.turnstileWidgets?.formGuard?.sitekey ?? null,
+      metadata: state.turnstileWidgets?.formGuard ?? {}
+    },
     {
       environment: options.scope,
       provider: "cloudflare",
@@ -1157,6 +1212,7 @@ async function provisionProjectPlatform(options) {
       target: deployTargetLabel(target),
       summary,
       verification,
+      timings,
       reconcileActions: summary.results.map((result) => ({
         unitId: result.unit.unitId,
         action: result.action,
@@ -1174,6 +1230,7 @@ async function provisionProjectPlatform(options) {
     target: deployTargetLabel(target),
     summary,
     verification,
+    timings,
     railway: {
       services: railwayValidation.services.map((service) => service.key),
       schedules: railwaySchedules,
@@ -1182,6 +1239,8 @@ async function provisionProjectPlatform(options) {
   };
 }
 async function deployProjectPlatform(options) {
+  const timings = [];
+  const deployStartMs = performance.now();
   const reporter = resolveReporter(options.tenantRoot, options.reporter);
   const commitSha = currentCommit(options.tenantRoot);
   const branchName = currentRef(options.tenantRoot);
@@ -1200,7 +1259,8 @@ async function deployProjectPlatform(options) {
     metadata: { scope: options.scope }
   });
   if (!options.skipProvision) {
-    await provisionProjectPlatform({ ...options, reporter, bootstrapSystems });
+    const provision = await timedPhase(timings, "deploy:provision", () => provisionProjectPlatform({ ...options, reporter, bootstrapSystems }));
+    timings.push(...provision.timings ?? []);
   }
   const nodes = [];
   let cloudflareContext = null;
@@ -1319,7 +1379,7 @@ async function deployProjectPlatform(options) {
       }
     });
   }
-  await runTreeseedBootstrapDag({ nodes, execution });
+  await runTreeseedBootstrapDag({ nodes, execution, write, timings });
   const serviceResults = selectedRailwayServiceKeys.map((serviceKey) => serviceResultsByKey.get(serviceKey)).filter(Boolean);
   if (options.scope !== "local" && !options.dryRun && (selectedSystems.has("web") || serviceResults.length > 0)) {
     finalizeDeploymentState(options.tenantRoot, {
@@ -1342,8 +1402,11 @@ async function deployProjectPlatform(options) {
       scheduleVerification: railwayScheduleVerification
     });
   }
-  const monitor = await monitorProjectPlatform({ ...options, reporter, bootstrapSystems });
-  const hostingRepair = await repairHostingAfterSuccessfulDeploy(options, bootstrapSystems);
+  const monitor = await timedPhase(timings, "deploy:monitor", () => monitorProjectPlatform({ ...options, reporter, bootstrapSystems }));
+  timings.push(...monitor.timings ?? []);
+  const hostingRepair = await timedPhase(timings, "deploy:hosting-repair", () => repairHostingAfterSuccessfulDeploy(options, bootstrapSystems));
+  recordTiming(timings, "deploy:total", deployStartMs);
+  writeProviderTimingSummary(options, timings);
   await reportDeployment(reporter, {
     environment: options.scope,
     deploymentKind: "code",
@@ -1355,7 +1418,8 @@ async function deployProjectPlatform(options) {
       scope: options.scope,
       railway: options.scope === "local" ? [] : configuredRailwayServices(options.tenantRoot, options.scope).map((service) => service.key).filter((serviceKey) => serviceKey === "api" ? selectedSystems.has("api") : selectedSystems.has("agents")),
       monitor,
-      hostingRepair
+      hostingRepair,
+      timings
     },
     finishedAt: (/* @__PURE__ */ new Date()).toISOString()
   });
@@ -1364,7 +1428,8 @@ async function deployProjectPlatform(options) {
     scope: options.scope,
     monitor,
     hostingRepair,
-    serviceResults
+    serviceResults,
+    timings
   };
 }
 function resolveRailwayServiceDeployDependencies({
@@ -1381,6 +1446,7 @@ async function publishProjectContent(options) {
   return publishContent(options, reporter);
 }
 async function monitorProjectPlatform(options) {
+  const timings = [];
   const reporter = resolveReporter(options.tenantRoot, options.reporter);
   const env = { ...process.env, ...options.env ?? {} };
   const target = createPersistentDeployTarget(options.scope === "local" ? "staging" : options.scope);
@@ -1392,23 +1458,23 @@ async function monitorProjectPlatform(options) {
   const webProbeUrl = resolveImmediatePagesProbeUrl(siteConfig, state, target);
   const apiBaseUrl = resolveImmediateApiProbeUrl(siteConfig, state, target);
   const apiMonitorEndpoints = resolveApiMonitorEndpoints(siteConfig, apiBaseUrl);
-  const railwayResources = options.scope === "local" || !apiSelected && !agentsSelected ? { ok: true, skipped: true, reason: options.scope === "local" ? "local_scope" : "railway_not_selected" } : await verifyRailwayManagedResources(options.tenantRoot, options.scope, {
+  const railwayResources = options.scope === "local" || !apiSelected && !agentsSelected ? { ok: true, skipped: true, reason: options.scope === "local" ? "local_scope" : "railway_not_selected" } : await timedPhase(timings, "monitor:railway-resources", () => verifyRailwayManagedResources(options.tenantRoot, options.scope, {
     env,
     settleDeployments: true,
     onProgress: options.write
-  });
+  }));
   const skippedApiCheck = apiSelected ? { ok: false, skipped: true, reason: "api_url_unconfigured" } : { ok: true, skipped: true, reason: "api_not_selected" };
   const skippedAgentCheck = agentsSelected ? { ok: false, skipped: true, reason: "api_url_unconfigured" } : { ok: true, skipped: true, reason: "agents_not_selected" };
   const skippedD1Check = apiMonitorEndpoints.processingAgentApi ? { ok: true, skipped: true, reason: "processing_agent_api" } : skippedApiCheck;
   const checks = {
-    pages: await probeHttp(webProbeUrl, { attempts: 3, delayMs: 5e3 }),
-    apiHealth: apiSelected && apiMonitorEndpoints.apiHealth ? await probeHttp(apiMonitorEndpoints.apiHealth, { attempts: 8, delayMs: 1e4 }) : skippedApiCheck,
-    apiReady: apiSelected && apiMonitorEndpoints.apiReady ? await probeHttp(apiMonitorEndpoints.apiReady, { attempts: 8, delayMs: 1e4 }) : skippedApiCheck,
-    d1Health: apiSelected && apiMonitorEndpoints.d1Health ? await probeHttp(apiMonitorEndpoints.d1Health, { attempts: 8, delayMs: 1e4 }) : skippedD1Check,
-    agentHealth: agentsSelected && apiMonitorEndpoints.agentHealth ? await probeHttp(apiMonitorEndpoints.agentHealth, { attempts: 8, delayMs: 1e4 }) : skippedAgentCheck,
-    r2: options.dryRun ? { ok: true, skipped: true, reason: "dry_run" } : probeR2(options.tenantRoot, siteConfig, state, target),
-    queue: options.dryRun ? Promise.resolve({ ok: true, skipped: true, reason: "dry_run" }) : probeQueue(siteConfig, state),
-    scaleProbe: probeScaleConfiguration(siteConfig, state),
+    pages: await timedPhase(timings, "monitor:probe-pages", () => probeHttp(webProbeUrl, { attempts: 3, delayMs: 5e3 })),
+    apiHealth: apiSelected && apiMonitorEndpoints.apiHealth ? await timedPhase(timings, "monitor:probe-api-health", () => probeHttp(apiMonitorEndpoints.apiHealth, { attempts: 8, delayMs: 1e4 })) : skippedApiCheck,
+    apiReady: apiSelected && apiMonitorEndpoints.apiReady ? await timedPhase(timings, "monitor:probe-api-ready", () => probeHttp(apiMonitorEndpoints.apiReady, { attempts: 8, delayMs: 1e4 })) : skippedApiCheck,
+    d1Health: apiSelected && apiMonitorEndpoints.d1Health ? await timedPhase(timings, "monitor:probe-d1-health", () => probeHttp(apiMonitorEndpoints.d1Health, { attempts: 8, delayMs: 1e4 })) : skippedD1Check,
+    agentHealth: agentsSelected && apiMonitorEndpoints.agentHealth ? await timedPhase(timings, "monitor:probe-agent-health", () => probeHttp(apiMonitorEndpoints.agentHealth, { attempts: 8, delayMs: 1e4 })) : skippedAgentCheck,
+    r2: options.dryRun ? { ok: true, skipped: true, reason: "dry_run" } : timedPhase(timings, "monitor:probe-r2", () => probeR2(options.tenantRoot, siteConfig, state, target)),
+    queue: options.dryRun ? Promise.resolve({ ok: true, skipped: true, reason: "dry_run" }) : timedPhase(timings, "monitor:probe-queue", () => probeQueue(siteConfig, state)),
+    scaleProbe: await timedPhase(timings, "monitor:probe-scale", () => probeScaleConfiguration(siteConfig, state)),
     railwayResources,
     readiness: state.readiness,
     apiMonitor: {
@@ -1448,14 +1514,16 @@ ${failedChecks.join("\n")}`);
     metadata: {
       mode: "monitor",
       target: deployTargetLabel(target),
-      checks: resolvedChecks
+      checks: resolvedChecks,
+      timings
     },
     finishedAt: (/* @__PURE__ */ new Date()).toISOString()
   });
   return {
     ok,
     target: deployTargetLabel(target),
-    checks: resolvedChecks
+    checks: resolvedChecks,
+    timings
   };
 }
 async function syncControlPlaneState(options) {

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

@@ -1295,7 +1295,8 @@ async function ensureRailwayServiceVolume({
   if (!volume) {
     volume = await createReplacementVolume();
   }
-  if (volume.name && volume.name !== name) {
+  const desiredNameInUse = volumes.some((candidate) => candidate.id !== volume?.id && candidate.name === name);
+  if (volume.name && volume.name !== name && !desiredNameInUse) {
     try {
       volume = await updateRailwayVolumeName({ volumeId: volume.id, name, env, fetchImpl }) ?? { ...volume, name };
     } catch (error) {

package/dist/operations/services/railway-deploy.d.ts

@@ -6,9 +6,10 @@ export declare function deriveRailwayMarketOperationsRunnerVolumeName(serviceNam
 export declare function railwayServiceRuntimeStartCommand(service: any): any;
 export declare function parseRailwayJsonOutput(output: any): any;
 export declare function collectRailwayDeploymentStatusChecks(statusPayload: any, scope: any, services: any): any;
-export declare function listRailwayServiceVolumesWithCli({ cwd, serviceId, environmentId, name, mountPath, env, }: {
+export declare function listRailwayServiceVolumesWithCli({ cwd, serviceId, serviceName, environmentId, name, mountPath, env, }: {
     cwd: any;
     serviceId: any;
+    serviceName: any;
     environmentId: any;
     name: any;
     mountPath: any;
@@ -30,18 +31,47 @@ export declare function runRailway(args: any, { cwd, capture, allowFailure, inpu
     retryAttempts?: number | undefined;
     retryDelayMs?: number | undefined;
 }): import("child_process").SpawnSyncReturns<string> | null;
-export declare function waitForRailwayManagedDeploymentsSettled(tenantRoot: any, scope: any, { services, env, timeoutMs, pollMs, onProgress, }?: {
+export declare function waitForRailwayManagedDeploymentsSettled(tenantRoot: any, scope: any, { services, env, timeoutMs, pollMs, fetchImpl, onProgress, }?: {
     services?: unknown[] | undefined;
     env?: NodeJS.ProcessEnv | undefined;
     timeoutMs?: number | undefined;
     pollMs?: number | undefined;
+    fetchImpl?: typeof fetch | undefined;
 }): Promise<{
+    ok: boolean;
+    checks: {
+        type: string;
+        service: any;
+        serviceName: any;
+        environment: string;
+        ok: boolean;
+        status: string;
+        settle: {
+            durationMs: number;
+            pollCount: number;
+            finalStatus: string;
+        };
+        message: string;
+    }[];
+    settle?: undefined;
+    message?: undefined;
+} | {
     ok: boolean;
     checks: any;
+    settle: {
+        durationMs: number;
+        pollCount: number;
+        status: string;
+    };
     message?: undefined;
 } | {
     ok: boolean;
     checks: any;
+    settle: {
+        durationMs: number;
+        pollCount: number;
+        status: string;
+    };
     message: string;
 }>;
 export declare function setRailwaySecretVariable({ cwd, service, environment, key, value, env, capture, allowFailure }: {

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

@@ -24,6 +24,7 @@ import {
   resolveRailwayWorkspaceContext,
   upsertRailwayVariables
 } from "./railway-api.js";
+import { elapsedMs, formatDurationMs } from "../../timing.js";
 function normalizeScope(scope) {
   return scope === "prod" ? "prod" : scope === "staging" ? "staging" : "local";
 }
@@ -171,6 +172,26 @@ function collectRailwayDeploymentStatusChecks(statusPayload, scope, services) {
       };
     }
     const deployment = instance.latestDeployment ?? null;
+    if (!deployment) {
+      return {
+        type: "deployment-status",
+        service: service.key,
+        serviceName: service.serviceName,
+        environment: normalizeRailwayEnvironmentName(environment.name),
+        ok: true,
+        skipped: true,
+        status: "no_active_deployment",
+        observed: {
+          status: null,
+          deploymentId: null,
+          deploymentCreatedAt: null,
+          deploymentStopped: null,
+          instanceStatuses: [],
+          volumeMounts: []
+        },
+        message: `Railway service ${service.serviceName} has no active deployment to wait for.`
+      };
+    }
     const status = String(deployment?.status ?? "").trim().toUpperCase();
     const instanceStatuses = Array.isArray(deployment?.instances) ? deployment.instances.map((entry) => String(entry?.status ?? "").trim()).filter(Boolean) : [];
     const ok = railwayStatusDeploymentSettled(status);
@@ -183,6 +204,8 @@ function collectRailwayDeploymentStatusChecks(statusPayload, scope, services) {
       status: status || "missing_deployment",
       observed: {
         status: status || null,
+        deploymentId: deployment?.id ?? null,
+        deploymentCreatedAt: deployment?.createdAt ?? null,
         deploymentStopped: deployment?.deploymentStopped ?? null,
         instanceStatuses,
         volumeMounts: Array.isArray(deployment?.meta?.volumeMounts) ? deployment.meta.volumeMounts : []
@@ -191,7 +214,7 @@ function collectRailwayDeploymentStatusChecks(statusPayload, scope, services) {
     };
   });
 }
-function normalizeRailwayCliVolume(value, { serviceId, environmentId, fallbackName, fallbackMountPath }) {
+function normalizeRailwayCliVolume(value, { serviceId, serviceName, environmentId, fallbackName, fallbackMountPath }) {
   if (!value || typeof value !== "object") {
     return null;
   }
@@ -200,6 +223,10 @@ function normalizeRailwayCliVolume(value, { serviceId, environmentId, fallbackNa
   if (!id) {
     return null;
   }
+  const listedServiceName = typeof record.serviceName === "string" && record.serviceName.trim() ? record.serviceName.trim() : "";
+  if (listedServiceName && serviceName && listedServiceName !== serviceName) {
+    return null;
+  }
   const name = typeof record.name === "string" && record.name.trim() ? record.name.trim() : fallbackName;
   const mountPath = typeof record.mountPath === "string" && record.mountPath.trim() ? record.mountPath.trim() : fallbackMountPath;
   const sizeMb = typeof record.sizeMB === "number" ? record.sizeMB : null;
@@ -228,6 +255,7 @@ function normalizeRailwayCliVolumeList(value, options) {
 function listRailwayServiceVolumesWithCli({
   cwd,
   serviceId,
+  serviceName,
   environmentId,
   name,
   mountPath,
@@ -244,6 +272,7 @@ function listRailwayServiceVolumesWithCli({
   }
   return normalizeRailwayCliVolumeList(parseRailwayJsonOutput(listResult.stdout ?? ""), {
     serviceId,
+    serviceName,
     environmentId,
     fallbackName: name,
     fallbackMountPath: mountPath
@@ -468,8 +497,10 @@ async function waitForRailwayManagedDeploymentsSettled(tenantRoot, scope, {
   env = process.env,
   timeoutMs = 6e5,
   pollMs = 15e3,
+  fetchImpl = fetch,
   onProgress
 } = {}) {
+  const startMs = performance.now();
   const deadline = Date.now() + timeoutMs;
   const projectId = services.find((service) => typeof service.projectId === "string" && service.projectId.trim())?.projectId ?? null;
   if (!projectId) {
@@ -482,6 +513,11 @@ async function waitForRailwayManagedDeploymentsSettled(tenantRoot, scope, {
         environment: resolveRailwayEnvironmentForScope(scope),
         ok: false,
         status: "missing_project",
+        settle: {
+          durationMs: elapsedMs(startMs),
+          pollCount: 0,
+          finalStatus: "missing_project"
+        },
         message: `Railway deployment status for ${service.serviceName} cannot be checked without a project id.`
       }))
     };
@@ -489,12 +525,15 @@ async function waitForRailwayManagedDeploymentsSettled(tenantRoot, scope, {
   let checks = [];
   let lastError = null;
   let lastSummary = "";
+  let pollCount = 0;
   for (; ; ) {
     lastError = null;
+    pollCount += 1;
     try {
       const statusPayload = await fetchRailwayProjectDeploymentStatus({
         projectId,
-        env
+        env,
+        fetchImpl
       });
       checks = collectRailwayDeploymentStatusChecks(statusPayload, scope, services);
     } catch (error) {
@@ -506,28 +545,63 @@ async function waitForRailwayManagedDeploymentsSettled(tenantRoot, scope, {
         environment: resolveRailwayEnvironmentForScope(scope),
         ok: false,
         status: "status_error",
+        settle: {
+          durationMs: elapsedMs(startMs),
+          pollCount,
+          finalStatus: "status_error"
+        },
         message: error instanceof Error ? error.message : String(error)
       }));
     }
     const summary = formatRailwayDeploymentStatusSummary(scope, checks);
-    if (summary !== lastSummary || !checks.every((entry) => entry.ok === true)) {
-      onProgress?.(summary, "stdout");
-      lastSummary = summary;
+    const progress = `${summary} poll=${pollCount} elapsed=${formatDurationMs(elapsedMs(startMs))}`;
+    if (progress !== lastSummary || !checks.every((entry) => entry.ok === true || entry.skipped === true)) {
+      onProgress?.(progress, "stdout");
+      lastSummary = progress;
     }
-    if (checks.every((entry) => entry.ok === true)) {
-      return { ok: true, checks };
+    if (checks.every((entry) => entry.ok === true || entry.skipped === true)) {
+      return {
+        ok: true,
+        checks: checks.map((check) => ({
+          ...check,
+          settle: {
+            durationMs: elapsedMs(startMs),
+            pollCount,
+            finalStatus: check.status,
+            fastSkipped: check.skipped === true
+          }
+        })),
+        settle: {
+          durationMs: elapsedMs(startMs),
+          pollCount,
+          status: checks.every((entry) => entry.skipped === true) ? "skipped" : "settled"
+        }
+      };
     }
     if (Date.now() >= deadline) {
       return {
         ok: false,
-        checks,
+        checks: checks.map((check) => ({
+          ...check,
+          settle: {
+            durationMs: elapsedMs(startMs),
+            pollCount,
+            finalStatus: check.status,
+            timeout: true
+          }
+        })),
+        settle: {
+          durationMs: elapsedMs(startMs),
+          pollCount,
+          status: "timeout"
+        },
         message: lastError instanceof Error ? lastError.message : "Railway deployments did not settle before the monitor timeout."
       };
     }
     await sleep(pollMs);
   }
 }
-async function fetchRailwayProjectDeploymentStatus({ projectId, env = process.env }) {
+async function fetchRailwayProjectDeploymentStatus({ projectId, env = process.env, fetchImpl = fetch }) {
   const payload = await railwayGraphqlRequest({
     query: `
 query TreeseedRailwayDeploymentStatus($projectId: String!) {
@@ -565,7 +639,8 @@ query TreeseedRailwayDeploymentStatus($projectId: String!) {
 }
 `.trim(),
     variables: { projectId },
-    env
+    env,
+    fetchImpl
   });
   return payload.data?.project ?? null;
 }
@@ -1294,6 +1369,7 @@ async function verifyRailwayManagedResources(tenantRoot, scope, {
     const settled = await waitForRailwayManagedDeploymentsSettled(tenantRoot, scope, {
       services: deploymentStatusServices.length > 0 ? deploymentStatusServices : services,
       env: effectiveEnv,
+      fetchImpl,
       timeoutMs: settleTimeoutMs,
       pollMs: settlePollMs,
       onProgress
@@ -1776,6 +1852,7 @@ async function ensureRailwayServiceVolumeWithCliFallback({
   const listResult = runRailway([...volumeArgs, "list", "--json"], cliOptions);
   const existingVolumes = normalizeRailwayCliVolumeList(parseRailwayJsonOutput(listResult.stdout ?? ""), {
     serviceId,
+    serviceName,
     environmentId,
     fallbackName: name,
     fallbackMountPath: mountPath
@@ -1787,6 +1864,7 @@ async function ensureRailwayServiceVolumeWithCliFallback({
     const createResult = runRailway([...volumeArgs, "add", "--mount-path", mountPath, "--json"], cliOptions);
     volume = normalizeRailwayCliVolume(parseRailwayJsonOutput(createResult.stdout ?? ""), {
       serviceId,
+      serviceName,
       environmentId,
       fallbackName: name,
       fallbackMountPath: mountPath
@@ -1810,6 +1888,7 @@ async function ensureRailwayServiceVolumeWithCliFallback({
     }
     const attachedVolume = (attachResult.status ?? 1) === 0 ? normalizeRailwayCliVolume(parseRailwayJsonOutput(attachResult.stdout ?? ""), {
       serviceId,
+      serviceName,
       environmentId,
       fallbackName: name,
       fallbackMountPath: mountPath
@@ -1833,21 +1912,6 @@ async function ensureRailwayServiceVolumeWithCliFallback({
     instance = volume.instances.find((entry) => entry.serviceId === serviceId && entry.environmentId === environmentId) ?? volume.instances[0] ?? null;
     updated = true;
   }
-  if (volume.name !== name || instance?.mountPath !== mountPath) {
-    const updateResult = runRailway([...volumeArgs, "update", "--volume", volume.id, "--name", name, "--mount-path", mountPath, "--json"], cliOptions);
-    const updatedVolume = normalizeRailwayCliVolume(parseRailwayJsonOutput(updateResult.stdout ?? ""), {
-      serviceId,
-      environmentId,
-      fallbackName: name,
-      fallbackMountPath: mountPath
-    });
-    volume = updatedVolume ?? {
-      ...volume,
-      name,
-      instances: volume.instances.map((entry) => ({ ...entry, mountPath }))
-    };
-    updated = true;
-  }
   const apiVolume = await waitForRailwayServiceVolumeMount({
     projectId,
     volumeId: volume.id,
@@ -1859,6 +1923,8 @@ async function ensureRailwayServiceVolumeWithCliFallback({
   });
   if (apiVolume) {
     volume = apiVolume;
+  } else {
+    throw new Error(`Railway volume ${name} was not attached to ${serviceName} at ${mountPath}.`);
   }
   return {
     volume,
@@ -1878,11 +1944,12 @@ async function waitForRailwayServiceVolumeMount({
 }) {
   for (let attempt = 0; attempt <= 24; attempt += 1) {
     const volumes = await listRailwayVolumes({ projectId, env });
-    const match = volumes.find(
-      (entry) => entry.id === volumeId || entry.name === volumeName || entry.instances.some(
+    const mounted = volumes.find(
+      (entry) => entry.instances.some(
         (instance) => instance.serviceId === serviceId && instance.environmentId === environmentId && instance.mountPath === mountPath
       )
     ) ?? null;
+    const match = mounted ?? volumes.find((entry) => entry.id === volumeId) ?? volumes.find((entry) => entry.name === volumeName) ?? null;
     if (match?.instances.some(
       (instance) => instance.serviceId === serviceId && instance.environmentId === environmentId && instance.mountPath === mountPath
     )) {

package/dist/operations/services/template-registry.js

@@ -11,6 +11,7 @@ import {
   cliPackageVersion,
   agentPackageVersion,
   corePackageVersion,
+  cliPackageRoot,
   localTemplateArtifactsRoot,
   sdkPackageVersion
 } from "./runtime-paths.js";
@@ -37,10 +38,31 @@ function listFiles(root) {
   return files;
 }
 function listTemplateArtifactIds() {
-  if (!existsSync(localTemplateArtifactsRoot)) {
-    return [];
+  const packagedIds = existsSync(localTemplateArtifactsRoot) ? readdirSync(localTemplateArtifactsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name) : [];
+  const localStarterIds = listLocalStarterArtifacts().map((entry) => entry.id);
+  return [.../* @__PURE__ */ new Set([...packagedIds, ...localStarterIds])].sort((left, right) => left.localeCompare(right, void 0, { sensitivity: "base" }));
+}
+const LOCAL_STARTER_ID_TO_DIRECTORY = {
+  "starter-research": "research",
+  "starter-engineering": "engineering",
+  "starter-information-hub": "information-hub"
+};
+function localStartersRoot() {
+  return resolve(cliPackageRoot, "..", "..", "starters");
+}
+function resolveLocalStarterArtifactRoot(id) {
+  const directory = LOCAL_STARTER_ID_TO_DIRECTORY[id];
+  if (!directory) {
+    return null;
   }
-  return readdirSync(localTemplateArtifactsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort((left, right) => left.localeCompare(right, void 0, { sensitivity: "base" }));
+  const artifactRoot = resolve(localStartersRoot(), directory);
+  return existsSync(resolve(artifactRoot, "template.config.json")) && existsSync(resolve(artifactRoot, "template")) ? artifactRoot : null;
+}
+function listLocalStarterArtifacts() {
+  return Object.keys(LOCAL_STARTER_ID_TO_DIRECTORY).map((id) => {
+    const artifactRoot = resolveLocalStarterArtifactRoot(id);
+    return artifactRoot ? { id, artifactRoot } : null;
+  }).filter((entry) => Boolean(entry));
 }
 function isTextFile(filePath) {
   return !/\.(png|jpe?g|gif|webp|ico|woff2?|ttf|eot|pdf|zip|gz)$/iu.test(filePath);
@@ -166,6 +188,14 @@ function materializeR2TemplateSource(product) {
   );
 }
 function resolveTemplateDefinitionPaths(product, options) {
+  const localStarterArtifactRoot = resolveLocalStarterArtifactRoot(product.id);
+  if (localStarterArtifactRoot) {
+    return {
+      artifactRoot: localStarterArtifactRoot,
+      manifestPath: resolve(localStarterArtifactRoot, "template.config.json"),
+      templateRoot: resolve(localStarterArtifactRoot, "template")
+    };
+  }
   if (existsSync(product.artifactManifestPath) && existsSync(product.templateRoot)) {
     return {
       artifactRoot: product.artifactRoot,

package/dist/platform/contracts.d.ts

@@ -283,6 +283,7 @@ export interface TreeseedDeployConfig {
     slug: string;
     siteUrl: string;
     contactEmail: string;
+    projectRoot?: string;
     hosting?: TreeseedHostingConfig;
     hub: TreeseedHubConfig;
     runtime: TreeseedRuntimeConfig;